Setting up Adobe Analytics Heartbeat

Adobe Heartbeat is an Adobe Analytics add-on that allows you to collect video analytics data from mobile applications, and JavaScript or website sources.

At this time, Adobe Heartbeat is only available for events sent using device mode.

Before you start, complete these required steps.

First, connect your Adobe Heartbeat Server URL to Segment:

  1. Find your Adobe Analytics Heartbeat Tracking Server URL and copy it. If you don’t know where to find your Heartbeat Tracking Server URL, contact your Adobe representative.
  2. Log in to your Segment workspace, and go to the Adobe Analytics settings. If you have multiple sources sending to Adobe Analytics, click the one that you’ll be using with Adobe Heartbeat. If you’ll be using Heartbeat with more than one source, repeat these steps for each source.
  3. Open the Heartbeat Tracking Server URL setting, and paste your server URL in the field. Click Save.

Note: If you don’t specify a Heartbeat Tracking Server URL, Segment can’t send your video events to Adobe Heartbeat.

Next, enable Adobe’s VisitorID service in your Adobe account. You must do this to track Heartbeat data. See Adobe’s documentation for more on enabling the VisitorID service.

Set Up Steps for Mobile

For Android:

  1. If you haven’t done so already, go to the Adobe Mobile Services UI and follow these steps to download the core adobeMobileLibrary and configure in your Android project. Add the ABDMobileConfig.json to your project from the downloaded SDK.
  2. Download the latest version of the MediaSDK.jar file and include it in your Android project using Adobe’s documentation steps.
  3. Follow the remaining set up steps to complete the installation.

For iOS: The Adobe Heartbeat SDK is already included with the Segment-Adobe-Analytics SDK when you add a Heartbeat Tracking Server URL. Ensure you have added the ABDMobileConfig.json for your iOS project from the Adobe Mobile Services UI.

Set Up Steps for Web

The Adobe Heartbeat JS SDK is automatically included with the Segment-Adobe-Analytics integration when you add a Heartbeat Tracking Server URL.

Segment will map your video events to the Adobe methods as outlined below. In order to record video heartbeats to Adobe accurately on web, Adobe’s SDK requires a playhead update at least once per second for main content. The “Video Content Playing” event updates the playhead using the position property. If you do not want to trigger this event every second, you can alternatively set the playhead to the window. This can be done by setting window._segHBPlayheads to the key-value pair of the current content’s session_id and position:

window._segHBPlayheads = { <session_id>: <position> }

The Segment-Adobe-Analytics integration will pick up the playhead(s) you set to window._segHBPlayheads and pass this to Adobe’s SDK.

Configure the MediaHeartbeat Instance

Segment instantiates a MediaHeartbeat object to track video data, but you need more information about each video session to make sure Segment configures the instance properly.

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

The following fields are required in order to initialize the MediaHeartbeat instance:

Field Description
SSL Segment UI setting that allows you to choose whether to track data using SSL. Defaults to false.
appVersion Auto-collected from your SDK. Defaults to “unknown”.
properties.channel Must be passed as a property on a “Video Playback Started” event. Sets the “channel” configuration property. Defaults to an empty string.
properties.playerName Must be passed as a property on a “Video Playback Started” event. Sets the “playerName” configuration property. Defaults to “unknown”.
options.ovpName Must be passed as an Adobe Analytics integration-specific option. Sets the “ovp” configuration property. Defaults to “unknown”.

The following example shows 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));

The following example shows how to set an integration-specific option on iOS:

[[SEGAnalytics sharedAnalytics] track:@"Video Playback Started"
  properties:@{}
  options:@{ @"integrations": @{
                @"Adobe Analytics" : @{
                    @"ovp_name": @"ovp name",
                    @"debug" : @YES
                  }
              },
              @"context":@{}}];
options:@{
  @"integrations": @{
   @"Adobe Analytics" : @{
     @"ovp_name": @"ovp name",
     @"debug" : @YES
    }
  }
}

Supported Video Events

Adobe Analytics supports many - but not all - of the Segment Video Spec events, however some events required for Adobe Analytics are not included as part of Segment’s standard video tracking, so read the documentation closely. The list below shows supported events and the corresponding Adobe method(s) they trigger. The next section explains the function of each event in more detail, and lists any required properties.

Segment Event Name Adobe Analytics Method(s) Triggered
Video Playback Started trackSessionStart
Video Playback Paused trackPause
Video Playback Resumed trackPlay
Video Playback Buffer Started trackEvent(bufferStart)
Video Playback Buffer Completed trackEvent(bufferComplete)
Video Playback Seek Started trackEvent(seekStart)
Video Playback Seek Completed trackEvent(seekComplete)
Video Playback Completed trackComplete
trackSessionEnd
Video Playback Interrupted Pauses video playhead.
Video Quality Updated Sends quality of service information to Adobe.
Video Content Started trackPlay
trackEvent(chapterStart)
Video Content Completed trackEvent(chapterComplete)
Video Ad Break Started trackEvent(adBreakStart)
Video Ad Break Completed trackEvent(adBreakComplete)
Video Ad Started trackEvent(adStart)
Video Ad Skipped trackEvent(adSkip)
Video Ad Completed trackEvent(adComplete)

On web, multiple video sessions can be open at once so video events must have a session_id property unique to the session the content belongs to. If a session_id is not included, Segment will send default as the s:event:sid and Adobe will create a new session. For more information on session_id, please visit Segment’s Video Spec.

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 can also send additional standard and custom video properties with this event. See the Custom Video Metadata section below.

Segment Field Description
properties.channel Distribution station/channels or where the content is played.
properties.playerName Name of the player responsible for rendering the ad.
properties.title The title of the video.
properties.contentAssetId The unique id for the video.
properties.totalLength The total length in seconds of the video.
properties.livestream Whether the video is a livestream (boolean).
properties.session_id The unique id for the session. Required for web.
options.ovp Name of the online video platform through which content gets distributed.

Video Playback Completed

This Segment event triggers an Adobe trackSessionEnd() event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support 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 Field Description
properties.title The title of the current chapter.
properties.indexPosition The index position, starting with 0, of the content in relation to the video session.(int)
properties.totalLength The total length of the chapter in seconds.
properties.startTime The position of the video playhead in seconds when the chapter starts playing.
properties.session_id The unique id for the session. Required for web.

Video Content Completed

This Segment event triggers an Adobe trackEvent(chapterComplete) event and a trackComplete() event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Playback Paused

This Segment event triggers an Adobe trackPause() event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Playback Resumed

This Segment event triggers an Adobe trackPlay() event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Playback Buffer Started

This Segment event triggers an Adobe trackEvent(bufferStart) event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Playback Buffer Completed

This Segment event triggers an Adobe trackEvent(bufferComplete) event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Playback Seek Started

This Segment event triggers an Adobe trackEvent(seekStart) event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Playback Seek Completed

This Segment event triggers an Adobe trackEvent(seekComplete) event. On web, you must include a session_id property to tie this event to the correct video session. To reconcile the new playhead position, you must also pass the position as seekPosition.

Segment Field Description
properties.seekPosition The new position of the playhead in seconds.

Video Ad Break Started

This Segment event triggers 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 Field Description
properties.title The title of the current chapter.
properties.indexPosition The index position of the content, starting with 0, in relation to the video session. (int)
properties.startTime The position of the video playhead in seconds when the chapter starts playing.
properties.session_id The unique id for the session. Required for web.

Video Ad Break Completed

This Segment event triggers an Adobe trackEvent(adBreakComplete) event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support video events).

Video Ad Started

This Segment event triggers 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 Field Description
properties.title The title of the current ad.
properties.assetId The asset id of the current ad.
properties.indexPosition The index position of the content, starting with 0, in relation to the ad break session. (int)
properties.totalLength The total length of the ad in seconds.
properties.session_id The unique id for the session. Required for web.

Video Ad Completed

This Segment event triggers an Adobe trackEvent(adComplete) event. On web, you must include a session_id property to tie this event to the correct video session. Any other properties passed to this event are not forwarded to Adobe (but are sent to other downstream destinations that support 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.framerate
properties.droppedFrames
properties.session_id Required for web. Defaults to default if missing.

Standard Video Metadata

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

Segment Property Adobe Constant
assetId MediaHeartbeat.VideoMetadataKeys.ASSET_ID
contentAssetId MediaHeartbeat.VideoMetadataKeys.ASSET_ID
program MediaHeartbeat.VideoMetadataKeys.SHOW
season MediaHeartbeat.VideoMetadataKeys.SEASON
episode MediaHeartbeat.VideoMetadataKeys.EPISODE
genre MediaHeartbeat.VideoMetadataKeys.GENRE
channel MediaHeartbeat.VideoMetadataKeys.NETWORK
airdate MediaHeartbeat.VideoMetadataKeys.FIRST_AIR_DATE
publisher MediaHeartbeat.VideoMetadataKeys.ORIGINATOR
rating MediaHeartbeat.VideoMetadataKeys.RATING

Standard Ad Metadata

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

Custom Video Metadata

You can send custom metadata with any video event that accepts metadata. To send Custom Video Metadata, map the values you want to send in the Context Data Variable mappings setting in the Adobe Destination settings in the Segment web app.

You do not need to map standard video or ad metadata in your Adobe dashboard, you must set up all custom video and ad metadata in Adobe before sending it. Adobe discards any metadata it receives that does not have a mapping.

Custom Video Metadata Formatting

For custom Context Data Variables, including custom video metadata, use the following notation when mapping your Segment payload properties. The formatting for these mappings is different for iOS and Android components, so read the documentation below carefully.

Segment Payload Field iOS Mapping Notation Android Mapping Notation
anonymousId anonymousId .anonymousId
messageId messageId .messageId
event
.track() calls only
event .event
name
screen() calls only
name .name
context.traits.key traits.key .context.traits.key
context.key key .context.key
context.arrayKey.key
ie. context.device.id
arrayKey.key
ie. device.id
.context.arrayKey.key
properties.key key key

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.

This page was last modified: 30 Aug 2023



Get started with Segment

Segment is the easiest way to integrate your websites & mobile apps data to over 300 analytics and growth tools.
or
Create free account