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:
- 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.
- 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.
- 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:
- 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 theABDMobileConfig.json
to your project from the downloaded SDK. - Download the latest version of the
MediaSDK.jar
file and include it in your Android project using Adobe’s documentation steps. - 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
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!