adobe experience cloud video heartbeat developer … analytics implementation guide 2.x for...
TRANSCRIPT
Contents
Video Analytics Implementation Guide 2.x for JavaScript..................................3
Release Notes for the JavaScript VideoHeartbeat 2.x SDK....................................................3
Getting started.........................................................................................................................3
Download the JavaScript SDK...................................................................................................................4
Implement the JavaScript library................................................................................................................4
Migrate to version 2.x in JavaScript............................................................................................................4
Implementation guide..............................................................................................................5
Set up and configure your MediaHeartbeat instance.................................................................................5
Track core playback....................................................................................................................................7
Track ads....................................................................................................................................................9
Track chapters..........................................................................................................................................10
Standard Metadata Parameters...............................................................................................................11
Track buffering..........................................................................................................................................13
Seeking....................................................................................................................................................13
QoS updates............................................................................................................................................14
Tracking errors..........................................................................................................................................15
Inactive video sessions and resuming......................................................................................................15
Opt-out and privacy settings.....................................................................................................................16
Video Measurement Parameters...........................................................................................16
Sample player.......................................................................................................................16
Debugging.............................................................................................................................16
Validate implementations......................................................................................................17
Ratings Partners Integration..................................................................................................17
Scenarios..............................................................................................................................18
VOD main content....................................................................................................................................18
Live main content.....................................................................................................................................45
API docs................................................................................................................................51
FAQs.....................................................................................................................................51
Contact and Legal Information..............................................................................................51
Video Heartbeat Developer Guide 2.x forJavaScript
Last updated 3/16/2018
Video Analytics Implementation Guide 2.x forJavaScript
Release Notes for the JavaScript VideoHeartbeat 2.x SDK
Included are notes from the latest major revision to current version.
What's new in Video Heartbeat Library (VHL) 2.x:
• Lighter and simpler implementation, which includes the following:
• Streamlined implementation and configuration.
In VHL 2.x, all the configuration and video tracking API calls are centralized through one class, MediaHeartbeat.
• Error state recovery.
VHL 2.x keeps track of the current state of the playback. With internal state logic, VHL 2.x can ignore incorrectAPI calls.
• A clear difference between optional and required video tracking APIs.
Optional video tracking features such as chapter tracking, ad tracking, bitrate change, and so on, are now trackedthrough one video tracking API, trackEvent.
Version 2.0.0 (July 1, 2016) was the initial release of the 2.x JavaScript libraries.
Getting started
Before you can use Video Heartbeat 2.x in JavaScript, you must set up an Experience Cloud account, enable theVisitor ID service, and obtain valid configuration parameters for measuring video heartbeats.
Prerequisites to implementing Video Analytics
Note: This guide is intended for a media integration engineer who has an understanding of the APIs andworkflow of the media player being instrumented.
Before you start implementing Video Heartbeat for JavaScript in the next section, ensure that you have completedthe following tasks:
• Set up an Experience Cloud account - Contact an Adobe representative to assist you in setting up an ExperienceCloud account for doing video analytics.
• Implement AppMeasurement for JavaScript in your video application - For more information about the AdobeMobile SDK documentation, see Implementing Analytics Using JavaScript.
• Implement the Visitor ID service - For more information about the Visitor ID service, see Implementing AnalyticsUsing JavaScript.
• Obtain valid configuration parameters for Heartbeats - These parameters can be obtained from an Adoberepresentative after you set up your video analytics account.
• Provide the following capabilities in your media player:
• An API to subscribe to player events - The media heartbeat requires that you call a set of simple APIs whenevents occur in your player.
3Video Analytics Implementation Guide 2.x forJavaScript
• An API that provides player information - This information includes details such as the media name and the playhead position.
Download the JavaScript SDK
You can download the SDK from the Experience Cloud GitHub page.
Download the SDK
1. Browse to https://github.com/Adobe-Marketing-Cloud/video-heartbeat-v2/releases.
2. Navigate to the tag which refers to latest library version for JavaScript.
3. Click and download the archive.
Implement the JavaScript library
After you download the JavaScript SDK and add it to your project, you can collect video metrics, such as initiates,content starts, ad starts, ad completes, content completes and so on.
Get the JavaScript heartbeats libraries
Before you begin implementing heartbeat tracking in your application, you must implement appMeasurement andthe Visitor ID service for JavaScript, and download the Video Heartbeat SDK. For more information, see theprerequisites in Getting started.
1. Expand the VideoHeartbeatLibrary-js-v2.*.zip file that you downloaded.
2. Verify that the VideoHeartbeat.min.js file exists in the libs directory:
This library is designed for use with desktop/browsers, with APIs for video heartbeat tracking.
Add the SDK to your project
To add the SDK to your project:
1. Host the VideoHeartbeat.min.js file.
This core JavaScript file must be hosted on a web server that is accessible to all pages on your site.You needthe path to these files for the next step.
2. Reference VideoHeartbeat.min.js on all site pages.
Include VideoHeartbeat for JavaScript by adding the following line of code in the <head> or <body> tag on eachpage. For example:
<script type="text/javascript"src="http://INSERT-DOMAIN-AND-PATH-TO-CODE-HERE/VideoHeartbeat.min.js"></script>
3. To quickly verify that the VideoHeartbeat library was successfully imported, instantiate theADB.va.MediaHeartbeatConfig class.
Note: From Version 2.1.0, the JavaScript SDK is compliant with the AMD and CommonJS module specifications,and VideoHeartbeat.min.js can also be used with compatible module loaders.
Migrate to version 2.x in JavaScript
This information helps you migrate from version 1.5 to 2.x of the JavaScript library.
4Video Analytics Implementation Guide 2.x forJavaScript
In version 2.x, all of the public methods are consolidated into the ADB.va.MediaHeartbeat class to make it easieron developers. Also, all configs are now consolidated into the ADB.va.MediaHeartbeatConfig class.
For detailed information about migrating from 1.x to 2.x, see VHL 1.x to 2.x Migration.
Implementation guide
This section will help you to implement various video tracking features using MediaHeartbeat.
Set up and configure your MediaHeartbeat instance
Add the library to your project by completing the tasks in Implement the JavaScript library.
1. For easy access to the APIs, create local references to the MediaHeartbeat classes.var MediaHeartbeat = ADB.va.MediaHeartbeat;var MediaHeartbeatConfig = ADB.va.MediaHeartbeatConfig;var MediaHeartbeatDelegate = ADB.va.MediaHeartbeatDelegate;
2. Create a MediaHeartbeatConfig instance.
This section helps you to understand MediaHeartbeat config parameters and how to set correct config valueson your MediaHeartbeat instance, for accurate tracking.
Here is the MediaHeartbeatConfig reference:
Default ValueRequiredDescriptionVariable Name
Empty StringYesDefines the server fortracking media heartbeats.
trackingServer
This is different from youranalytics tracking server.
Empty StringYesChannel name propertychannel
unknownYesName of the online videoplatform through whichcontent gets distributed.
ovp
unknownYesVersion of the video playerapp/SDK.
appVersion
Empty StringYesName of the video playerin use. E.g.: "AVPlayer",
playerName
"HTML5 Player", "MyCustom VideoPlayer".
falseYesProperty that indicateswhether the heartbeat calls
ssl
should be made overHTTPS.
falseYesGets the preference fordebug log output.
debugLogging
5Video Analytics Implementation Guide 2.x forJavaScript
Here is a sample MediaHeartbeatConfig initialization:
//Media Heartbeat initializationvar mediaConfig = new MediaHeartbeatConfig();mediaConfig.trackingServer = Configuration.HEARTBEAT.TRACKING_SERVER;mediaConfig.playerName = Configuration.PLAYER.NAME;mediaConfig.channel = Configuration.HEARTBEAT.CHANNEL;mediaConfig.debugLogging = true;mediaConfig.appVersion = Configuration.HEARTBEAT.SDK;mediaConfig.ssl = false;mediaConfig.ovp = Configuration.HEARTBEAT.OVP;
3. Implement the MediaHeartbeatDelegate protocol.
Here is the MediaHeartbeatDelegate reference:
RequiredDescriptionMethod name
YesReturns the MediaObject instancethat contains the current QoS
getQoSObject()
information. This method will becalled multiple times during aplayback session. Playerimplementation must always returnthe most recently available QoSdata.
YesReturns the current position of theplayhead.
getCurrentPlaybackTime()
For VOD tracking, the value isspecified in seconds from thebeginning of the media item.
For LIVE/LIVE tracking, the value isspecified in seconds from thebeginning of the program.
Here is the MediaObject (QoS Object) reference:
RequiredDescriptionVariable name
YesThe bitrate of media in bits persecond
bitrate
YesThe start up time of media inseconds
startupTime
YesThe start up time of media inseconds
fps
YesThe number of dropped frames sofar
droppedFrames
var mediaDelegate = new MediaHeartbeatDelegate();
// Replace <currentPlaybackTime> with the video player current playback timemediaDelegate.getCurrentPlaybackTime = function() { return <currentPlaybackTime>;};
// Replace <bitrate>, <startuptime>, <fps> and <droppeFrames> with the current playback QoS
6Video Analytics Implementation Guide 2.x forJavaScript
values. mediaDelegate.getQoSObject = function() { return MediaHeartbeat.createQoSObject(<bitrate>, <startuptime>, <fps>, <droppedFrames>);};
4. Create the MediaHeartbeat instance.
Use the MediaHeartbeatConfig and MediaHeartbeatDelegate to create the MediaHeartbeat instance.
this.mediaHeartbeat = new MediaHeartbeat(mediaDelegate, mediaConfig, appMeasurement);
Important: Make sure that your MediaHeartbeat instance is accessible and does not get deallocateduntil the end of the video session. This instance will be used for all of the following video tracking events.
Tip: MediaHeartbeat requires an instance of AppMeasurement to send calls to Adobe Analytics.
Here is an example of an AppMeasurement instance:
// AppMeasurement instance examplevar appMeasurement = new AppMeasurement();appMeasurement.visitor = visitor;appMeasurement.trackingServer = "<visitor_namespace>.sc.omtrdc.net";appMeasurement.account = <rsid>;appMeasurement.pageName = <page_name>;appMeasurement.charSet = "UTF8";
Track core playback
Add the library to your project by completing the tasks in Implement the JavaScript library and Configure and setup.
1. Identify when the user triggers the intention of playback (user clicks play and/or autoplay is on) and create aMediaObject instance using the video information.
Here is the MediaObject (Media Object) reference:
RequiredDescriptionVariable name
YesVideo name.name
YesVideo unique identifier.mediaId
YesVideo lengthlength
YesStream type (see constantsMediaHeartbeatStreamType)
streamType
Here is the MediaHeartbeat.StreamType constants reference:
DescriptionConstant name
Stream type for Video on Demand.VOD
Stream type for LIVE content.LIVE
Stream type for LINEAR content.LINEAR
//Replace <VIDEO_NAME> with the video name.//Replace <VIDEO_ID> with a video unique identifier.//Replace <VIDEO_LENGTH> with the video length.
7Video Analytics Implementation Guide 2.x forJavaScript
var mediaObject = MediaHeartbeat.createMediaObject(<VIDEO_NAME>, <VIDEO_ID, <VIDEO_LENGTH>, MediaHeartbeat.StreamType.VOD);
2. To attach custom video metadata (Adobe Analytics context data) to the video tracking session, create an objectwith keyvalue pairs:var videoCustomMetadata = { subchannel: "Sample subchannel", campaign: "Sample campaign", videometadata3: "Sample video metadata 3"};
3. Call trackSessionStart() in the MediaHeartbeat instance to begin tracking a video session:_onVideoLoad = function () { this._mediaHeartbeat.trackSessionStart(mediaObject, contextData);};
Important: trackSessionStart() tracks the user intention of playback, not the beginning of the playback.This API is used to load the video data/metadata and to estimate the time to start QoS metric (time durationbetween trackSessionStart() and trackPlay()).
Note: If you are not using custom video metadata, simply send an empty object for the data argument intrackSessionStart().
4. Identify the event from the video player for the beginning of the video playback (the 1st frame of the main contentis rendered on the screen) and call trackPlay()._onVideoPlay = function() { this._mediaHeartbeat.trackPlay();};
5. Identify the event from the video player for the completion of the video playback (user watched the end of thecontent) and call trackComplete()._onVideoComplete = function() { this._mediaHeartbeat.trackComplete();};
6. Identify the event from the video player for the unloading/closing of the video playback (user closes the videoand/or the video completed and unloaded) and call trackSessionEnd()._onVideoUnload = function() { this._mediaHeartbeat.trackSessionEnd();};
Important: trackSessionEnd() marks the end of a video tracking session. If the session was successfullywatched to completion (user watched the end of the content), make sure that trackComplete() is calledbefore trackSessionEnd(). Any other track* API call is ignored after trackSessionEnd() (except fortrackSessionStart() for a new video tracking session).
7. Identify the event from the video player for video play and/or video resume from pause and call trackPause()._onPause = function() { this._mediaHeartbeat.trackPause();};
Tip: Identify any scenario in which the Video Player will pause and make sure that trackPause() isproperly called. Sample scenarios include when an application goes to background, the video pause, andso on.
8Video Analytics Implementation Guide 2.x forJavaScript
8. Identify the event from the video player for video play and/or video resume from pause and call trackPlay()._onVideoPlay = function() { this._mediaHeartbeat.trackPlay();};
Important: This might be the same event source that was used for "How to track video playback". Makesure that each trackPause() API call is paired with a following trackPlay() API call when the videoplayback resumes.
Track ads
Here is the MediaHeartbeat.Event Ad tracking constants reference:
DescriptionConstant name
Constant for tracking AdBreak Start eventAdBreakStart
Constant for tracking AdBreak Complete eventAdBreakComplete
Constant for tracking Ad Start eventAdStart
Constant for tracking Ad Complete eventAdComplete
Constant for tracking Ad Skip eventAdSkip
1. Identify when an AdBreak boundary starts, then create an AdBreakObject instance.
Here is the AdBreakObject Reference:
RequiredDescriptionVariable name
YesAdBreak namename
YesAdBreak positionposition
YesAdBreak start timestartTime
// Replace <ADBREAK_NAME> with the AdBreak name.// Replace <POSITION> with a valid position value.// Replace <START_TIME> with the AdBreak start time. var adBreakInfo = MediaHeartbeat.createAdBreakObject(<ADBREAK_NAME>, <POSITION>, <START_TIME>);
2. Using the track API, track MediaHeartbeat.Event.AdBreakStart event._onAdBreakStart = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakObject);}
3. Identify when the ad boundary starts and create an AdObject instance.
Here is the AdObject reference:
RequiredDescriptionVariable name
YesAd namename
YesAd identifieradId
YesAd positionposition
9Video Analytics Implementation Guide 2.x forJavaScript
RequiredDescriptionVariable name
YesAd lengthlength
// Replace <AD_NAME> with the Ad name.// Replace <AD_ID> with the unique Ad identifier.// Replace <POSITION> with a valid ad position value.// Replace <LENGTH> with the ad length.
var adObject = MediaHeartbeat.createAdObject(<AD_NAME>, <AD_ID>, <POSITION>, <LENGTH>);
4. Create Ad context data dictionary if you intend to provide custom ad metadata while tracking an Ad.var adCustomMetadata = { affiliate: "Sample affiliate", campaign: "Sample ad campaign", creative: "Sample creative"};
5. Using the track API, track the MediaHeartbeat.Event.AdStart event._onAdStart = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adObject, adCustomMetadata);};
6. Identify when playback hits an Ad end boundary, and track the MediaHeartbeat.Event.AdComplete event._onAdComplete = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);};
7. Optionally, identify if ad playback did not complete and was skipped (for example, if the user seeks out of thead). Track the ad skip event using MediaHeartbeat.Event.AdSkip._onAdSkip = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdSkip);};
8. If there are any additional ads within the same AdBreak, repeat steps 3 through 7 again.
9. Identify if the playback hits an AdBreak end boundary, and when the AdBreak completes, track the event usingMediaHeartbeat.Event.AdBreakComplete._onAdBreakComplete = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);};
Track chapters
Here is the MediaHeartbeat.Event chapter tracking constants reference:
DescriptionConstant Name
Constant for tracking Chapter Start eventChapterStart
Constant for tracking Chapter Complete eventChapterComplete
Constant for tracking Chapter Skip eventChapterSkip
1. Identify when playback hits chapter start boundary, and when the chapter starts, create the ChapterObjectinstance using the chapter information.
10Video Analytics Implementation Guide 2.x forJavaScript
Here is the MediaHeartbeat.Event chapter tracking reference:
RequiredDescriptionVariable name
YesChapter namename
YesChapter positionposition
YesChapter lengthlength
YesChapter start timestartTime
///Replace <CHAPTER_NAME> with the chapter name.//Replace <POSITION> with a valid chapter position value.//Replace <LENGTH> with the chapter length.//Replace <START_TIME> with the chapter start time.
var chapterInfo = MediaHeartbeat.createChapterObject(<CHAPTER_NAME>, <POSITION>, <LENGTH>, <START_TIME>);
2. Create the chapter context data dictionary if you intend to provide custom chapter metadata while trackingchapters.var chapterCustomMetadata = { segmentType: "Sample segment type", segmentName: "Sample segment name", segmentInfo: "Sample segment info"};
3. Using the track API, track the MediaHeartbeat.Event chapter events._onChapterStart = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterStart, chapterObject, chapterCustomMetadata);};
4. Identify if the playback hits the ChapterBreak end boundary, and on ChapterBreak complete, track the eventusing MediaHeartbeat.Event.ChapterComplete._onChapterComplete = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterComplete);};
5. Optionally, identify if chapter playback did not complete and was skipped (for example, if the user seeks out ofthe chapter boundary), and track the chapter skip event using MediaHeartbeat.Event.ChapterSkip._onChapterSkip = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterSkip);};
6. If there are any additional chapters, repeat steps 1 through 5.
Standard Metadata Parameters
Video and ad data-collection parameters sent by video heartbeat are presented here:
• Video Metadata - See the Standard Video Metadata table in the Measuring Video in Adobe Analytics guide.• Ad Metadata - See the Standard Ad Metadata table in the Measuring Video in Adobe Analytics guide.
• Video metadata keys API Reference - MediaHeartbeat.VideoMetadataKeys• Ad metadata keys API Reference - MediaHeartbeat.AdMetadataKeys
11Video Analytics Implementation Guide 2.x forJavaScript
Implementation for standard video metadata
Standard Metadata Constants:
DescriptionConstant name
Constant for attaching standard video metadata on VideoMediaObject
StandardVideoMetadata
Constant for attaching standard ad metadata on AdMediaObject
StandardAdMetadata
Implement standard video metadata:
1. Create a dictionary of standard Video metadata key value pairs using the MediaHeartbeat.VideoMetadataKeyskeys specified above.
2. Set the standard video metadata dictionary on the MediaInfo instance using the Standard Metadata key forvideo metadata.
3. Provide this MediaInfo object while invoking the trackSessionStart API.
Here is a sample implementation:
_onVideoLoad = function () { //Replace <VIDEO_NAME> with the video name. //Replace <VIDEO_ID> with a video unique identifier. //Replace <VIDEO_LENGTH> with the video length. //Create the Media Object var mediaInfo = MediaHeartbeat.createMediaObject(<VIDEO_NAME>, <VIDEO_ID, <VIDEO_LENGTH>, MediaHeartbeat.StreamType.VOD);
//Set standard Video Metadata var standardVideoMetadata = {}; standardVideoMetadata[MediaHeartbeat.VideoMetadataKeys.SHOW] = "Sample Show"; standardVideoMetadata[MediaHeartbeat.VideoMetadataKeys.SEASON] = "Sample Season"; standardVideoMetadata[MediaHeartbeat.VideoMetadataKeys.EPISODE] = "Sample Episode";
mediaInfo.setValue(MediaObjectKey.StandardVideoMetadata, standardVideoMetadata); this._mediaHeartbeat.trackSessionStart(mediaInfo, contextData);};
Implementation for standard ad metadata
Standard Metadata Constants:
DescriptionConstant name
Constant for attaching standard video metadata on the Video MediaObjectStandardVideoMetadata
Constant for attaching standard ad metadata on the Ad MediaObjectStandardAdMetadata
Implement standard ad metadata:
1. Create a dictionary of standard ad metadata key value pairs using the MediaHeartbeat.AdMetadataKeys specifiedabove.
12Video Analytics Implementation Guide 2.x forJavaScript
2. Set the standard ad metadata dictionary on the Ad Object MediaObject instance using the Standard Metadataconstant for ad metadata.
3. Provide this Ad Object while invoking trackEvent() API for MediaHeartbeat.Event.Start.
Here is a sample implementation:_onAdStart = function() { //Replace <AD_NAME> with the Ad name. //Replace <AD_ID> with the unique Ad identifier. //Replace <POSITION> with a valid ad position value. //Replace <LENGTH> with the ad length. var adObject = MediaHeartbeat.createAdObject(<AD_NAME>, <AD_ID>, <POSITION>, <LENGTH>);
// Set standard Ad Metadata var standardAdMetadata = {}; standardAdMetadata[MediaHeartbeat.AdMetadataKeys.ADVERTISER] = "Sample Advertiser"; standardAdMetadata[MediaHeartbeat.AdMetadataKeys.CAMPAIGN_ID] = "Sample Campaign"; adObject.setValue(MediaObjectKey.StandardAdMetadata, standardAdMetadata); this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adObject);
};
Track buffering
Here is the MediaHeartbeat.Event buffer tracking constants reference:
DescriptionConstant name
Constant for tracking Buffer Start eventMediaHeartbeat.Event.BufferStart
Constant for tracking Buffer Complete eventMediaHeartbeat.Event.BufferComplete
Implement buffer tracking:
1. Listen for the playback buffering events from the media player, and on buffer start event notification, track bufferingusing the MediaHeartbeat.Event.BufferStart event._onBufferStart = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BufferStart);};
2. On buffer complete notification from the media player, track the end of buffering using theMediaHeartbeat.Event.BufferComplete event._onBufferComplete = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BufferComplete);};
Seeking
Here is the MediaHeartbeat.Event seek tracking constants reference:
DescriptionConstant name
Constant for tracking Seek Start eventMediaHeartbeat.Event.SeekStart
13Video Analytics Implementation Guide 2.x forJavaScript
DescriptionConstant name
Constant for tracking Seek Complete eventMediaHeartbeat.Event.SeekComplete
Implement seeking:
1. Listen for playback seeking events from the media player. On seek start event notification, track seeking usingthe MediaHeartbeat.Event.SeekStart event._onSeekStart = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekStart);};
2. On seek complete notification from the media player, track the end of seeking using theMediaHeartbeat.Event.SeekComplete event._onSeekComplete = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekComplete);};
QoS updates
Here is the MediaHeartbeat.Event QoS tracking constants reference:
DescriptionConstant name
Constant for tracking Bitrate changeMediaHeartbeat.Event.BitrateChange
Implement QoS tracking:
1. Listen for the QoS updates from media player, and on bitrate change event notification, create MediaObject withQoS information.
ADBMediaObject (QoS Object) Reference:
RequiredDescriptionVariable
YesCurrent bitratebitrate
YesStartup timestartupTime
YesFPS valuefps
YesNumber of dropped framesdroppedFrames
// Replace <bitrate>, <startuptime>, <fps> and // <droppeFrames> with the current playback QoS values. var qosObject = MediaHeartbeat.createQoSObject(<bitrate>, <startuptime>, <fps>, <droppedFrames>);
2. Track bitrate change using the MediaHeartbeat.Event.BitrateChange event._onBitrateChange = function() { this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BitrateChange, qosObject);};
14Video Analytics Implementation Guide 2.x forJavaScript
Tracking errors
Before you configure error tracking, see Implement the JavaScript library.
To track video player errors:onPlayerError = function() { this._mediaHeartbeat.trackError("videoErrorId");};
Tip: Tracking video player errors will not stop the video tracking session. If the video player error preventsthe playback from continuing, make sure that the video tracking session is closed by callingtrackSessionEnd() after calling trackError().
Inactive video sessions and resuming
Prerequisite: Before you configure the resuming of inactive video sessions, see Core playback tracking andAdding pause and other interruptions in Implement the JavaScript library.
Long pauses
The VHL SDK will automatically keep track of how long the video playback is in one of these inactive states :
• Paused
• Seeking
• Stalled
• Suffering
If a video tracking session stays in an inactive state for longer than 30 minutes, the VHL SDK automatically closesthe video tracking session. If the user resumes after a previously inactive video tracking session (the app callstrackPlay()), the VHL SDK will automatically create a new video session using the previously used video informationand metadata, and will send a resume heartbeat event. For more information, see Video Measurement Parameters.
Manually resume a previously closed session
Prerequisite: Before you manually resume a previously closed session, see Getting started.
MediaHeartbeat (VHL) will only automatically resume sessions if the application was not closed. If the applicationstores user data and has the capability to resume a previously closed video, it is possible to manually trigger aresume event. When starting the video tracking session. Set the optional property MediaObjectKey.VideoResumedto Yes.
_onVideoLoad = function () { // Replace <VIDEO_NAME> with the video name. // Replace <VIDEO_ID> with a video unique identifier. // Replace <VIDEO_LENGTH> with the video length. var mediaObject = MediaHeartbeat.createMediaObject(<VIDEO_NAME>, <VIDEO_ID, <VIDEO_LENGTH>, MediaHeartbeat.StreamType.VOD);
15Video Analytics Implementation Guide 2.x forJavaScript
// Set to true if this user is resuming a previously closed video session mediaObject.setValue(MediaObjectKey.VideoResumed, true); this._mediaHeartbeat.trackSessionStart(mediaObject, contextData);};
Opt-out and privacy settings
You can control whether Video Heartbeat activity is allowed on a specific device. A MediaHeartbeat object respectsthe VisitorAPI privacy and optout settings. To optout of Video Heartbeat tracking, you need to opt out from theVisitor API service. For further information on optout and privacy, see Experience Cloud ID Service.
Video Measurement Parameters
These are the data-collection parameters sent by video heartbeat.
See the Video Parameters tables in Measuring Video in Adobe Analytics:
• Video Parameters
• Ad Parameters
• Chapter Parameters
• Quality Parameters
Sample player
A sample player is included in the […]/samples directory of the SDK.
Debugging
You can enable or disable logging for MediaHeartbeat.
The Video Heartbeat Library (VHL) provides an extensive tracing/logging mechanism that is put in place throughoutthe entire video-tracking stack.You can enable or disable this logging for the VHL by setting the debugLogging flagon the MediaHeartbeatConfig object.
Sample code for debug logging:
// Media Heartbeat initializationvar mediaConfig = new MediaHeartbeatConfig();mediaConfig.debugLogging = true;this._mediaHeartbeat = new MediaHeartbeat(mediaDelegate, mediaConfig, appMeasurement);
The log messages follow this format:
Format: [<timestamp>] [<level>] [<tag>] [<message>]Example: [16:10:29 GMT0700 (PDT).245] [DEBUG] [plugin::player] Resolving qos.startupTime: 0
• timestamp: This is the current CPU time (time-zoned for GMT)
• level: There are 4 message levels defined:
• INFO – Usually the input data from the application (validate player name, video ID, etc.)
• DEBUG – Debug logs, used by the developers to debug more complex issues
16Video Analytics Implementation Guide 2.x forJavaScript
• WARN – Indicates potential integration/configuration errors or Heartbeats SDK bugs
• ERROR – Indicates important integration errors or Heartbeats SDK bugs
• tag: The name of the sub-component that issued the log message (usually the class name)
• message: The actual trace message
You can use the logs output by the video heartbeat library to verify the implementation. A good strategy is to searchthrough the logs for the string #track. This will highlight all the track*() calls made by your application.
For instance, this is what the logs filtered for #track could look like:
[16:10:29 GMT0700 (PDT).222] [INFO] [plugin::player] #trackVideoLoad()[16:10:29 GMT0700 (PDT).230] [INFO] [plugin::player] #trackSessionStart()[16:10:29 GMT0700 (PDT).250] [INFO] [plugin::player] #trackPlay()[16:10:29 GMT0700 (PDT).759] [INFO] [plugin::player] #trackChapterStart()[16:10:44 GMT0700 (PDT).769] [INFO] [plugin::player] #trackAdStart()[16:10:59 GMT0700 (PDT).752] [INFO] [plugin::player] #trackAdComplete()[16:10:59 GMT0700 (PDT).770] [INFO] [plugin::player] #trackChapterStart()[16:11:29 GMT0700 (PDT).734] [INFO] [plugin::player] #trackPause()[16:11:29 GMT0700 (PDT).764] [INFO] [plugin::player] #trackComplete()[16:11:29 GMT0700 (PDT).766] [INFO] [plugin::player] #trackVideoUnload()
Validate implementations
To validate your Media Heartbeat implementation you will need to use an HTTP Proxy tool to view the HTTP / HTTPStraffic between the Application and Heartbeats/Adobe Analytics.
HTTP calls for video analytics tracking are sent to 2 different tracking servers:
• Adobe Analytics: Adobe Analytics hits are used to mark the initiate of a Video/Ad/Chapter. Tracking serverexample: <visitornamespace>.sc.omtrdc.net.
• Heartbeats platform: Heartbeat platform hits (heartbeats) are sent throughout the video tracking session at 10second intervals (out of band events may be sent outside of the 10 seconds cycle). Tracking server example:<visitornamespace>.hb.omtrdc.net
•
All of the different parameters sent to the Adobe Analytics and Heartbeats tracking servers are presented here:Metrics and Metadata.
Adobe Debug Tool
Optionally, you can debug payloads (Heartbeat and Adobe Analytics) going out of the Video Heartbeat Library usingthe Adobe Debug tool, which is a freely available tool from Adobe for Video Heartbeat customers.
To use Adobe Debug, you need to contact your Adobe representative for the initial setup and registration. After yougain access to Adobe Debug, go to Adobe Debug help to see the help information.
Ratings Partners Integration
DocumentationParter
Digital Content Ratings powered by AdobeNielsen
17Video Analytics Implementation Guide 2.x forJavaScript
Scenarios
Scenarios help you understand how video heartbeat works for a variety of features.
For more information about setting up a scenario in JavaScript, see Set up and configure your MediaHeartbeatinstance.
VOD main content
These scenarios provide information about video-on-demand (VOD) content.
VOD playback with no ads - details
Scenario: One VOD asset, with no ads, played once, from beginning to end.
Scenario
NotesNetwork callsHeartbeat methodTrigger
This can be either a userclicking Play or an auto-playevent.
trackSessionStart()User clicks Play1. Analytics Content
Start
2. Heartbeat Content
Start
This method triggers thetimer, and from this point
Heartbeat Content PlaytrackPlay()First frame of the video
forward, heartbeats will besent every 10 seconds forthe duration of the playback.
Content HeartbeatsContent plays
Complete means that theend of the playhead wasreached.
Heartbeat Content
Complete
trackComplete()Content is complete
Parameters
Table 1: Heartbeat Content Start
Many of the same values that you see on Heartbeat Content Start calls are also seen on Adobe Analytics ContentStart calls. There are many parameters that Adobe uses to populate the various video reports, but only the mostimportant parameters are listed in this table:
NotesValueParameter
<Your Adobe Report Suite ID>s:sc:rsid
<Your Analytics Tracking ServerURL>
s:sc:tracking_server
Should match the mid value on theAdobe Analytics Content Start
call.
This must be set.s:user:mid
18Video Analytics Implementation Guide 2.x forJavaScript
NotesValueParameter
"start"s:event:type
"main"s:asset:type
<Your Video Name>s:asset:video_id
Custom metadata that is set on thevideo.
Optionals:meta:*
Table 2: Heartbeat Content Play
These parameters should look nearly identical to the Heartbeat Content Start call, but the key difference is thes:event:type parameter. All of the other parameters should still exist.
NotesValueParameter
"play"s:event:type
"main"s:asset:type
Table 3: Content heartbeats
During video playback, a timer sends at least one heartbeat every 10 seconds.These heartbeats contain informationabout playback, ads, buffering, and so on.The exact content of each heartbeat is beyond the scope of this document,but the critical issue is that heartbeats are triggered consistently while playback continues. In the content heartbeats,look for the following parameters:
NotesValueParameters
"play"s:event:type
This parameter reflects the currentposition of the playhead.
<playhead position> e.g., 50, 60, 70l:event:playhead
Table 4: Heartbeat Content Complete
When playback has completed, which means that the end of the playhead is reached, a Heartbeat ContentComplete call is sent. This call looks like other Heartbeat calls, but it contains some specific parameters:
NotesValueParameters
"complete"s:event:type
"main"s:asset:type
Playback with no interruptions
Scenario: Content is 40 seconds long, played until the end, without any interruption.
19Video Analytics Implementation Guide 2.x forJavaScript
To view this scenario in JavaScript, enter the following text:
// Set up mediaObject
var mediaInfo = MediaHeartbeat.createMediaObject(Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH,MediaHeartbeat.StreamType.VOD);var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3
};
// 1. Call trackSessionStart() when the user clicks play, or when autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// 2. Call trackPlay() when the main content starts, i.e., // the first frame of the video content is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 3. Call trackComplete() when the playback reaches the end, i.e., the video completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 4. Call trackSessionEnd() when the playback session is over. // This method must be called even if the user does not // watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
VOD playback with pre-roll ads - details
In this scenario, a pre-roll ad has been inserted before the main content.
Unless specified, the network calls are the same as the calls in the VOD playback with no ads - details scenario.The network calls happen at the same time, but the payload is different.
20Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
The measurement librarydoes not know that there is
trackSessionStart()The user clicks Play1. Analytics Content
Start a pre-roll ad, so these2. Heartbeat Content
Startnetwork calls are stillidentical to the Playbackwith no interruptionsscenario.
The ad starts. • trackEvent:AdBreakStart 1. Analytics Ad Start• trackEvent:AdStart 2. Heartbeat Ad Start
The ad content plays beforemain content, and the
Heartbeat Ad PlaytrackPlay()The frame of ad #1 isplayed.
heartbeats start when thead starts.
Ad HeartbeatsThe ad is played.
The end of the ad isreached.
Heartbeat Ad CompletetrackEvent:trackAdCompleteAd #2 completes playing.
trackEvent:AdStartThe first frame of ad #2 isplayed. 1. Analytics Ad Start
2. Heartbeat Ad Start
Ad HeartbeatsThe ad plays.
The end of the ad and thepod is reached.
Heartbeat Ad CompleteAd #2 completes playing. • trackEvent:trackAdComplete• trackEvent:AdBreakComplete
This network call is identicalto the Playback with nointerruptions scenario.
Content HeartbeatsThe content plays.
This network call is identicalto the Playback with nointerruptions scenario.
Heartbeat Content
Complete
trackComplete()The content is complete.
SessionEnd means the endof a viewing session. This
trackSessionEnd()The session is over
API must be called even ifthe user does not watch thevideo to completion.
Parameters
Table 5: Heartbeat Ad Start
When ad playback begins, a Heartbeat Ad Start call is sent. If the beginning of the ad does not coincide with the10-second timer, the Heartbeat Ad Start call is delayed by a few seconds, and the call goes to the next 10-secondinterval.When this happens, a Content Heartbeat goes out in the same interval, and you can differentiate betweenthe two calls by looking at the event type and the asset type:
21Video Analytics Implementation Guide 2.x forJavaScript
NotesValueParameter
"start"s:event:type
"ad"s:asset:type
Table 6: Heartbeat Ad Play Call
Ads follow the same basic model as Content Heartbeats, so the Ad Play call is similar to the Content Play call:
NotesValueParameter
"play"s:event:type
"ad"s:asset:type
Table 7: Ad Heartbeats
These parameters are similar to the Content Heartbeats call, but the Ad Heartbeats call contains a few extraparameters:
NotesValueParameter
"play"s:event:type
"ad"s:asset:type
<ad ID>s:asset:ad_id
<ad pod ID>s:asset:pod_id
Table 8: Heartbeat Ad Complete Call
Similar to Heartbeat Content Complete calls, when ad playback has completed, and the end of the playhead isreached, a Heartbeat Ad Complete call is sent.This call looks like other Heartbeat Ad calls but contains a couplespecific things:
NotesValueParameter
"complete"s:event:type
"ad"s:asset:type
22Video Analytics Implementation Guide 2.x forJavaScript
Playback with a pre-roll ad break
To view this scenario in JavaScript, enter the following text:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject(Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH,MediaHeartbeat.StreamType.VOD);var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// Prerollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME);var adInfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION, AD_LENGTH);
// Custom ad metadatavar adMetadata = { CUSTOM_AD_KEY_1 : CUSTOM_AD_VAL_1, CUSTOM_AD_KEY_2 : CUSTOM_AD_VAL_2};
// 2. Track the MediaHeartbeat.Event.AdBreakStart event when the preroll pod starts to play. // Note that since this is a preroll, track the MediaHeartbeat.Event.AdBreakStart // event before you call trackPlay().this._mediaheartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo, null);
.......
.......
// 3. Track the MediaHeartbeat.Event.AdStart event when the preroll pod's ad starts to play. // Note that since this is a preroll, track the MediaHeartbeat.Event.AdStart event before // you call trackPlay().this._mediaheartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 4. Call trackPlay() when the playback actually starts, i.e., the first frame of the main content is rendered on the screen. this._mediaHeartbeat.trackPlay();
23Video Analytics Implementation Guide 2.x forJavaScript
.......
.......
// 5. Track event MediaHeartbeat.Event.AdComplete when the ad reaches the end, // i.e., when it completes and finishes playing.this._mediaheartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
.......
.......
// 6. Track the MediaHeartbeat.Event.AdStart event when the preroll pod's second // ad starts to play.this._mediaheartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 7. Track the MediaHeartbeat.Event.AdComplete event when the second ad reaches // the end, i.e., when it completes and finishes playing.this._mediaheartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
.......
.......
// 8. Track the MediaHeartbeat.Event.AdBreakComplete event when all the ads // in the pod finish playing.this._mediaheartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
.......
.......
// 9. Call trackComplete() when the playback reaches the end, i.e., when it// completes and finishes playing. this._mediaHeartbeat.trackComplete();
// 10. Call trackSessionEnd() when the playback session is over. This method must // be called even if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
.......
.......
Playback with ad breaks
In this scenario, VOD content is played back with a 30-second pre-roll ad, 20 seconds of conent, a 20-second mid-rollad, 40 seconds of content, and a 20-second post-roll ad.
To view this scenario in JavaScript, enter the following text:
// Set up mediaObjectMediaObject mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD
24Video Analytics Implementation Guide 2.x forJavaScript
);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., when there's an intent to start playback. this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// Prerollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME);var adInfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION, AD_LENGTH);
// Custom ad metadatavar adMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2
};
// 2. Track the MediaHeartbeat.Event.AdBreakStart event when the preroll pod // starts to play. Note that since this is a preroll, you must track the // MediaHeartbeat.Event.AdBreakStart event before you call trackPlay(). this._trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo, null);
.......
.......
// 3. Track the MediaHeartbeat.Event.AdStart event when the preroll pod's ad // starts to play. Note that since this is a preroll, you must track the// MediaHeartbeat.Event.AdStart event before you call trackPlay(). this._heartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 4. Call trackPlay() when the main content actually starts, i.e., when the // first frame of the video content is rendered on the screen. this._mediaHeartbeat.trackPlay();
.......
.......
// 5. Track the MediaHeartbeat.Event.AdComplete event when the ad reaches the end, // i.e., when the ad completes and finishes playing.this._heartbeat.trackEvent(MediaHeartbeat.Event.AdComplete, null, null);
.......
.......
// 6. Track the MediaHeartbeat.Event.AdBreakComplete event when all of the ads in // the pod finish playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
.......
.......
25Video Analytics Implementation Guide 2.x forJavaScript
// Midrollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(MIDROLL_BREAK_NAME, MIDROLL_BREAK_POSITION, MIDROLL_BREAK_START_TIME);var adInfo = MediaHeartbeat.createAdObject(MIDROLL_AD_NAME, MIDROLL_AD_ID, MIDROLL_AD_POSITION, MIDROLL_AD_LENGTH);
// Custom ad metadatavar adMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2
};
// 7. Track the MediaHeartbeat.Event.AdBreakStart event when the // midroll pod starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo);
.......
.......
// 8. Track the MediaHeartbeat.Event.AdStart event when the midroll // pod's ad starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 9. Track the MediaHeartbeat.Event.AdComplete event when the ad // reaches the end, i.e., when the ad completes and finishes playing. this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
.......
.......
// 10. Track the MediaHeartbeat.Event.AdBreakComplete event when all of // the ads in the midroll pod finish playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
.......
.......
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD
);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3
};
// 1. Call trackSessionStart() when Play is clicked or if autoplay // is used, i.e., when there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
26Video Analytics Implementation Guide 2.x forJavaScript
......
......
// Prerollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME);var adInfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION, AD_LENGTH);
// Custom ad metadatavar adMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2
};
// 2. Track the MediaHeartbeat.Event.AdBreakStart event when the preroll pod // starts to play. Note that since this is a preroll, you must track the // MediaHeartbeat.Event.AdBreakStart event before you call trackPlay().this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo);
.......
.......
// 3. Track the MediaHeartbeat.Event.AdStart event when the preroll pod's // ad starts to play. Note that since this is a preroll, you must track // the MediaHeartbeat.Event.AdStart event before you call trackPlay().this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 4. Call trackPlay() when the playback actually starts, i.e., when the first // frame of the main content is rendered on the screen. _mediaHeartbeat.trackPlay();
.......
.......
// 5. Track the MediaHeartbeat.Event.AdComplete event when the ad reaches // the end, i.e., when the ad completes and finishes playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
.......
.......
// 6. Track the MediaHeartbeat.Event.AdBreakComplete event when all // of the ads in the pod finish playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
.......
.......
// Mid-rollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(MIDROLL_BREAK_NAME, MIDROLL_BREAK_POSITION, MIDROLL_BREAK_START_TIME);var adInfo = MediaHeartbeat.createAdObject(MIDROLL_AD_NAME, MIDROLL_AD_ID, MIDROLL_AD_POSITION, MIDROLL_AD_LENGTH);
27Video Analytics Implementation Guide 2.x forJavaScript
// Custom ad metadatavar adMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2
};
// 7. Track the MediaHeartbeat.Event.AdBreakStart event when the midroll // pod starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo);
.......
.......
// 8. Track the MediaHeartbeat.Event.AdStart event when the midroll pod's // ad starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 9. Track the MediaHeartbeat.Event.AdComplete event when the ad reaches // the end, i.e., when the ad completes and finishes playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
.......
.......
// 10. Track the MediaHeartbeat.Event.AdBreakComplete event when all // of the ads in the midroll pod finish playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
.......
.......
// Postrollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(POSTROLL_BREAK_NAME, POSTROLL_BREAK_POSITION, POSTROLL_BREAK_START_TIME);var adInfo = MediaHeartbeat.createAdObject(POSTROLL_AD_NAME, POSTROLL_AD_ID, POSTROLL_AD_POSITION, POSTROLL_AD_LENGTH);
// Custom ad metadatavar adMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2
};
// 11. Track the MediaHeartbeat.Event.AdBreakStart event when the postroll // pod starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo);
.......
.......
// 12. Track the MediaHeartbeat.Event.AdStart event when the postroll pod's ad // starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 13. Track the MediaHeartbeat.Event.AdComplete event when the ad reaches // the end, i.e., when the ad completes and finishes playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdComplete);
.......
.......
28Video Analytics Implementation Guide 2.x forJavaScript
// 14. Track the MediaHeartbeat.Event.AdBreakComplete event when all of // the ads in the postroll pod finish playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakComplete);
.......
.......
// 15. Call trackComplete() when the playback reaches the end, i.e., when playback// completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 16. Call trackSessionEnd() when the playback session is over. This method must be called // even if the user doesnot watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
VOD playback with skipped ads - details
This scenario comprises VOD content playback with a skipped ad.
Scenario
Table 9: One VOD with a skipped pre-roll ad
This is the same scenario as Playback with ad breaks except the application has a provision to let the user skip thead, on the click of a skip button perhaps.
NotesNetwork callsHeartbeat methodTrigger
The measurement library isunaware that there is a
trackSessionStart()User clicks Play1. Analytics Content
Start pre-roll ad. These network2. Heartbeat Content
Startcalls are still exactly thesame as Playback with nointerruptions scenario.
The ad starts. • trackEvent:AdBreakStart 1. Analytics Ad Start
• trackEvent:AdStart 2. Heartbeat Ad Start
When ad content playsbefore main content, the
Heartbeat Ad PlaytrackPlay()The first frame of the ad isplayed.
heartbeats will start whenthe ad starts to play.
Ad HeartbeatsThe ad plays.
There is no ad completenetwork call.
trackEvent:trackAdSkipThe ad is skipped.
These network calls areexactly the same as the
Content HeartbeatsThe content plays.
Playback with nointerruptions scenario.
29Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
This network call is exactlythe same as the Playback
Heartbeat Content
Complete
trackComplete()The content completesplaying.
with no interruptionsscenario.
SessionEnd means the endof a viewing session. This
trackSessionEnd()The session is over.
API must be called even ifthe user does not watch thevideo to completion.
Parameters
The parameters are identical to the parameters in the VOD playback with pre-roll ads - details scenario, except thereis no ad complete and no ad-break complete call.
Playback with skipped ads
To view this scenario in JavaScript, enter the following text:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject(Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// Prerollvar adBreakInfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME);MediaObject adInfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION,
30Video Analytics Implementation Guide 2.x forJavaScript
AD_LENGTH);
//context ad datavar adMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2};
// 2. Track the MediaHeartbeat.Event.AdBreakStart event when the preroll pod starts to play. // Since this is a preroll, you must track the MediaHeartbeat.Event.AdBreakStart event // before calling trackPlay().this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdBreakStart, adBreakInfo);
.......
.......
// 3. Track the MediaHeartbeat.Event.AdStart event when the preroll pod's ad starts to play. // Since this is a preroll, you must track the MediaHeartbeat.Event.AdStart event before // calling trackPlay().this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdStart, adInfo, adMetadata);
.......
.......
// 4. Call trackPlay() when the playback actually starts, i.e., when the first frame of // the main content is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 5. Track the MediaHeartbeat.Event.AdSkip event when the user intends to (and can) // skip the ad. For example, this could be tied to a "skip ad" button onClick handler. // The application could have the viewer land in the main content post ad.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.AdSkip);
.......
.......
// 6. Call trackComplete() when the playback reaches the end, i.e., playback completes // and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 7. Call trackSessionEnd() when the playback session is over. This method must be called even
// if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
VOD playback with one chapter - details
In this scenario, a portion of the VOD content is marked as a chapter.
ScenarioUnless specified, the network calls in this scenario are the same as the calls in the VOD playback with no ads -details scenario. The network call happens at the same time, but the payload is different.
31Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
We have not yet told themeasurement library that
trackSessionStart()User clicks Play1. Analytics Content
Start there is a pre-roll ad, so2. Heartbeat Content
Startthese network calls are stillexactly the same as SingleVoD.
Heartbeat Chapter StarttrackEvent:ChapterStartThe chapter starts.
When chapter contentplays before main content,
Heartbeat Content PlaytrackPlay()First frame of thechapter plays.
the Heartbeats start whenthe chapter starts.
Chapter HeartbeatsThe chapter plays.
This is when the end of thechapter is reached.
Heartbeat Chapter
Complete
trackEvent:trackChapterCompleteThe chapter iscomplete.
This network call is exactlythe same as the VOD
Content HeartbeatsThe content plays.
playback with no ads -details scenario.
This network call is exactlythe same as the VOD
Heartbeat Content
Complete
trackComplete()The content iscomplete.
playback with no ads -details scenario.
SessionEnd means thatthe end of a viewing
trackSessionEnd()The session is over.
session has been reached.This API must be calledeven if the user does notwatch the video tocompletion.
Parameters
Table 10: Heartbeat Chapter Start
When chapter playback begins, a Heartbeat Chapter Start call is sent. If the beginning of the chapter does notcoincide with the 10-second timer, the Heartbeat Chapter Start call is delayed by a few seconds, and the callgoes to the next 10-second interval.
When this happens, a Content Heartbeat call goes out in the same interval.You can differentiate between thetwo by examining the event type and the asset type:
NotesValueParameter
"chapter_start"s:event:type
"main"s:asset:type
Stream information that is specific tothe chapter data.
s:stream:chapter_*
32Video Analytics Implementation Guide 2.x forJavaScript
NotesValueParameter
Chapter with specific context data.s:meta:*
Playback with one chapter
To view this scenario in JavaScript, enter the following text:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD
);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart when Play is clicked or if autoplay is used, // i.e., when there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// Chaptervar chapterMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1};
var chapterDataInfo = MediaHeartbeat.createChapterObject(CHAPTER_NAME, CHAPTER_POSITION, CHAPTER_LENGTH, CHAPTER_START_TIME);
// 2. Track the MediaHeartbeat.Event.ChapterStart event when the chapter // starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterStart, chapterDataInfo, chapterMetadata);
.......
.......
// 3. Call trackPlay() when the playback actually starts, i.e., when the first
33Video Analytics Implementation Guide 2.x forJavaScript
// frame of the main content is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 4. Track the MediaHeartbeat.Event.ChapterComplete event when the chapter // finishes playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterComplete);
.......
.......
// 5. Call trackComplete() when the playback reaches the end, i.e., when playback // completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 6. Call trackSessionEnd() when the playback session is over. This method must be // called even if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
Playback with one chapter at the beginning
To view this scenario in JavaScript, enter the following text:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD
);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., when there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
34Video Analytics Implementation Guide 2.x forJavaScript
// Chaptervar chapterMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1};
var chapterDataInfo = MediaHeartbeat.createChapterObject(CHAPTER_NAME, CHAPTER_POSITION, CHAPTER_LENGTH, CHAPTER_START_TIME);
// 2. Track the MediaHeartbeat.Event.ChapterStart event when the chapter starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterStart, chapterDataInfo, chapterMetadata);
.......
.......
// 3. Call trackPlay() when the playback actually starts, i.e., when the first // frame of the main content is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 4. Track the MediaHeartbeat.Event.ChapterComplete event when the chapter // finishes playing.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterComplete);
.......
.......
// 5. Call trackComplete() when the playback reaches the end, i.e., when playback // completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 6. Call trackSessionEnd() when the playback session is over. This method must be // called even if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
VOD playback with a skipped chapter - details
In this scenario, the user skips a chapter in the main content.
Scenario
This is the same scenario as Playback with one chapter, except the user in this case intends to seek out of thechapter thereby skipping it to land into main content.
NotesNetwork callsHeartbeat methodTrigger
The measurement library iunaware that there is a
trackSessionStart()User clicks Play1. Analytics Content Start2. Heartbeat Content Start pre-roll ad. These network
calls are still exactly thesame as Playback with nointerruptions scenario.
35Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
Heartbeat Chapter StarttrackEvent:ChapterStartThe chapter starts.
When chapter content playsbefore main content, we
Heartbeat Chapter PlaytrackPlay()The first frame of thechapter is played.
want to start the Heartbeatswhen the chapter starts.
Chapter HeartbeatsThe chapter plays.
No heartbeats duringseeking
trackEvent:trackSeekStartSeek begins to skip the firstchapter.
Heartbeats would resumepost this.
trackEvent:trackSeekCompleteThe seek is complete.
trackEvent:trackChapterSkipThe application realizes thatthe user has seeked out ofthe regular chapterboundary.
Content HeartbeatsThe content plays.
This network call is exactlythe same as the Playback
Heartbeat ContentComplete
trackComplete()The content completesplaying.
with no interruptionsscenario.
SessionEnd means the endof a viewing session. This
trackSessionEnd()The session is over.
API must be called even ifthe user does not watch thevideo to completion.
Parameters
The parameters during the chapter playback are identical to the parameters in the Playback with one chapter, exceptthat there is no chapter complete network call.
Playback with a skipped chapter
Figure 1: Playback with a skipped chapter
To view this scenario in JavaScript, enter the following text:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject(
36Video Analytics Implementation Guide 2.x forJavaScript
Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3
};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// Chaptervar chapterMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1};
var chapterDataInfo = MediaHeartbeat.createChapterObject(CHAPTER_NAME, CHAPTER_POSITION, CHAPTER_LENGTH, CHAPTER_START_TIME);
// 2. Track the MediaHeartbeat.Event.ChapterStart event when the chapter starts to play.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterStart, chapterDataInfo, chapterMetadata);
.......
.......
// 3. Call trackPlay() when the playback actually starts, i.e., when the // first frame of the main content is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 4. Track the MediaHeartbeat.Event.SeekStart event when the user begins // to seek out of the chapter with the intent to skip it.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekStart);
.......
.......
// 5. Track the MediaHeartbeat.Event.SeekComplete event when the user seeks // out of the chapter with the intent to skip it.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekComplete);
.......
.......
// 6. Track the MediaHeartbeat.Event.ChapterSkip event because the user // skipped the chapter by seeking out of it in the steps above.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.ChapterSkip);
.......
.......
// 7. Call trackComplete() when the playback reaches the end, i.e., completes // and finishes playing.
37Video Analytics Implementation Guide 2.x forJavaScript
this._mediaHeartbeat.trackComplete();
........
........
// 8. Call trackSessionEnd() when the playback session is over. This method must be // called even if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
VOD playback with seeking in the main content - details
This scenario comprises seeking in the main content during playback.
ScenarioThis is the same scenario as the VOD playback with no ads - details scenario, but a part of the content is scrubbedthrough and a seek is completed from one point in main content to another point.
NotesNetwork callsHeartbeat methodTrigger
The measurement library isunaware that there is a
trackSessionStart()User clicks Play1. Analytics Content
Start pre-roll ad, so these network2. Heartbeat Content
Startcalls are identical to the VODplayback with no ads - detailsscenario.
When chapter content playsbefore main content, the
Heartbeat Content PlaytrackPlay()First frame of thecontent plays.
Heartbeats start when thechapter starts.
This network call is exactlythe same as the VOD
Content HeartbeatsContent plays
playback with no ads - detailsscenario.
No heartbeats go out till seekis complete, for example,trackSeekComplete is called.
trackSeekStart()User begins seekoperation on content
Heartbeats begin to go outsince seek is complete.
trackSeekComplete()Seek operationcompletes
Tip: The playheadvalue should representthe correct newplayhead after theseek.
This network call is exactlythe same as the VOD
Heartbeat Content
Complete
trackComplete()Content is complete
playback with no ads - detailsscenario.
SessionEnd means that theend of a viewing session has
trackSessionEnd()Session Over
38Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
been reached. This API mustbe called even if the userdoes not watch the video tocompletion.
Playback with seeking in the main content
To view this scenario, enter the following text:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD
);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3
};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// 2. Call trackPlay() when the playback actually starts, i.e., when the // first frame of the ad video is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 3. Track the MediaHeartbeat.Event.SeekStart event when the user // begins to seek.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekStart);
.......
.......
// 4. Track the MediaHeartbeat.Event.SeekComplete event when the user // completes seeking.
39Video Analytics Implementation Guide 2.x forJavaScript
this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.SeekComplete);
.......
.......
// 5. Call trackComplete() when the playback reaches the end, i.e., when// playback completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 6. Call trackSessionEnd() when the playback session is over. This method must be called // even if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
VOD playback with buffering - details
In this scenario, some buffering occurs when VOD content is played back.
ScenarioUnless specified, the network calls in this scenario are the same as the calls in the Playback with no interruptionsscenario.
NotesNetwork callsHeartbeat methodTrigger
This can be a userclicking Play or anauto-play event.
trackSessionStart()User clicks Play1. Analytics Content Start
2. Heartbeat Content Start
This method triggers thetimer. Heartbeats are sent
Heartbeat Content PlaytrackPlay()The first frame ofthe video plays.
every 10 seconds as longas playback continues.
Content HeartbeatsThe content plays.
Heartbeat BuffertrackEvent:BufferStartThe bufferingstarts.
Content HeartbeatsThe content isbuffered.
trackEvent:BufferCompleteThe bufferingcompletes. 1. Heartbeat Buffer
2. Heartbeat Play
Content HeartbeatsThe content plays.
The end of the playheadwas reached.
Heartbeat Content CompletetrackComplete()The contentcompletes playing.
SessionEnd means theend of a viewing session.
trackSessionEnd()The session isover.
This API must be calledeven if the user does notwatch the video tocompletion.
40Video Analytics Implementation Guide 2.x forJavaScript
Parameters
Table 11: Heartbeat Buffer
This scenario refers to a rebuffer event, which is when buffering occurs in addition to the initial buffering period thatoccurred when playback first began. All call query parameters are identical to the play heartbeats, except that theevent:type (with a value of buffer after a trackEvent:BufferStart) is called until trackEvent:BufferCompleteor a trackPlay method is called.
NotesValueParameter
"buffer"s:event:type
Playback with buffering in the main content
To view this scenario, enter the following text:
// Set up mediaObject
var mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD
);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// 2. Call trackPlay() when the playback actually starts, i.e., when the // first frame of the ad video is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 3. Track event MediaHeartbeat.Event.BufferStart when the video player // goes into the buffering state and begins to buffer content.
41Video Analytics Implementation Guide 2.x forJavaScript
this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BufferStart);
.......
.......
// 4. Track the MediaHeartbeat.Event.BufferComplete event when the // video player goes into the buffering state and begins to buffer content.this._mediaHeartbeat.trackEvent(MediaHeartbeat.Event.BufferComplete);
.......
.......
// 5. Call trackComplete() when the playback reaches the end, i.e., // when playback completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 6. Call trackSessionEnd() when the playback session is over. This method must // be called even if the user does not watch the video to completion.this._mediaHeartbeat.trackSessionEnd();
........
........
Multiple trackers in parallel - details
In this scenario, there are two sessions running in parallel for two separate videos and using two separate instancesof MediaHeartbeat..
Scenario
This scenario is identical to the Playback with no interruptions scenario, except there are two sessions that arerunning in parallel for two separate videos. Each of these sessions uses a separate instance of MediaHeartbeat.
Unless specified, the network calls are the same as the Playback with no interruptions scenario.
Parameters
Table 12: Heartbeat session
NotesValueParameter
A unique session ID that exists in allof the heartbeat network calls until thetrackSessionEnd() method is called.
Unique session IDs:event:sid
42Video Analytics Implementation Guide 2.x forJavaScript
Multiple trackers in parallel
To view this scenario:
var MediaHeartbeat = ADB.va.MediaHeartbeat;var MediaHeartbeatConfig = ADB.va.MediaHeartbeatConfig;var MediaHeartbeatDelegate = ADB.va.MediaHeartbeatDelegate;
function VideoAnalyticsProvider(player) { if (!player) { throw new Error("Illegal argument. Player reference cannot be null.")
} this._player = player;
//Media Heartbeat initialization var mediaConfig = new MediaHeartbeatConfig(); mediaConfig.trackingServer = Configuration.HEARTBEAT.TRACKING_SERVER; mediaConfig.playerName = Configuration.PLAYER.NAME; mediaConfig.channel = Configuration.HEARTBEAT.CHANNEL; mediaConfig.debugLogging = true; mediaConfig.appVersion = Configuration.HEARTBEAT.SDK; mediaConfig.ssl = false; mediaConfig.ovp = Configuration.HEARTBEAT.OVP;
var mediaDelegate = new MediaHeartbeatDelegate();
mediaDelegate.getCurrentPlaybackTime = function() { return player.getCurrentPlaybackTime(); };
mediaDelegate.prototype.getQoSObject = function() { return player.getQoSInfo(); };
this._mediaHeartbeat = new MediaHeartbeat(mediaDelegate, mediaConfig, appMeasurement);}
// Create first VideoPlayer instance. var _player1 = new VideoPlayer();
43Video Analytics Implementation Guide 2.x forJavaScript
// Create the first VideoAnalyticsProvider instance // and attach it to the VideoPlayer instance. analyticsProvider1 = new VideoAnalyticsProvider(_player1);
// Load the main video content. _player1.loadContent(URL_TO_VIDEO_1);
// Create second VideoPlayer instance. var _player2 = new VideoPlayer();
// Create second VideoAnalyticsProvider instance and// attach it to the VideoPlayer instance. analyticsProvider2 = new VideoAnalyticsProvider(_player2);
// Load the main video content for the 2nd player. _player2.loadContent(URL_TO_VIDEO_2);
Both instances of VideoAnalyticsProvider and MediaHeartbeat track two separate sessions, each with its ownunique session IDs.You can see the two sessions in the Charles debugging tool.
One tracker for multiple sessions - details
In this scenario, the MediaHeartbeat instance is used to create two separate sessions in sequence.
Scenario
This scenario is the same as the Playback with no interruptions scenario.
Parameters
Table 13: Heartbeat Session
NotesValueParameter
A unique session ID that exists in all the heartbeatnetwork calls until trackSessionEnd() is called.
Unique session IDs:event:sid
One tracker for multiple sessions
Figure 2: Multiple tracking sessions: one at a time
var MediaHeartbeat = ADB.va.MediaHeartbeat;var MediaHeartbeatConfig = ADB.va.MediaHeartbeatConfig;var MediaHeartbeatDelegate = ADB.va.MediaHeartbeatDelegate;
function VideoAnalyticsProvider(player) {
44Video Analytics Implementation Guide 2.x forJavaScript
if (!player) { throw new Error("Illegal argument. Player reference cannot be null.") } this._player = player;
// Media Heartbeat initialization var mediaConfig = new MediaHeartbeatConfig(); mediaConfig.trackingServer = Configuration.HEARTBEAT.TRACKING_SERVER; mediaConfig.playerName = Configuration.PLAYER.NAME; mediaConfig.channel = Configuration.HEARTBEAT.CHANNEL; mediaConfig.debugLogging = true; mediaConfig.appVersion = Configuration.HEARTBEAT.SDK; mediaConfig.ssl = false; mediaConfig.ovp = Configuration.HEARTBEAT.OVP;
var mediaDelegate = new MediaHeartbeatDelegate();
mediaDelegate.getCurrentPlaybackTime = function() { return player.getCurrentPlaybackTime(); };
mediaDelegate.prototype.getQoSObject = function() { return player.getQoSInfo(); };
this._mediaHeartbeat = new MediaHeartbeat(mediaDelegate, mediaConfig, appMeasurement);}
// Create the first VideoPlayer instance. var _player1 = new VideoPlayer();
// Create the first VideoAnalyticsProvider instance and// attach it to the VideoPlayer instance. analyticsProvider1 = new VideoAnalyticsProvider(_player1);
// Load the main video content. _player1.loadContent(URL_TO_VIDEO_1);
Live main content
These scenarios provide information about live content.
Live main content - details
In this scenario, there is one live asset with no ads played for 40 secs after joining the live stream.
Scenario
NotesNetwork callsHeartbeat methodTrigger
This can be a userclicking Play or anauto-play event.
trackSessionStart()User clicks Play1. Analytics Content Start
2. Heartbeat Content Start
This method triggers thetimer. Heartbeats are sent
Heartbeat Content PlaytrackPlay()The first frame ofthe video plays.
every 10 seconds as longas playback continues.
Content HeartbeatsThe content plays.
SessionEnd means theend of a viewing session.
trackSessionEnd()The session isover.
45Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
This API must be calledeven if the user does notwatch the video tocompletion.
Parameters
Table 14: Heartbeat Content Start
Many of the same values that you see on Adobe Analytics Content Start Calls you will also see on Heartbeat ContentStart Calls.You will also see lots of other parameters that Adobe uses to populate the various Video reports in AdobeAnalytics. We won't be covering all of them here, only the most important ones.
NotesValueParameter
<Your Adobe Report Suite
ID>
s:sc:rsid
<Your Analytics Tracking
Server URL>
s:sc:tracking_serve
Should match the mid value on the Adobe AnalyticsContent Start Call
s:user:mids:user:mid
"start"s:event:type
"main"s:asset:type
<Your Video Name>s:asset:video_id
lives:stream:type
Custom metadata set on the videooptionals:meta:*
Content Heartbeats
During video playback, there is a timer that will send one or more heartbeats every 10 seconds. These heartbeatscontain information about playback, ads, buffering, and a number of other things.The exact content of each heartbeatis beyond the scope of this document, but the critical thing to validate is that heartbeats are being triggered consistentlywhile playback continues.
In the content heartbeats, look for these specific things:
NotesValueParameter
"play"s:event:type
This should reflect the current positionof the playhead.
<playhead position> e.g., 50, 60,70
l:event:playhead
Heartbeat Content Complete
There will not be a complete call, because the live stream was never completed.
46Video Analytics Implementation Guide 2.x forJavaScript
Live content playback
Here is the expected API call order:
// Set up mediaObjectvar mediaInfo = MediaHeartbeat.createMediaObject(Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart() when Play is clicked or if autoplay // is used, i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// 2. Call trackPlay() when the playback actually starts, i.e., when the // first frame of video is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 3. Call trackSessionEnd() when user ends the playback session. // Since user does not watch live video to completion, there is // no need to call trackComplete().this._mediaHeartbeat.trackSessionEnd();
........
........
Live main content with sequential tracking - details
In this scenario, there is one live asset with no ads played for 40 seconds after joining the live stream.
ScenarioThis scenario is a single LIVE asset with no ads, and multiple episodes that need to be tracked as different sessions.
NotesNetwork callsHeartbeat methodTrigger
This can be either a userclicking Play or an auto-playevent.
trackSessionStart()User clicks Play1. Analytics Content
Start
47Video Analytics Implementation Guide 2.x forJavaScript
NotesNetwork callsHeartbeat methodTrigger
2. Heartbeat Content
Start
This method triggers the timerand from this point forward,
Heartbeat Content PlaytrackPlay()First frame of thecontent plays.
heartbeats will be sent every10 seconds as long asplayback continues.
Content HeartbeatsContent plays
Complete means Session1for the 1st episode was
1. Heartbeat ContentCompletetrackComplete()
trackSessionEnd()
Session1 Over
(Episode1 ended) reached and watchedcompletely. Before startingthe session for the nextepisode, this session must beended.
This is because the userwatched the first episode andAnalytics Content Start
Heartbeat Content Start
trackSessionStart()Episode2 started
(Session2 start) continued watching intoanother episode
This method triggers thetimer, and from this point
Heartbeat Content PlaytrackPlay()1st Frame of Video
forward heartbeats will besent every 10 seconds, aslong as playback continues.
Content HeartbeatsContent Plays
Complete means thatSession2 for the 2nd episode
1. Heartbeat ContentCompletetrackComplete()
trackSessionEnd()
Session Over(Episode2 ended)
was reached and watchedcompletely. Before startingthe session for the nextepisode, this session must beended.
Parameters
Table 15: Heartbeat Content Start
Many of the same values that you see on Adobe Analytics Content Start Calls you will also see on Heartbeat ContentStart Calls.You will also see lots of other parameters that Adobe uses to populate the various Video reports in AdobeAnalytics. We won't be covering all of them here, only the most important ones.
NotesValueParameter
<Your Adobe Report Suite
ID>
s:sc:rsid
<Your Analytics Tracking
Server URL>
s:sc:tracking_serve
48Video Analytics Implementation Guide 2.x forJavaScript
NotesValueParameter
Should match the mid value on the Adobe AnalyticsContent Start Call
s:user:mids:user:mid
"start"s:event:type
"main"s:asset:type
<Your Video Name>s:asset:video_id
lives:stream:type
Custom metadata set on the videooptionals:meta:*
Heartbeat Content Play
This should look almost exactly like the Heartbeat Content Start call, but for the key difference in the "s:event:type"parameter. All parameters should still be in place here.
NotesValueParameter
"play"s:event:type
"main"s:asset:type
Content Heartbeats
During video playback, there is a timer that sends one or more heartbeats every 10 seconds. These heartbeatscontain information about playback, ads, buffering, and a number of other things.The exact content of each heartbeatis beyond the scope of this document, but the critical thing to validate is that heartbeats are being triggered consistentlywhile playback continues.
In the content heartbeats, look for these specific things:
NotesValueParameter
"play"s:event:type
This should reflect the current positionof the playhead.
<playhead position> e.g., 50, 60,70
l:event:playhead
Heartbeat Content Complete
When playback for any given episode has completed (playhead crosses episode boundary), a Heartbeat ContentComplete call is sent. This looks like other Heartbeat Calls, but contains these specific things:
NotesValueParameter
"complete"s:event:type
"main"s:asset:type
49Video Analytics Implementation Guide 2.x forJavaScript
Live main content with sequential tracking
Here is the expected API call order:
// Set up mediaObject
var mediaInfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD);
var videoMetadata = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 1. Call trackSessionStart() when Play is clicked or if autoplay is used, // i.e., there's an intent to start playback.this._mediaHeartbeat.trackSessionStart(mediaInfo, videoMetadata);
......
......
// 2. Call trackPlay() when the playback actually starts, i.e., when the // first frame of video is rendered on the screen.this._mediaHeartbeat.trackPlay();
.......
.......
// 3. Call trackComplete() when the playback reaches the end of a session, // i.e., whn playback completes and finishes playing the 1st episode/session.this._mediaHeartbeat.trackComplete();
........
........
// 4. Call trackSessionEnd() to end session 1this._mediaHeartbeat.trackSessionEnd();
........
........
// Start tracking session 2/episode 2 of the same live stream. There is no need // to reinstantiate a mediaHeartbeat instance for tracking sesison 2.
// Set up mediaObjectvar mediaInfo2 = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.LIVE
50Video Analytics Implementation Guide 2.x forJavaScript
);
var videoMetadata2 = { CUSTOM_KEY_1 : CUSTOM_VAL_1, CUSTOM_KEY_2 : CUSTOM_VAL_2, CUSTOM_KEY_3 : CUSTOM_VAL_3};
// 5. Call trackSessionStart() when the playhead reaches a point that denotes // the start of session 2this._mediaHeartbeat.trackSessionStart(mediaInfo2, videoMetadata2);
......
......
// 6. Call trackPlay() to start tracking session 2 playbackthis._mediaHeartbeat.trackPlay();
.......
.......
// 7. Call trackComplete() when the playback reaches the end of session 2, // i.e., playback completes and finishes playing.this._mediaHeartbeat.trackComplete();
........
........
// 8. Call trackSessionEnd() to end session 2this._mediaHeartbeat.trackSessionEnd();
........
........
// Continue tracking further sessions in live stream similarly if required
API docs
To see the API docs for Video Heartbeat 2.0 in JavaScript, go tohttps://adobe-marketing-cloud.github.io/video-heartbeat-v2/reference/javascript/index.html.
FAQs
This section will be updated as information becomes available.
Contact and Legal Information
Information to help you contact Adobe and to understand the legal issues concerning your use of this product anddocumentation.
Help & Technical Support
The Adobe Experience Cloud Customer Care team is here to assist you and provides a number of mechanisms bywhich they can be engaged:
• Check the Experience Cloud help pages for advice, tips, and FAQs• Ask us a quick question on Twitter @AdobeExpCare
51Video Analytics Implementation Guide 2.x forJavaScript
• Log an incident in our customer portal• Contact the Customer Care team directly• Check availability and status of Experience Cloud Solutions
Service, Capability & Billing
Dependent on your solution configuration, some options described in this documentation might not be available toyou. As each account is unique, please refer to your contract for pricing, due dates, terms, and conditions. If youwould like to add to or otherwise change your service level, or if you have questions regarding your current service,please contact your Account Manager.
Feedback
We welcome any suggestions or feedback regarding this solution. Enhancement ideas and suggestions can beadded to our Customer Idea Exchange.
Legal
© 2018 Adobe Systems Incorporated. All Rights Reserved.Published by Adobe Systems Incorporated.
Terms of Use | Privacy Center
Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in theUnited States and/or other countries. A trademark symbol (®, ™, etc.) denotes an Adobe trademark.
All third-party trademarks are the property of their respective owners. Updated Information/Additional Third PartyCode Information available at http://www.adobe.com/go/thirdparty.
52Video Analytics Implementation Guide 2.x forJavaScript