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.

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:

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.