Adobe Analytics Destination

Segment makes it easy to send your data to Adobe Analytics (and lots of other destinations). Once you've tracked your data through our open source libraries we'll translate and route your data to Adobe Analytics in the format they understand. Learn more about how to use Adobe Analytics with Segment.

Getting Started

After you toggle on Adobe Analytics (formerly known as Omniture/Sitecatalyst) in Segment, you can start sending data to a report suite. You can send data with any of our libraries. When you send events via our mobile SDKs or server-side libraries, we translate that data into XML format and pass it to Adobe Analytics’ Data Insertion API.

Our server-side Adobe Analytics destination provides support for Adobe Mobile Services “states”, “actions”, and lifecycle events, metrics, and dimensions.

Events tracked in client-side javascript are sent directly from the browser using Adobe Analytics’ Appmeasurement.js library by default. However, you may enable the Cloud-Based Connection Mode in the Segment app if you would prefer to send data via our servers.

The following documentation provides detailed explanation of how both destination components work (Device-Based and Cloud-Based). For FAQs relating to client vs server-side tracking, unique users, identifiers, etc, please be sure to view the bottom of this page!


Device-Based (data sent via analytics.js)

Initialization

When using Adobe Analytics through analytics.js, we will check if you already have global properties such as window.s_account or any properties on the window.s object and use them. However, in the absence of any of these values, we will fallback on the Report Suite ID, Tracking Server URL, and Tracking Server Secure URL (optional) you have defined in the destination settings inside Segment.

Once these required properties are set, we will load appmeasurement.js version 1.6.

Marketing Cloud Visitor ID Service

If you’d like to use Adobe’s Marketing Cloud Visitor ID Service, please provide Segment with your Marketing Cloud Organization ID in the advanced options inside Segment.

Our analytics.js destination will load their visitorAPI.js library, but will not initialize it unless you provide your Marketing Cloud Organization ID. If you do, we will set window.s.visitor with the return value from window.Visitor.getInstance(<Your Marketing Cloud Org Id>). See their documentation for more information.

Note: We load visitorAPI.js in the same script as appmeasurement.js because Adobe Analytics requires synchronous execution of the two scripts. Using the visitor API is optional but for those who do, we make it available on the page.

Page

By default, the Segment snippet includes an empty page call. When page is called, there’s a few things that will happen:

  1. Set window.s.pageName to whatever the name of the page call was. This means that by default, the Segment .page() call will set this property as undefined since no parameters were passed. If you include a name such as .page('Home'), we will set window.s.pageName to 'Home'.

    Note: If no name is passed, Adobe Analytics will by default fallback to displaying the url as the name of the page.

  2. Set window.s.events to the name from your .page(<name>) call

  3. Check if page call is associated with a userId from a previous .identify() call. If so, we will set the userId as window.s.visitorID.

    IMPORTANT: Note that Adobe Analytics does not support setting vistorID if you are sending a timestamped hit. So we will only set window.s.visitorID if your Timestamp Option is disabled and a userId exists on the event.

  4. Check for some common properties such as the following and set them on the window.s object:

    • channel
    • campaign
    • state
    • zip

    First respect the properties you have sent via the .page() call. Thus an example page call in order to set the four properties above would be:

    analytics.page({
     channel: 'Laptops',
     campaign: '0813',
     state: 'RI',
     zip: '02818'
    });
    

    For campaign, we will respect our spec and check context.campaign.name first before checking properties.campaign.

    Alternatively, if you had already set any of these four properties on your existing Adobe Analytics instance on the page (window.s.channel, window.s.campaign, etc.), we will fallback on that as the default value. This allows you easily set a default values for all your web pages but be able to programmatically change them per page if needed.

  5. If your Timestamp Option is either Timestamp Enabled or Timestamp Optional, we will attach the timestamp to window.s.timestamp. Please make sure that this setting is inline with your actual timestamp setting inside Adobe Analytics for the same Report Suite ID.

  6. Check if any of the page call’s properties have been mapped to any custom Adobe Analytics variables such as eVar, props, and hVar.

    Given the mapping setting below:

    If you call the following page call:

    analytics.page({
     browser: 'chrome',
     searchTerm: 'swim shorts',
     section: 'swimwear'
    });
    

    Set the following properties on the window.s object:

    • window.s.prop1 = 'chrome'
    • window.s.eVar7 = 'swim shorts'
    • window.s.eVar3 will be set to the url of the page where the call was made (.page() automatically sets a url property)
    • window.s.hier1 = 'swimwear'

7) Finally we will flush the pageview request to Adobe Analytics using window.s.t().

Track

Required Prerequisite Steps

Event tracking for Adobe Analytics through Segment requires you to predefine which events you want to collect.

You must predefine in both Adobe Analytics and Segment destination settings UI a list of .track() events you want to send and which properties you want to send as custom variables.

This means that you must map each event and property to a corresponding Adobe Analytics event, prop, or eVar.

Here is an example of how you might map the custom variables in Segment:

Given the settings above, if you make a sample .track() call below:

analytics.track('Watched Video', {
  plan: 'free',
  videoName: 'The Uptick'
});

The following will happen:

  1. Check if the Segment event name, 'Watched Video', is mapped in your Segment settings. If it is, set window.s.linkTrackEvents and window.s.events to its corresponding Adobe Analytics event name, 'event1'. If no matching event name is found in the Segment settings, do nothing and abort.

  2. Attach timestamp to window.s.timestamp if your Timestamp Option setting inside Segment is either Timestamp Enabled or Timestamp Optional.

  3. Update common variables such as channel, campaign, state, zip if their corresponding properties were included in the event or on your window.s object.

  4. Check if the Segment event name, Watched Video is mapped to an eVar. Since it is in the example case above, set window.s.eVar3 as 'Watched Video'.

  5. Check if any of the properties are mapped to either a prop, eVar, or hVar. Thus for the example above, set window.s.prop1 as 'free' and window.s.eVar4 as 'The Uptick'.

  6. Automatically try to set window.s.pageName to the following values, in order of precedence:

    • properties.pageName (for backward compatibility)
    • options.pageName (if you already have window.s.pageName defined on the web page)
    • context.page.title (which is automatically tracked by our analytics.js library)

    Since context.page.title will always be populated, at the very minimum window.s.pageName will always be set to the value inside your <title> tag of the page where the .track() call was fired.

  7. Set window.s.linkTrackVars, which is a joined string of variable keys delimited by a comma. The example above would produce a value of 'eVar3,events,pageName,timestamp,eVar3,prop1'. This tells Adobe Analytics which properties on the window.s object they should send along with this event.

  8. Finally, we will flush the request to Adobe Analytics via window.s.tl(true, 'o', 'Watched Video')

    Note: true sets a 500ms delay to give your browser time to flush the event. It also signifies to Adobe that this event is something other than a href link. The 'o' stands for 'Other', as opposed to 'd' for 'Downloads' and 'e' for 'Exit Links'. The final parameter is the link name you will see in reports inside Adobe Analytics.

Ecommerce Events

The Adobe Analytics destination works with our standard Ecommerce API.

The following mapping between semantic ecommerce events for Segment and Adobe Analytics are supported:

Segment Event NameAdobe Analytics Event Name
Product ViewedprodView
Product AddedscAdd
Product RemovedscRemove
Cart ViewedscView
Checkout StartedscCheckout
Order Completedpurchase

For any of the above ecommerce events, data is sent similarly to .track() events. The difference here is that you do NOT need to predefine these Segment event names in the Segment settings. The above ecommerce events will automatically be mapped and sent to Adobe Analytics.

Note: Ecommerce relevant properties such as orderId, products will be sent automatically. However, if you want to attach custom properties to Adobe’s eVar, prop or hVar, you need to predefine them in the Segment settings. (just the properties, no need to map the event names, unless you want the event name to be set to an eVar).

For all ecommerce events listed, we will send product description data to Adobe Analytics.

Given the sample Order Completed Segment event:

analytics.track('Order Completed', {
 orderId: '50314b8e9bcf000000000000',
 total: 30.00,
 revenue: 25.00,
 shipping: 3.00,
 tax: 2.00,
 discount: 2.50,
 coupon: 'hasbros',
 currency: 'USD',
 products: [
   {
     id: '507f1f77bcf86cd799439011',
     sku: '45790-32',
     name: 'Monopoly: 3rd Edition',
     price: 19,
     quantity: 1,
     category: 'Games'
   },
   {
     id: '505bd76785ebb509fc183733',
     sku: '46493-32',
     name: 'Go Pro',
     price: 99,
     quantity: 2,
     category: 'Electronics'
   }
 ]
});
  1. Set window.s.products with the product description string.

    The product description is a semi-colon delimited string per product which is additionally delimited by commas if you have multiple products. The string format per product is [category];[name];[quantity];[total]. Total is calculated by multiplying price and quantity for each product.

    Note: you can optionally choose whether to map the name, sku, or id for each of item in the products array. So one could alternatively send product descriptions with [category];[sku];[quantity];[total]. Select the mapping via the Product Identifier dropdown under Advanced Options in your Adobe Analytics Segment settings. name is the default identifier.

    Thus the above example would set window.s.products to 'Games;Monopoly: 3rd Edition;1;19,Electronics;Go Pro;2;99'.

    Note that the default fallback values for quantity and price is 1 and 0, respectively.

    Important: If any of the items in the products array have property values that include commas or semi-colons, you may have data issues since Adobe Analytics uses them as delimiters.

  2. Update common variables such as channel, campaign, state, zip, and pageName. These values will be set if they exist at the property level, your existing Adobe Analytics variables already attached on the window.s object, or context.page.title (for pageName).

  3. Set window.s.events with the corresponding Adobe Analytics naming convention. The example above wouild set this as 'purchase'.

  4. Check if the event name is mapped as an eVar and if so, set it on the window.s.

  5. Check if any other top level properties (not the custom properties at the item level inside products array) have been mapped to a custom variable in the Segment settings such as eVar, prop, and hVar. If so, set them on the window.s.

  6. Set window.s.purchaseID and window.s.transactionID as the orderId, which for the example above would be '50314b8e9bcf000000000000'. Note that this is only for Order Completed events.

    The default currencyCode we set upon pageload is USD. However, we will check if you have passed any currency other than this in your event by checking properties.currency.

    Important: If you’d like to collect transactionID, make sure to enable the transactionID storage setting inside your Reporting Suite!

  7. Attach the timestamp as window.s.timestamp if your Timestamp Option is Timestamp Enabled or Timestamp Optional.

  8. Set window.s.linkTrackEvents to the Adobe Analyics event name, which would be purchase for the example above.

  9. Set window.s.linkTrackVars which is a string of keys we want Adobe Analytics to read from the window.s object when the request is sent. For the example above, the value of linkTrackVars would be set as 'pageName,events,products,purchaseID,transactionID,timestamp'.

  10. Finally, fire off the event via window.s.tl(true, 'o', 'Order Completed');.

Server side (data sent via server side or mobile libraries without bundling the Segment-Adobe-Analytics SDK)

For more information on mobile native integrations using Segment’s iOS and Android Adobe Analytics SDKs, see the next section in this doc.

When you send data via any of our mobile or server side libraries, we will use Adobe Analytics’ Data Insertion API. You must configure your Report Suite ID and Tracking Server URL inside Segment for us to be able to successfully send data.

Important: For data sent from server-side libraries, you’ll still need to predefine your events and custom properties in order to send events to Adobe Analytics server side destination. However, for data sent from mobile devices, we will send every event along automatically, and you may use their processing rules UI to map actions, lifecycle dimensions, and custom properties from contextData to events, props and eVars retroactively.

When we generate the XML tag to be sent, there are a few things that happen:

  1. If your Timestamp Option is Timestamp Enabled or Timestamp Optional, set <timestamp>.

  2. For .track() events, we will set <channel> as properties.channel or fallback to properties.category. If neither properties are provided, we will not set this XML tag. For .page() events, this XML tag will be set as the category of the page call, which is sent by providing both category and name (ie. .page('Some Category', 'Some Name');)

  3. For .track() events, we will set <pageName> as properties.pageName, properties.page, context.page.title, context.screen.name or 'None' (in order of precedence). For .page() calls, we will set the tag as the name. This can be sent by providing the first parameter: .page('Some Name');

  4. Since Adobe Analytics does not support sending timestamped hits a <visitorID>, if you have set your Report to Timestamp Disabled, we will set <visitorID> as these values in order of precedence:

    • visitorId passed manually from the client. Adobe Analytics sets a cookie with their own visitorId on the client. You can read from this cookie and pass it to your servers manually and then send it to Segment. This is generally unnecessary, but may be worth considering if you’re concerned about unique user identification.

      (In Node.js)

      analytics.track({
      userId: '019mr8mf4r',
      event: 'Gotta catch em all',
      properties: {
      caught: 1738
      },
      integrations: {
       'Adobe Analytics': {
         visitorId: '12345'
       }
      }
      });
      
    • userId

    • anonymousId
  5. We will map a number of other supported XML tags. For example, we will set <ipAddress> with the ip of the call.

    Note: For server side libraries, the ip would be by default be the ip address of your company servers, NOT the customers’ own. This means that for server side events, it is best practice to grab your customer’s ip from their requests and manually send that to Segment as context.ip.

    We will also set your context.locale (which is automatically collected if using a mobile library) to <language>. Since mobile libraries also send your traits from previous .identify() calls inside the context.traits, we will try to send <state> and <zip> by looking up context.traits.address.state and context.traits.postalCode respectively, as noted in our identify spec. If these lookups fail, we will fallback on properties.state and properties.zip.

    For mobile libraries, since we can detect whether the event occured while the user had wifi connection, we will also send the <connectionType> as lan/wifi. All other events will be treated as Mobile Carrier inside Adobe’s Mobile Web Reports.

    We will also calculate your timezone offset from UTC/GMT as required by Adobe and send <timezone> based on your context.timezone and the timestamp fields.

    Since many out of the box reports from Mobile Web services rely on the <userAgent> tag, we will also map this to your context.userAgent.

    Important: Android library can collect the userAgent automatically – however, the iOS library cannot do so. However, since we do collect other contextual metadata about your device, we will render a valid iOS userAgent string that should populate all your Mobile Web Reports.

  6. If you are using the Marketing Cloud ID Service, you can pass the Marketing Cloud Visitor ID as an destination specific setting and we will set that as <marketingCloudVisitorID>.

    (In Node.js)

    analytics.track({
     userId: '019mr8mf4r',
     event: 'Gotta catch em all',
     properties: {
      caught: 1738
     },
     integrations: {
       'Adobe Analytics': {
         marketingCloudVisitorId: '12345'
       }
     }
    });
    
  7. For .track() events only, set some custom link report parameters such as:

    • <linkType> to 'o' (stands for 'Other')
    • <linkURL> to context.page.url with a default fallback to 'No linkURL provided'
    • <linkName> to 'Link Name - <whatever was set as the linkURL>'
  8. On the server, we send all property values as contextData.$propertyKey by defauly so that you can further map them with Adobe Processing Rules. If you’d like to set a prefix for your properties, you may specify that in the destination’s advanced settings page and we will send the properties as contextData.<prefix>.$propertyKey.

  9. For Segment native mobile spec events, we automatically translate them and forward them to Adobe Analytics as Mobile Services Lifecycle Metrics.

Specifically, we map the following events:

Segment Event NameAdobe Analytics Event Name
Application Openeda.LaunchEvent
Application Installeda.InstallEvent
Application Updateda.UpgradeEvent

The following metrics and dimensions are supported:

  • a.AppID
  • a.HourOfDay
  • a.DayOfWeek
  • a.OSVersion
  • a.DeviceName
  • a.CarrierName

Support for additional “stateful” lifecycle dimensions is coming in a future Adobe Analytics release. If there are any missing that are of importance to you, let us know and we’ll get them shipped!

  1. Set <userAgent> with context.userAgent (which is automatically populated by our libraries). Note this is omitted for mobile events and superceded by DeviceName and OSVersion.

  2. For any ecommerce events, we will try to set <products> if possible. The product description will have the same logic as the ecommerce event processing done on the client side destination.

  3. We will follow the same logic as the client side and look up any mappings for custom properties and generate the proper <eVar>, <prop>, and <hVar> XML tags.

  4. Finally, we send the event POST request to your Tracking Server URL!

List Variables

You can map your Segment properties in your settings to any of your three list variables. You can either send the property value as a comma delimited string (ie. 'brady,edelman,blount') or as an array (['brady', 'edelman', 'blount']). If you choose to send them as an array, we will join it so that it is a comma delimited string before sending to Adobe!

Mobile

Our Adobe-Analytics mobile SDK’s are currently in beta. Feel free to try them out and give us feedback via our contact form.

Setting Up the SDKs

You’ll need to do a few things before you can start sending data from your mobile application to Adobe Analytics:

  • First, enable Segment-Adobe Analytics in your Segment account’s UI
  • Download the ADBMobileConfig.json file and follow the instructions in Adobe’s documentation, here for iOS, and here for Android
  • Finally, bundle the Segment’s Adobe Analytics SDK in your project

Android:

compile 'com.segment.analytics.android.integrations:adobeanalytics:+'

iOS:

pod 'Segment-Adobe-Analytics'

Note: Implementations using a Segment-Adobe Analytics SDK don’t require that you enter a Report Suite ID, a Timestamp Option, a Tracking Server Secure URL, a Tracking Server URL, or specify Use Secure URL for Server-side in your Segment settings UI. Your Adobe settings can be customized from the “Manage App Settings” tab of your Adobe Mobile Services dashboard, and downloaded as an ADBMobileConfig.json file by clicking the “Config JSON” link at the bottom of the same tab.

Sending Data to Adobe analytics

We strongly recommend creating both a Segment and Adobe Analytics tracking plan before attempting to send any events or properties to Adobe, since you’ll have to map all your Segment events to Adobe events and Segment properties to Adobe eVars or props in both the Segment settings UI and your Adobe Mobile Services dashboard.

Sending Events

You can map Segment events in your Events V2 setting to any event variable you’ve already defined in your Adobe Analytics Mobile Services dashboard. Note: Mapping events in Segment’s Events setting will have no effect, and your events will not be forwarded to Adobe.

Here’s an example of how you might map Segment events to Adobe Analytics events:

Here’s an example of how you would implement the same mapping in Adobe’s Mobile Services Dashboard:

Sending Properties

You can map Segment properties in your Context Data Variables setting to any context data variable you’ve already defined in your Adobe Analytics Mobile Services dashboard - this includes not only Adobe props, but also eVars. All these Adobe variable types will be found in your Adobe Mobile Services dashboard.

Here’s an example of how you would implement the same mapping in Adobe’s Mobile Services Dashboard:

Adobe Lifecycle events

Segment implements Adobe Lifecycle Events out of the box - you don’t have to enable any additional settings! Lifecycle events gather crucial information such as app launches, crashes, session length and much more. You can find a full list of all lifecycle metrics and dimensions in Adobe’s documentation.

Identify

Whenever you call identify, Segment sets the Adobe visitorId to the value of your user’s Segment userId. Here’s what we’re doing behind the scenes, on Android:

Config.setUserIdentifier("123");

And on iOS:

[ADBMobile setUserIdentifier:@"123"];

Screen

Whenever you call screen, Segment triggers an Adobe trackState event, passing your screen name, as well as any properties you’ve mapped to Adobe as context data values. Here’s what we’re doing behind the scenes, on Android:

Analytics.trackState("Home Screen", <properties mapped in contextData>);

And on iOS:

[self.ADBMobile trackState:@"Home Screen" data:<properties mapped in contextData>];

Track

Whenever you call track, Segment triggers an Adobe trackAction event, passing your event name, as well as any properties you’ve mapped to Adobe as context data values. Here’s what we’re doing behind the scenes, on Android:

Analytics.trackEvent("Clicked A Button", <properties mapped in contextData>);

And on iOS:

[ADBMobile trackAction:@"Clicked A Button" data:<properties mapped in contextData>];

Reset

Calling reset will set your user’s visitorId to null. null is Adobe’s default visitorId value until you explicitly set it by calling identify. Here’s what Segment is triggering behind the scenes:

Config.setUserIdentifier(null);
[ADBMobile trackingClearCurrentBeacon];

Flush

Calling flush will immediately dispatch all locally queued hits to Adobe. Here’s what Segment is triggering behind the scenes, on Android:

Analytics.sendQueuedHits();

And on iOS:

[ADBMobile trackingSendQueuedHits];

Ecommerce

The Adobe Analytics destination works with our standard Ecommerce API.

The following mapping between semantic ecommerce events for Segment and Adobe Analytics are supported:

Segment Event NameAdobe Analytics Event Name
Product ViewedprodView
Product AddedscAdd
Product RemovedscRemove
Cart ViewedscView
Checkout StartedscCheckout
Order Completedpurchase

For any of the above ecommerce events, data is sent similarly to standard track events. The difference here is that you do NOT need to predefine these event names in either your Segment settings or Adobe mobile services dashboard. The above ecommerce events will automatically be mapped and sent to Adobe Analytics.

Specced ecommerce properties such as orderId, products will be sent automatically. However, if you want to attach properties to Adobe’s eVar, prop or lVar, you need to predefine them in the Segment settings, as well as in your Adobe mobile services dashboard.

Note: An event name, product_id or sku is required for Adobe to process product information. You can select which of these values you’d like to set as the product name in Adobe in the Product Identifier setting in your Segment dashboard. Segment defaults to name as the product identifier. If you fail to pass the appropriate identifier with all products in a products array, Segment will still send the event to Adobe, but will not send any products with that ecommerce hit.

Adobe Heartbeat for Mobile

Adobe Heartbeat is an Adobe Analytics add-on that allows you to collect video analytics data from your mobile applications.

To get started, on Android:

For iOS, the Adobe Heartbeat SDK is already included with the Segment-Adobe-Analytics SDK.

IMPORTANT

  • You must add your Adobe heartbeat tracking server URL to your Adobe Analytics settings in your Segment UI. If you do not specify a tracking server URL, then Segment will not send any of your video events to Adobe Analytics.
  • You must enable Adobe’s VisitorID service in your Adobe account in order to track Heartbeat data. Please refer to Adobe’s documentation for more on enabling the VisitorID service.

Configuring the MediaHeartbeat Instance

Segment instantiates a MediaHeartbeat object to track video data. That said, we do require some information about each video session in order to make sure we configure the instance properly.

A “Video Playback Started” will begin a new video session and destroy any existing MediaHeartbeat instances. This means that you can only track one video session at a time.

Fields to initialize the MediaHeartbeat instance

FieldDescription
SSLSegment UI setting that allows you to choose whether to track data via SSL. Defaults to false.
appVersionAuto-collected from your SDK. Defaults to “unknown”.
properties.channelMust be passed as a property on a “Video Playback Started” event. Sets the “channel” configuration property. Defaults to an empty string.
properties.playerNameMust be passed as a property on a “Video Playback Started” event. Sets the “playerName” configuration property. Defaults to “unknown”.
options.ovpNameMust be passed as an Adobe Analytics integration-specific option. Sets the “ovp” configuration property. Defaults to “unknown”.

Here are examples of how to set an integration-specific option, on Android:

Map<String, Object> options = new HashMap<>();
        options.put("ovp", "ovpName");

Analytics.with(this).track("Video Playback Started",
        null,
        new Options()
          .setIntegrationOptions("Adobe Analytics", options));

And iOS:

options:@{
  @"integrations": @{
   @"Adobe Analytics" : @{
     @"ovp_name": @"ovp name",
     @"debug" : @YES
    }
  }
}

Supported Video Events

Adobe Analytics supports many - but not all - of our specced video events. Note, too, that some events required for Adobe Analytics are not specced as part of Segment’s standard video tracking, so read the documentation closely. The list below includes supported events, as well as the corresponding Adobe method(s) triggered. In the next section, we go into more detail on the functionality of each event, as well as list any required properties:

Segment Event NameAdobe Analytics Method(s) Triggered
Video Playback StartedtrackSessionStart
Video Playback PausedtrackPause
Video Playback ResumedtrackPlay
Video Playback Buffer StartedtrackEvent(bufferStart)
Video Playback Buffer CompletedtrackEvent(bufferComplete)
Video Playback Seek StartedtrackEvent(seekStart)
Video Playback Seek CompletedtrackEvent(seekComplete)
Video Playback CompletedtrackSessionEnd
Video Playback InterruptedPauses video playhead.
Video Quality UpdatedSends quality of service information to Adobe.
Video Content StartedtrackPlay
trackEvent(chapterStart)
Video Content CompletedtrackEvent(chapterComplete)
trackComplete
Video Ad Break StartedtrackEvent(adBreakStart)
Video Ad Break CompletedtrackEvent(adBreakComplete)
Video Ad StartedtrackEvent(adStart)
Video Ad SkippedtrackEvent(adSkip)
Video Ad CompletedtrackEvent(adComplete)

Video Playback Started

“Video Playback Started” is required to begin a new video session. This event must include the appropriate properties and options to configure the MediaHeartbeat instance for this video session. Although all the properties and options listed below are also required, you may send additional standard and custom video properties with this event.

Segment FieldDescription
properties.channelDistribution station/channels or where the content is played.
properties.playerNameName of the player responsible for rendering the ad.
properties.titleThe title of the video session.
properties.contentAssetIdThe unique id for the video session.
properties.totalLengthThe total length in seconds of the video session.
properties.livestreamWhether the session is a livestream (boolean).
options.ovpName of the online video platform through which content gets distributed.

Video Playback Completed

This Segment event will trigger an Adobe trackSessionEnd() event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Content Started

“Video Content Started” begins a new video chapter, or what is a content segment. This event must include the the following properties to configure a chapter MediaObject. You may also send additional standard and custom video properties with this event.

Segment FieldDescription
properties.titleThe title of the current chapter.
properties.indexPositionThe index position, starting with 0, of the content in relation to the video session.(int)
properties.totalLengthThe total length of the chapter in seconds.
properties.startTimeThe position of the video playhead in seconds when the chapter starts playing.

Video Content Completed

This Segment event will trigger an Adobe trackEvent(chapterComplete) event and a trackComplete() event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Playback Paused

This Segment event will trigger an Adobe trackPause() event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Playback Resumed

This Segment event will trigger an Adobe trackPlay() event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Playback Buffer Started

This Segment event will trigger an Adobe trackEvent(bufferStart) event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Playback Buffer Completed

This Segment event will trigger an Adobe trackEvent(bufferComplete) event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Playback Seek Started

This Segment event will trigger an Adobe trackEvent(seekStart) event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Playback Seek Completed

This Segment event will trigger an Adobe trackEvent(seekComplete) event. In order to reconcile the new playhead position, you must pass this value as seekPosition.

Segment FieldDescription
properties.seekPositionThe new position of the playhead in seconds.

Video Ad Break Started

This Segment event will trigger an Adobe trackEvent(adBreakStart) event. This event must include the following properties to configure an ad break MediaObject. You may also send additional standard and custom video properties with this event.

Segment FieldDescription
properties.titleThe title of the current chapter.
properties.indexPositionThe index position of the content, starting with 0, in relation to the video session. (int)
properties.startTimeThe position of the video playhead in seconds when the chapter starts playing.

Video Ad Break Completed

This Segment event will trigger an Adobe trackEvent(adBreakComplete) event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Ad Started

This Segment event will trigger an Adobe trackEvent(adStart) event. This event must include the following properties to configure an ad break MediaObject. You may also send additional standard and custom video properties with this event.

Segment FieldDescription
properties.titleThe title of the current ad.
properties.assetIdThe asset id of the current ad.
properties.indexPositionThe index position of the content, starting with 0, in relation to the ad break session. (int)
properties.totalLengthThe total length of the ad in seconds.

Video Ad Completed

This Segment event will trigger an Adobe trackEvent(adComplete) event. You are not required to pass any properties along with this event. Properties passed to this event will not be forwarded to Adobe (but will be sent to other downstream destinations supporting video events).

Video Quality Updated

This event is required to set quality of service information in the MediaHeartbeat delegate. To do so, fire this event with the following properties. All properties not set default to 0.

properties.bitrate
properties.startupTime
properties.fps
properties.droppedFrames

Standard Video Metadata

We map the following Segment-specced properties to Adobe constants. Note you don’t need to set up standard video properties in your Adobe dashboard as with contextData values.

Segment PropertyAdobe Constant
assetIdMediaHeartbeat.VideoMetadataKeys.ASSET_ID
contentAssetIdMediaHeartbeat.VideoMetadataKeys.ASSET_ID
programMediaHeartbeat.VideoMetadataKeys.SHOW
seasonMediaHeartbeat.VideoMetadataKeys.SEASON
episodeMediaHeartbeat.VideoMetadataKeys.EPISODE
genreMediaHeartbeat.VideoMetadataKeys.GENRE
channelMediaHeartbeat.VideoMetadataKeys.NETWORK
airdateMediaHeartbeat.VideoMetadataKeys.FIRST_AIR_DATE
publisherMediaHeartbeat.VideoMetadataKeys.ORIGINATOR
ratingMediaHeartbeat.VideoMetadataKeys.RATING

Standard Ad Metadata

At the moment, Segment only passes publisher as standard ad metadata. We map this property to Adobe constant MediaHeartbeat.AdMetadataKeys.ADVERTISER.

Custom Video Metadata

You may send any custom metadata you wish along with any video event that accepts metadata. Remember that although you do not need to set up standard video or ad metadata in your Adobe dashboard first, you must set up all custom video and ad metadata in Adobe before sending it. Adobe will discard all metadata that have not been set up before being received in their system.

Troubleshooting and Logging Heartbeat

For Android, Segment sets verbose Adobe Heartbeat logging if you pass VERBOSE as your Analytics log level when initializing Segment.

On iOS, pass in an integration specific option debug: @YES on Video Playback Started events so you can initialize the heartbeat with debugging enabled.

FAQ

There are a few common questions that we’ve heard over time that is worth mentioning.

Best practices for userId and sessioning

UPDATE: If you are willing to sacrifice having your own userId inside Adobe, you can enable Drop Visitor ID to effectively resolve the issue of Adobe creating a new user profile when you set window.s.visitorID with a custom value. Not setting this value will ensure that the funnel between anonymous users to identified users are not broken inside your reports (assuming you are only using analytics.js to send data to Adobe).

Adobe Analytics unfortunately counts every “effective” visitor ID as a unique visitor. There is no ability for Segment to alias, implicitly or explicitly, two effective IDs on your behalf.

Key to understanding the implications of this fact is an understanding of what Adobe Analytics means by “effective” visitor ID. To do so, we recommend reading this section of their documentation.

With analytics.js, prior to identifying your users the default auto-generated Adobe Analytics s_vi cookie value is used as the effective visitor ID. If you provide your Marketing Cloud ID Service Organization ID, then we’ll set the MCVID, which is used as the effective ID instead.

Once you identify your user, Segment sets the visitorId variable to your userId. This effectively creates a new user, which does have unique user implications. However, based on a thorough reading of their documentation and discussion with many customers, we believe this is the best practice because now you can seamlessly track this user across devices whenever they are logged in.

So if you’d like to track your users on the server as well, you have a few options. If you’re only tracking logged-in users, sending their userId in your events will ensure that the events are attributed to the proper user. If you’re tracking anonymous users as well, Segment will send along the s_vi cookie from Adobe if you pass it under context['Adobe Analytics'].visitorId as the visitorId. Then we will fallback on the userId and lastly the Segment anonymousId, which you’ll notice is a different ID from the anonymous s_vi value used on the client (Adobe Analytics’ auto-generated effective ID for anonymous users).

If you don’t mind slightly inflated unique user counts, this may be acceptable, as all events in that anonymous user’s session will still be attributable to a single user ID. If you really do want to tie the anonymous event from the client side with your server side events, you could grab the s_vi cookie value from the client and pass it to your server. We will respect any value passed in context["Adobe Analytics"].visitorId and pass that as the visitorID if provided. But keep in mind that if you go this route, you would probably need to manage the s_vi cookies for all your users since you always need to pass it with all your server side calls. Note that you can only parse the s_vi cookie if you have 1st party cookie enabled in you reporting suite.

Thus our recommendation is to stomach the slight inflated user count and simply just use the Segment userId as the visitorId. Yes you will have two user profiles if you have any anonymous client side events but you can always set up custom eVars to connect the few anonymous events to the right user.

If you’re using the marketingCloudVisitorID, we recommend doing this and including it in context["Adobe Analytics"].marketingCloudVisitorId. We’ll send both the userId (or anonymousId, if the call is anonymous) in the <visitorId> tag and the MCVID in the <marketingCloudVisitorID> tag, and Adobe will handle it from there.

We know this is daunting territory, so please don’t hesitate to reach out directly for guidance!

Since we cannot automatically track page data for server side calls, if you want to populate the Custom Links report in Adobe Analytics, you will need to manually pass context.page.url!

Sending data via mobile library

Segment supports Adobe Analytics Mobile Services. With Segment, there is no need to package Adobe Analytics SDKs to take advantage of Adobe Analytics Mobile Services functionality.

For getting started with our mobile libraries, check out the iOS and Android technical docs.

Add the Adobe Analytics Report Suite Id / Report Server Url

The first thing you’ll want to do is to add the Report Suite Id and the Tracking Server Url settings to your Segment Adobe Analytics destination settings.

When Will I See Data?

If you already have an app deployed with the Segment library, and you just turned on Adobe Analytics, it will take up to an hour for all your mobile users to refresh their Segment settings cache, and learn about the new service that you want to send to.

After the settings cache refreshes, our library will automatically start sending data to Adobe Analytics. Typically, Adobe requires up to 24 hours to process and display any new data.

Keep in mind that there is a known reporting delay.

Android Permissions

You’ll need to make sure you added these permissions to your AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

Supported Sources and Connection Modes

WebMobileServer
📱 Device-based
☁️ Cloud-based

To learn more about about Connection Modes and what dictates which we support, see here.

We offer an optional Cloud-based Connection Mode for Web data with Adobe Analytics. As a reminder, this removes the Adobe Analytics javascript library from your site, improving performance. Segment offers an optional Device-based Connection Mode for Mobile data with Adobe Analytics. If you’d like to use those features that require client-based functionality, follow the steps above to ensure you have packaged the Adobe Analytics SDK with Segment’s.

Settings

Segment lets you change these destination settings via your Segment dashboard without having to touch any code.

Context Data Variables

Map values you pass into the context object to Context Data Variables in Adobe Analytics. Then you can use processing rules to map you Context Data Variables in Adobe to other variables with Adobe Analytics Processing Rules. In the box on the left, put your Segment context key. The box on the right is what Context Data Variable you’d like it to be mapper to in Adobe.

If you have a nested object, separate the name with a . For example if you wanted to map the page referrer, you would put: page.referrer.

NOTE: By default we send all your properties as Context Data Variables so you do not need to map them again here.

Context Data Property Prefix

If you would like to prefix your Segment properties before sending them as contextData, enter a prefix here.

Drop Visitor ID

This will disable Visitor ID from being passed to Adobe.

eVars

Map your Adobe Analytics eVar names to the property names you’re using in your Segment events. Enter a Segment property name on the left and an Adobe Analytics eVar number on the right. You can view your Segment events and properties in your Schema.

Enable pageName for Track Events

If you do not want to attach pageName for your .track() calls, you can disable this option.

Events

Map your Adobe Analytics events names to your Segment events. Enter a Segment event name on the left and an Adobe Analytics event number on the right. You can view your Segment events in your Schema.

Events V2

Map your Adobe Analytics property names on the left to Adobe event names on the right. Your events MUST be set up in Adobe and mapped here in order to to be forwarded to the destination. This setting only applies to Mobile integrations with Adobe.

Hierarchy Variables

Map your Adobe Analytics hVars to the property names you’re using in your Segment page calls. Enter a Segment property name on the left and an Adobe Analytics hVar number on the right. You can view your Segment page calls and properties in your Schema.

Heartbeat Tracking Server URL

This is the URL of your Adobe Heartbeat server. Please contact Adobe to obtain this URL.

List Variables

Map your Adobe Analytics list variables names to the property names you’re using in your Segment events. Enter a Segment property name on the left and an Adobe Analytics list variable number on the right. You can view your Segment events and properties in your Schema.

Marketing Cloud Organization Id

If you would like to use the Marketing Cloud Id Service and use visitorAPI.js, please enter your Marketing Cloud Organization ID. If you do not know your organization ID, you can find it on the Marketing Cloud administration page. It should look something like ‘1234567ABC@AdobeOrg’.

Prefer VisitorID for Hybrid Timestamp Reporting

If you enable this option and you also have a Timestamp Optional reporting suite, you can opt to send your visitorID instead of the timestamp since Adobe does not allow you to send both. If you care more about your user attribution, you should enable this if you’re using a hybrid timestamp reporting suite.

Product Identifier

Adobe Analytics only accepts a single product identifier. Use this option to choose whether we send product name, id, or sku.

Props

Map your Adobe Analytics property names to the property names you’re using in your Segment events. Enter a Segment property name on the left and an Adobe Analytics property number on the right. You can view your Segment events and properties in your Schema.

Report Suite ID(s)

You can find your Report Suite ID in your Adobe Analytics Settings page. Multiple report suite ids can be separated by commas: suite1,suite2,suite3.

Send Both Timestamp and VisitorID for Timestamp Optional Reporting Suites

If you have a Timestamp Optional Reporting Suite, you can opt to send both the timestamp and the visitorID in your XML when sending events server side. However, note that this is NOT recommended by Adobe as it may lead to out of order data. This setting will only work for reporting suites that have optional timestamp setting enabled.

SSL

Check this box if you would like your Adobe Heartbeat calls to be made over HTTPS.

Timestamp Option

Adobe Analytics can have Report Suites that will accept timestamped, non-timestamped or hybrid data. Note that we can only play historical data for timestamped or hybrid Report Suites.

Tracking Server Secure URL

This is the secure URL of your Adobe Analytics server.

Tracking Server URL

This is the URL of your Adobe Analytics server.

Use Legacy LinkName

Before sending LinkName to Adobe Analytics, prepend the URL with Link Name -.

This setting enables a legacy behavior for backwards compatibility. You probably want to keep this setting turned off.

Use Secure URL for Server-side

Enable this option if you want to use the ‘Tracking Server Secure URL’ endpoint instead of the normal URL for server-side and Cloud Mode calls.


If you have any questions or see anywhere we can improve our documentation, please let us know or kick off a conversation in the Segment Community!