Adobe Experience Cloud Video Heartbeat 2.x Developer Guide for Android

Transcription

1 Adobe Experience Cloud Video Heartbeat 2.x Developer Guide for Android

2 Contents Video Heartbeat 2.x Developer Guide for Android...3 Release for the Android VideoHeartbeat 2.x SDK3 Getting started on Android...3 Download the Android SDK.4 Implement the Android library...4 Migrating to version 2.x in Android...5 Implementation guide...5 Set up and configure your MediaHeartbeat instance...5 Track core playback7 Track ads.9 Track chapters...11 Standard Metadata Parameters12 Track buffering...13 Seeking.14 QoS updates14 Tracking errors...15 Inactive video sessions and resuming...15 Opt-out and privacy settings...16 Video Measurement Parameters16 Sample player16 Debugging16 Validate implementations...17 Ratings Partners Integration18 Scenarios18 VOD main content18 Live main content45 API docs..51 FAQs51 Contact and Legal Information...51 Last updated 3/16/2018 Video Heartbeat 2.x Developer Guide for Android

3 3 Video Heartbeat 2.x Developer Guide for Android Release for the Android VideoHeartbeat 2.x SDK Included are notes from the latest major revision to the 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 wrong API calls. 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 tracked through one video tracking API, trackevent. Version (July 1, 2016) was the initial release of the 2.x Android libraries. Getting started on Android Before you can use Video Heartbeat 2.x in Android, you must set up a Experience Cloud account, enable the Visitor 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 and workflow of the media player being instrumented. Before you start implementing Video Heartbeat for Android in the next section, ensure that you have completed the following tasks: Set up an Experience Cloud account - Contact an Adobe representative to assist you in setting up an Experience Cloud account for doing video analytics. Implement ADBMobile for Android in your application - For more information about the Adobe Mobile SDK documentation, see Android SDK 4.x for Experience Cloud Solutions. Implement the Visitor ID service - For more information about the Visitor ID service, see Experience Cloud ID Service. Obtain valid configuration parameters for Heartbeats - These parameters can be obtained from an Adobe representative 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 when events occur in your player. An API that provides player information - This information includes details such as the media name and the play head position.

4 4 Download the Android SDK You can download the SDK from the Experience Cloud github page. Download the SDK To download the SDK: 1. Browse to 2. Navigate to the tag which refers to latest library version for Android. 3. Click and download the archive. Implement the Android library After you download the Android 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 Android SDK Before you begin implementing heartbeat tracking in your application, you must set up a mobile SDK, and download the Video Heartbeat SDK. For more information, see the prerequisites in Getting started on Android. 1. Expand the VideoHeartbeatLibrary-android-v2.*.zip file that you downloaded. For information about downloading this file, see Getting started on Android. 2. Verify that the VideoHeartbeat.jar file exists in the libs/ directory: This library is used with Android devices and simulators for video heartbeat tracking APIs. Add the SDK to your project To add the SDK to your project using IntelliJ IDEA: 1. Right click your project in the Project navigation panel. 2. Select Open Module Settings. 3. Under Project Settings, select Libraries. 4. Click + to add a new library. 5. Select Java and navigate to the VideoHeartbeat.jar file. 6. Select the modules in which you plan to use the mobile library. 7. Click Apply and then OK to close the Module Settings window. To add the SDK to your project using Eclipse: 1. In the Eclipse IDE, right-click on the project name. 2. Click Build Path > Add External Archives. 3. Select VideoHeartbeat.jar. 4. Click Open. 5. Right-click the project again, and click Build Path > Configure Build Path. 6. Click the Order and Export tabs. 7. Ensure that the VideoHeartbeat.jar file is selected. Adding app permissions The VideoHeartbeat Library requires the following permissions to send data in tracking calls:

5 5 INTERNET ACCESS_NETWORK_STATE To add these permissions, add the following lines to your AndroidManifest.xml file in the application project directory: <uses-permission android:name="android.permission.internet" /> <uses-permission android:name="android.permission.access_network_state" /> Migrating to version 2.x in Android This information helps you migrate from version 1.5 to 2.x of the Android library. In versions 2.x, all of the public methods are consolidated into the com.adobe.primetime.va.simple.mediaheartbeat class to make it easier on developers. Also, all configs are now consolidated into the com.adobe.primetime.va.simple.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 Android library. 1. Import the library. import com.adobe.primetime.va.simple.mediaheartbeat; import com.adobe.primetime.va.simple.mediaheartbeat.mediaheartbeatdelegate; import com.adobe.primetime.va.simple.mediaheartbeatconfig; import com.adobe.primetime.va.simple.mediaobject; 2. Create the MediaHeartbeatConfig instance. This section helps you to understand MediaHeartbeat config parameters and to set the correct config values on your MediaHeartbeat instance for accurate tracking. Here is the MediaHeartbeatConfig reference: Variable Name Description Required Default Value trackingserver Define the server for tracking media heartbeats. This is different from your analytics tracking server. Empty String channel Channel name property Empty String ovp Name of the online video platform through which content gets distributed. No Empty String

6 6 Variable Name Description Required Default Value appversion Version of the video player app/sdk. unknown playername Name of the video player on use, for example, "AVPlayer", "HTML5 Player", "My Custom VideoPlayer". Empty String ssl Property that indicates whether the heartbeat calls should be made over HTTPS. false debuglogging Gets the preference for debug log output. false Here is a sample MediaHeartbeatConfig initialization: // Media Heartbeat Initialization config.trackingserver = <SAMPLE_HEARTBEAT_TRACKING_SERVER>; config.channel = <SAMPLE_HEARTBEAT_CHANNEL>; config.appversion = <SAMPLE_HEARTBEAT_SDK_VERSION>; config.ovp = <SAMPLE_HEARTBEAT_OVP_NAME>; config.playername = <SAMPLE_PLAYER_NAME>; config.ssl = <true/false>; config.debuglogging = <true/false>; 3. Implement the MediaHeartbeatDelegate interface. Here is the MediaHeartbeatDelegate reference: Method name getqosobject() Description Returns the MediaObject instance that contains the current QoS information. This method will be called multiple times during a playback session. Player implementation must always return the most recently available QoS data. Required Here is the MediaObject (QoS Object) reference: Variable name bitrate startuptime Description The bitrate of media in bits per second The start up time of media in seconds Required

7 7 Variable name fps droppedframes Description The start up time of media in seconds The number of dropped frames so far Required public class VideoAnalyticsProvider implements Observer, MediaHeartbeatDelegate { // Replace <bitrate>, <startuptime>, <fps>, and // <droppeframes> with the current playback QoS public MediaObject getqosobject() { return MediaHeartbeat.createQoSObject(<bitrate>, <startuptime>, <fps>, <droppedframes>); //Replace <currentplaybacktime> with the video player current playback public Double getcurrentplaybacktime() { return <currentplaybacktime>; 4. Create the MediaHeartbeat instance. Use the MediaHertbeatConfig instance and the MediaHertbeatDelegate instance to create the MediaHeartbeat instance. // Replace <MediaHertbeatDelegate> with your delegate instance MediaHeartbeat _heartbeat = new MediaHeartbeat(<MediaHeartbeatDelegate>, config); Important: Make sure that your MediaHeartbeat instance is accessible and does not get deallocated until the end of the video session. This instance will be used for all of the following video tracking events. Track core playback Add the library to your project by completing the tasks in Implement the Android library and Set up and configure your MediaHeartbeat instance. 1. Initial tracking setup - Identify when the user triggers the intention of playback (the user clicks Play and/or autoplay is on) and create a MediaObject instance using the video information. Here is the MediaObject (Media Object) reference: Variable name name mediaid length streamtype Description Video name Video unique identifier Video length Stream type Required

8 8 Here is the MediaHeartbeat.StreamType constants reference: Constant name MediaHeartbeat.StreamType.VOD MediaHeartbeat.StreamType.LIVE MediaHeartbeat.StreamType.LINEAR Description Stream type for Video on Demand (VOD) Stream type for Live content. Stream type for Linear content. // Replace <VIDEO_NAME> with the video name. // Replace <VIDEO_ID> with a video unique identifier. // Replace <VIDEO_LENGTH> with the video length. MediaObject mediainfo = MediaHeartbeat.createMediaObject( <VIDEO_NAME>, <VIDEO_ID>, <VIDEO_LENGTH>, MediaHeartbeat.StreamType.VOD ); 2. Custom video metadata - If you need to attach custom video metadata (Adobe Analytics context data) to the video tracking session, create a HashMap with the keyvalue pairs: HashMap<String, String> videometadata = new HashMap<String, String>(); videometadata.put("isuserloggedin", "false"); videometadata.put("tvstation", "Sample TV Station"); videometadata.put("programmer", "Sample programmer"); 3. Track the intention to start playback - Call tracksessionstart() on the MediaHeartbeat instance to begin tracking a video session: public void onvideoload(observable observable, Object data) { _heartbeat.tracksessionstart(mediainfo, videometadata); Note: 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 duration between tracksessionstart() and trackplay()). If you are not using custom video metadata, simply send an empty object for the data argument in tracksessionstart(). 4. Track the actual start of playback - Identify the event from the video player for the beginning of the video playback (the first frame of the video is rendered on the screen) and call trackplay(). // Video is rendered on the screen) and call trackplay. public void onvideoplay(observable observable, Object data) { _heartbeat.trackplay(); 5. Track the completion of playback - Identify the event from the video player for the completion of the video playback (watched the end of the content) and call trackcomplete(). public void onvideocomplete(observable observable, Object data) { _heartbeat.trackcomplete(); 6. Track the end of the session - Identify the event from the video player for the unloading/closing of the video playback (user closes the video and/or the video completed and unloaded) and call tracksessionend. // Closes the video and/or the video completed and unloaded, // and call tracksessionend(). public void onmainvideounload(observable observable, Object data) {

9 9 _heartbeat.tracksessionend(); Note: tracksessionend() marks the end of a video tracking session. If the session was successfully watched to completion (user watched to the end of the content), make sure that trackcomplete() is called before tracksessionend(). Any other track* API call is ignored after tracksessionend() (except for tracksessionstart() for a new video tracking session). 7. Track all possible pause scenarios - Identify any event from the video player that causes the video to pause and call trackpause. public void onvideopause(observable observable, Object data) { _heartbeat.trackpause(); Pause Scenarios - Identify any scenario in which the Video Player will pause and make sure that trackpause is properly called. The following scenarios all require that your app call trackpause(): The user explicitly hits pause in the app. The player puts itself into the Pause state. The user puts the application into the background, but you want the app to keep the session open. Any type of system interrupt occurs that causes an application to be backgrounded. For example, the user receives a call, or a pop up from another application occurs, but you want the application to keep the session alive to give the user the opportunity to resume the video from the point of interruption. 8. Identify the event from the video player for video play and/or video resume from pause and call trackplay(). // trackplay() public void onvideoplay(observable observable, Object data) { _heartbeat.trackplay(); Tip: This may be the same event source that was used in Step 4. Ensure that each trackpause() API call is paired with a following trackplay() API call when the video playback resumes. Track ads Here is the MediaHeartbeat.Event ad tracking constants reference: Constant name MediaHeartbeat.Event.AdBreakStart MediaHeartbeat.Event.AdBreakComplete MediaHeartbeat.Event.AdStart MediaHeartbeat.Event.AdComplete MediaHeartbeat.Event.AdSkip Description Constant for tracking AdBreak Start event Constant for tracking AdBreak Complete event Constant for tracking Ad Start event Constant for tracking Ad Complete event Constant for tracking Ad Skip event 1. Identify when the AdBreak boundary starts, then create a MediaObject instance using AdBreak information. Here is the MediaObject (AdBreak Object) reference:

10 10 Variable name name position starttime Description AdBreak name AdBreak position AdBreak start time Required // Replace <ADBREAK_NAME> with the AdBreak name. // Replace <POSITION> with a valid position value. // Replace <START_TIME> with the AdBreak start time. MediaObject adbreakinfo = MediaHeartbeat.createAdBreakObject(<ADBREAK_NAME>, <POSITION>, <START_TIME>); 2. Using the track API, track MediaHeartbeat.Event.AdBreakStart event. public void onadbreakstart(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.adbreakstart, adbreakinfo, null); 3. Identify when Ad boundary starts, then create a MediaObject instance using the ad information. Here is the MediaObject (Ad Object) reference: Variable name name adid position length Description Ad name Ad identifier Ad position Ad length Required // 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. MediaObject adinfo = MediaHeartbeat.createAdObject(<AD_NAME> <AD_ID>, <POSITION>, <LENGTH>); 4. Create Ad context HashMap if you intend to provide custom ad metadata while tracking an ad. // Setting Ad Metadata HashMap<String, String> admetadata = new HashMap<String, String>(); admetadata.put("affiliate", "Sample affiliate"); admetadata.put("campaign", "Sample ad campaign"); 5. Using track API, track MediaHeartbeat.Event.AdStart event. public void onadstart(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.adstart, adinfo, admetadata);

11 11 6. Identify when playback hits Ad end boundary and track the MediaHeartbeat.Event.AdComplete event. public void onadcomplete(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.adcomplete, null, null); 7. Optionally, identify if Ad playback did not complete and was skipped. For example, if the user seeks out of the Ad, track the Ad skip event using MediaHeartbeat.Event.AdSkip. public void onadskip(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.adskip, null, null); 8. If there are any additional ads in the same AdBreak, repeat Steps 3 through Identify whether the playback hits the AdBreak end boundary, and on AdBreak complete, track the event using MediaHeartbeat.Event.AdBreakComplete. public void onadbreakcomplete(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.adbreakcomplete, null, null); Track chapters Here is the MediaHeartbeat.Event chapter tracking constants reference: Constant Name MediaHeartbeat.Event.ChapterStart MediaHeartbeat.Event.ChapterComplete MediaHeartbeat.Event.ChapterSkip Description Constant for tracking Chapter Start event Constant for tracking Chapter Complete event Constant for tracking Chapter Skip event 1. Identify when playback hits a chapter start boundary, and when the chapter starts, create a MediaObject instance using the chapter information. Here is the MediaObject (Chapter Object) reference: Variable name name position length starttime Description Chapter name Chapter position Chapter length Chapter start time Required // 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. MediaObject chapterdatainfo = MediaHeartbeat.createChapterObject(<CHAPTER_NAME>, <POSITION>, <LENGTH>, <START_TIME>);

12 12 2. Create the Chapter context data dictionary if you plan to provide custom chapter metadata while tracking chapters. HashMap<String, String> chaptermetadata = new HashMap<String,String>(); chaptermetadata.put("segmenttype", "Sample Segment Type"); chaptermetadata.put("segmentname", "Sample Segment Name"); chaptermetadata.put("segmentinfo", "Sample Segment Info"); 3. Using the track API, track the MediaHeartbeat.Event.ChapterStart event. public void onchapterstart(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.chapterstart, chapterdatainfo, chaptermetadata); 4. Identify if the playback hits a chapter end boundary, and on AdBreak complete, track the event using MediaHeartbeat.Event.ChapterComplete. public void onchaptercomplete(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.chaptercomplete, null, null); 5. Optionally, identify whether Chapter playback did not complete and was skipped. For example, if the user seeks out of the chapter boundary, track the chapter skip event using MediaHeartbeat.Event.ChapterSkip. public void onchapterskip(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.chapterskip, null, null); 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 Implementation for standard ad metadata Here is the Standard Metadata Constants (Standard Metadata Constants) reference: Constant name MediaHeartbeat.MediaObjectKey.StandardVideoMetadata MediaHeartbeat.MediaObjectKey.StandardAdMetadata Description Constant for attaching standard video metadata on Video MediaObject. Constant for attaching standard ad metadata on Ad MediaObject. 1. Create a HashMap of standard Ad metadata key value pairs using the AdMetadataKeys specified above. 2. Set the standard ad metadata dictionary on AdObject using the Standard Metadata constant for ad metadata. 3. Provide this AdObject while invoking trackevent API for MediaHeartbeat.Event.AdStart.

13 13 Here is a sample implementation: // Setting standard Ad Metadata Map <String, String> standardadmetadata = new HashMap<String, String>(); standardadmetadata.put(mediaheartbeat.admetadatakeys.advertiser, "Sample Advertiser"); standardadmetadata.put(mediaheartbeat.admetadatakeys.campaign_id, "Sample Campaign"); adinfo.setvalue(mediaheartbeat.mediaobjectkey.standardadmetadata, standardadmetadata); _heartbeat.trackevent(mediaheartbeat.event.adstart, adinfo, null); Implementation for standard video metadata Here is the Standard Metadata Constants (Standard Metadata Constants) reference: Constant name MediaHeartbeat.MediaObjectKey.StandardVideoMetadata MediaHeartbeat.MediaObjectKey.StandardAdMetadata Description Constant for attaching standard video metadata on Video MediaObject. Constant for attaching standard ad metadata on Ad MediaObject. 1. Create a HashMap of standard Video metadata key value pairs using the VideoMetadataKeys specified above. 2. Set the standard video metadata HashMap on MediaInfo using the Standard Metadata constant for video metadata. 3. Provide this MediaInfo object while invoking the tracksessionstart() API. Here is a sample implementation: // Sample code to set standard Video Metadata Map <String, String> standardvideometadata= new HashMap<String, String>(); standardvideometadata.put(mediaheartbeat.videometadatakeys.episode, "Sample Episode"); standardvideometadata.put(mediaheartbeat.videometadatakeys.show, "Sample Show"); standardvideometadata.put(mediaheartbeat.videometadatakeys.season, "Sample Season"); mediainfo.setvalue(mediaheartbeat.mediaobjectkey.standardvideometadata, standardvideometadata); Track buffering Here is the MediaHeartbeat.Event buffer tracking constants reference: Constant name MediaHeartbeat.Event.BufferStart MediaHeartbeat.Event.BufferComplete Description Constant for tracking the Buffer Start event. Constant for tracking the Buffer Complete event. 1. Listen for the playback buffering events from media player, and on buffer start event notification, track buffering using the MediaHeartbeat.Event.BufferStart event. public void onbufferstart(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.bufferstart, null, null); 2. On buffer complete notification from media player, track the end of buffering using the MediaHeartbeat.Event.BufferComplete event. public void onbuffercomplete(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.buffercomplete,null, null);

14 14 Seeking Here is the MediaHeartbeat.Event seek tracking constants reference: Constant name MediaHeartbeat.Event.SeekStart MediaHeartbeat.Event.SeekComplete Description Constant for tracking Seek Start event. Constant for tracking Seek Complete event. 1. Listen for the playback seeking events from the media player, and on seek start event notification, track seeking using the MediaHeartbeat.Event.SeekStart event. public void onseekstart(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.seekstart, null, null); 2. On seek complete notification from the media player, track the end of seeking using the MediaHeartbeat.Event.SeekComplete event. public void onseekcomplete(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.seekcomplete, null, null); QoS updates Here is the MediaHeartbeat.Event QoS tracking constants reference: Constant name MediaHeartbeat.Event.BitrateChange Description Constant for tracking bitrate change. 1. Listen for the QoS updates from the media player, and on a bitrate change event notification, create a the MediaObject with QoS information. MediaObject (QoS Object) reference: Variable bitrate startuptime fps droppedframes Description Current bitrate Startup time FPS value Number of dropped frames Required // Replace <BITRATE> with the updated bitrate value // Replace <STARTUP_TIME> with a startup time value // Replace <FPS> with the fps value // Replace <DROPPED_FRAMES> with dropped frames MediaObject qosobject = MediaHeartbeat.createQoSObject(<BITRATE>, <STARTUP_TIME>, <FPS>, <DROPPED_FRAMES>);

15 15 2. Track bitrate change using MediaHeartbeat.Event.BitrateChange event. public void onbitratechange(observable observable, Object data) { _heartbeat.trackevent(mediaheartbeat.event.bitratechange, qosobject, null); Tracking errors Before you configure error tracking, see Implement the Android library. To track video player errors: public void onplayererror(observable observable, Object data) { _heartbeat.trackerror("videoerrorid"); Note: Tracking video player errors will not stop the video tracking session. If the video player error prevents the playback from continuing, make sure that the video tracking session is closed by calling tracksessionend() after calling trackerror(). Inactive video sessions and resuming Prerequisite: Before you configure the resuming of inactive video sessions, see Core playback tracking and Adding pause and other interruptions in Implement the Android library. Long pauses Media Heartbeat (VHL) automatically tracks how long the video playback is in one of the following inactive states: Paused Seeking Stalled Buffering If a video tracking session remains in an inactive state for longer than 30 minutes, the session will automatically be closed. If the user resumes after a previously inactive video tracking session (trackplay()), Media Heartbeat automatically creates a new video session using the previously used video information and metadata, and sends a resume heartbeat event. For more information, see Video Measurement Parameters. Manually resume a previously closed session VHL will only automatically resume sessions if the application was not closed. If the application stores user data and has the capability to resume a previously closed video, it is possible to manually trigger a resume event. When starting the video tracking session, set the optional property MediaHeartbeat.MediaObjectKey.VideoResumed to true. // Set MediaHeartbeat.MediaObjectKey.VideoResumed to true public void onvideoload(observable observable, Object data) { // Replace <VIDEO_NAME> with the video name. // Replace <VIDEO_ID> with a video unique identifier. // Replace <VIDEO_LENGTH> with the video length.

16 16 MediaObject mediainfo = MediaHeartbeat.createMediaObject( <VIDEO_NAME>, <VIDEO_ID>, <VIDEO_LENGTH>, MediaHeartbeat.StreamType.VOD ); // Set to true if this is a resume playback scenario mediainfo.setvalue(mediaheartbeat.mediaobjectkey.videoresumed, true); _heartbeat.tracksessionstart(mediainfo, videometadata); Opt-out and privacy settings You can control whether Video Heartbeat activity is allowed on a specific device. The MediaHeartbeat object respects the AdobeMobileLibrary s privacy and opt-out settings. To opt-out of Video Heartbeat tracking, you need to opt out using the AdobeMobile Library. For more information on the AdobeMobileLibrary s opt-out and privacy settings, see Opt-Out and Privacy Settings. Video Measurement Parameters List of data-collection parameters sent by video heartbeat. This section contains the following information: 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. You can enable or disable logging for MediaHeartbeat. The video heartbeat library provides an extensive tracing/logging mechanism that is put in place throughout the entire video-tracking stack. You can enable or disable this logging for video heartbeat library by setting the debuglogging flag on the MediaHeartbeatConfig object. The log messages follow this format: Format: [<timestamp>] [<level>] [<tag>] [<message>] Example: [16:01:48 GMT ] [INFO] [com.adobe.primetime.va.plugins.videoplayer::videoplayerplugin] \ Data from delegate > ChapterInfo: name=first chapter, length=15, position=1, starttime=0

17 17 Sample code to debug logging Here is some code to enable debug logging: // Media Heartbeat initialization MediaHeartbeatConfig config = new MediaHeartbeatConfig(); config.debuglogging = true; // Use this space for setting other config values MediaHeartbeat _heartbeat = new MediaHeartbeat(this, config); There are several sections delimited by pairs of square brackets as follows: 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 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 search through the logs for the string #track. This will highlight all the track*.() APIs called by your application. For instance, this is what the logs filtered for #track could look like: [17:47:48 GMT+0200 (EET).942] [INFO] [plugin::player] #trackvideoload() [17:47:48 GMT+0200 (EET).945] [INFO] [plugin::player] #trackplay() [17:47:48 GMT+0200 (EET).945] [INFO] [plugin::player] #trackplay() > Tracking session autostart. [17:47:48 GMT+0200 (EET).945] [INFO] [plugin::player] #tracksessionstart() [17:47:49 GMT+0200 (EET).446] [INFO] [plugin::player] #trackchapterstart() [17:47:49 GMT+0200 (EET).446] [INFO] [plugin::player] #trackchaptercomplete() [17:48:10 GMT+0200 (EET).771] [INFO] [plugin::player] #trackcomplete() [17:48:10 GMT+0200 (EET).774] [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 / HTTPS traffic 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 server example: <visitornamespace>.sc.omtrdc.net. Heartbeats platform: Heartbeat platform hits (heartbeats) are sent throughout the video tracking session at 10 seconds intervals (out of band events might 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.

18 18 Adobe Debug Optionally, you can debug payloads (Heartbeat and Adobe Analytics) going out of Video Heartbeat Library using the 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 you gain access to Adobe Debug, go to Adobe Debug help to see the help information. Ratings Partners Integration Parter Nielsen Documentation Digital Content Ratings powered by Adobe Scenarios Scenarios help you understand how video heartbeat works for a variety of features on the different platforms. For more information about setting up a scenario in Android, see Set up and configure your MediaHeartbeat instance. 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 Trigger Heartbeat method Network calls User clicks Play tracksessionstart() 1. Analytics Content Start 2. Heartbeat Content Start This can be either a user clicking Play or an auto-play event. First frame of the video trackplay() Heartbeat Content Play This method triggers the timer, and from this point forward, heartbeats will be sent every 10 seconds for the duration of the playback. Content plays Content Heartbeats Content is complete trackcomplete() Heartbeat Content Complete Complete means that the end of the playhead was reached.

19 19 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 Content Start Calls. There are many parameters that Adobe uses to populate the various video reports, but only the most important parameters are listed in the following table: Parameter s:sc:rsid s:sc:tracking_server s:user:mid s:event:type s:asset:type s:asset:video_id s:meta:* Value <Your Adobe Report Suite ID> <Your Analytics Tracking Server URL> This must be set. "start" "main" <Your Video Name> optional Should match the mid value on the Adobe Analytics Content Start call. Custom metadata that is set on the video. Table 2: Heartbeat Content Play These parameters should look nearly identical to the Heartbeat Content Start call, but the key difference is the s:event:type parameter. All of the other parameters should still exist. Parameter s:event:type s:asset:type Value "play" "main" Table 3: Content heartbeats During video playback, a timer sends at least one heartbeat every 10 seconds. These heartbeats contain information about 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: Parameters s:event:type l:event:playhead Value "play" <playhead position> e.g., 50, 60, 70 This parameter reflects the current position of the playhead. Table 4: Heartbeat Content Complete When playback has completed, which means that the end of the playhead is reached, a Heartbeat Content Complete call is sent. This call looks like other Heartbeat calls, but it contains some specific parameters: Parameters s:event:type Value "complete"

20 20 Parameters s:asset:type Value "main" Playback with no interruptions Scenario: Content is 40 seconds long, played until the end, without any interruption. To view this scenario in Android, set up the following code: // Set up mediaobject MediaObject mediainfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD ); HashMap<String, String> videometadata = new HashMap<String, String>(); videometadata.put(custom_val_1, CUSTOM_KEY_1); videometadata.put(custom_val_2, CUSTOM_KEY_2); // 1. Call tracksessionstart() when the user clicks Play or if autoplay // is used, i.e., there's an intent to start playback. _mediaheartbeat.tracksessionstart(mediainfo, videometadata); // 2. Call trackplay() when the playback actually starts, // i.e., the first frame of video is rendered on the screen. _mediaheartbeat.trackplay(); // 3. Call trackcomplete() when the playback reaches the end, // i.e., when the video completes and finishes playing. _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. _mediaheartbeat.tracksessionend();..

21 21 VOD playback with pre-roll ads - details 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 scenario.the network calls happen at the same time, but the payload is different. Trigger The user clicks Play. The ad starts. The frame of ad #1 is played. The ad is played. Ad #2 completes playing. The first frame of ad #2 is played. The ad plays. Ad #2 completes playing. Heartbeat method tracksessionstart() Network calls 1. Analytics Content Start 2. Heartbeat Content Start trackevent:adbreakstart 1. Analytics Ad Start trackevent:adstart 2. Heartbeat Ad Start trackplay() trackevent:trackadcomplete trackevent:adstart trackevent:trackadcomplete trackevent:adbreakcomplete Heartbeat Ad Play Ad Heartbeats Heartbeat Ad Complete 1. Analytics Ad Start 2. Heartbeat Ad Start Ad Heartbeats Heartbeat Ad Complete The measurement library does not know that there is a pre-roll ad, so these network calls are still identical to the Playback with no interruptions scenario. The ad content plays before the main content, and the heartbeats start when the ad starts. The end of the ad is reached. The end of the ad and the pod is reached. The content plays. Content Heartbeats This network call is identical to the Playback with no interruptions scenario. The content is complete. trackcomplete() Heartbeat Content Complete This network call is identical to the Playback with no interruptions scenario. The session is over. tracksessionend() SessionEnd means the end of a viewing session. This API must be called even if the user does not watch the video to completion.

22 22 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 the 10-second timer, the Heartbeat Ad Start call is delayed by a few seconds, and the call goes to the next 10-second interval. When this happens, a Content Heartbeat goes out in the same interval, and you can differentiate between the two calls by looking at the event type and the asset type: Parameter s:event:type s:asset:type Value "start" "ad" 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. Parameter s:event:type s:asset:type Value "play" "ad" Table 7: Ad Heartbeats These parameters are similar to the Content Heartbeats call, but the Ad Heartbeats call contains a few extra parameters: Parameter s:event:type s:asset:type s:asset:ad_id s:asset:pod_id Value "play" "ad" <ad ID> <ad 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 is reached, a Heartbeat Ad Complete call is sent. This call looks like other Heartbeat Ad calls but contains a couple specific things: Parameter s:event:type s:asset:type Value "complete" "ad"

23 23 Playback with a pre-roll ad break To view this scenario in Android, set up the following code: // Set up mediaobject MediaObject mediainfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD ); HashMap<String, String> videometadata = new HashMap<String, String>(); videometadata.put(custom_key_1, CUSTOM_VAL_1); videometadata.put(custom_key_2, CUSTOM_VAL_2); // 1. Call tracksessionstart() when the user clicks Play or if autoplay is used, // i.e., there's an intent to start playback. _mediaheartbeat.tracksessionstart(mediainfo, videometadata); // Pre-roll MediaObject adbreakinfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME); MediaObject adinfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION, AD_LENGTH); // Context ad data HashMap<String, String> admetadata = new HashMap<String, String>(); admetadata.put(custom_key_1, CUSTOM_VAL_1); admetadata.put(custom_key_2, CUSTOM_VAL_2); // 2. Track the MediaHeartbeat.Event.AdBreakStart event when the pre-roll pod starts // to play. Note that since this is a pre-roll, call must track the // "MediaHeartbeat.Event.AdBreakStart" event before you call trackplay(). _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakstart, adbreakinfo, null); // 3. Track the MediaHeartbeat.Event.AdStart event when the pre-roll pod's ad starts // to play. Note that since this is a pre-roll, you must track the // "MediaHeartbeat.Event.AdStart" event before you call trackplay(). _mediaheartbeat.trackevent(mediaheartbeat.event.adstart, adinfo, admetadata);

24 24 // 4. Call trackplay() when the playback actually starts, i.e., when the first frame // of the ad video 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. _mediaheartbeat.trackevent(mediaheartbeat.event.adcomplete, null, null); // 6. Track the MediaHeartbeat.Event.AdStart event when the pre-roll pod's second ad // starts to play. _mediaheartbeat.trackevent(mediaheartbeat.event.adstart, adinfo, admetadata); // 7. Track the MediaHeartbeat.Event.AdComplete event when the second ad reaches the // end, i.e., the second ad completes and finishes playing. _mediaheartbeat.trackevent(mediaheartbeat.event.adcomplete, null, null); // 8. Track the MediaHeartbeat.Event.AdBreakComplete event when all of the ads in the // pod finish playing. _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakcomplete, null, null); // 9. Call trackcomplete() when the playback reaches the end, i.e., when the video // completes and finishes playing. _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. _mediaheartbeat.tracksessionend();.. Playback with ad breaks Scenario: Pre-roll ads, the main content, mid-roll ads, the main content, and post-roll ads.

25 25 To view this scenario in Android, set up the following code: // Set up mediaobject MediaObject mediainfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD ); HashMap<String, String> videometadata = new HashMap<String, String>(); videometadata.put(custom_key_1, CUSTOM_VAL_1); videometadata.put(custom_key_2, CUSTOM_VAL_2); // 1. Call tracksessionstart() when the user clicks Play or if autoplay is used, // i.e., there's an intent to start playback. _mediaheartbeat.tracksessionstart(mediainfo, videometadata); // Pre-roll MediaObject adbreakinfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME); MediaObject adinfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION, AD_LENGTH); // Context ad data HashMap<String, String> admetadata = new HashMap<String, String>(); admetadata.put(custom_key_1, CUSTOM_VAL_1); admetadata.put(custom_key_2, CUSTOM_VAL_2); // 2. Track the MediaHeartbeat.Event.AdBreakStart event when the pre-roll pod // starts to play. Note that since this is a pre-roll, you must track the // "MediaHeartbeat.Event.AdBreakStart" event before you call trackplay(). _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakstart, adbreakinfo, null); // 3. Track the MediaHeartbeat.Event.AdStart event when the pre-roll pod's ad // starts to play. Note that since this is a pre-roll, you must track the // "MediaHeartbeat.Event.AdStart" event before you call trackplay(). _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. _mediaheartbeat.trackevent(mediaheartbeat.event.adcomplete, null, null); // 6. Track the MediaHeartbeat.Event.AdBreakComplete event when all of the ads in //; the pod finish playing. _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakcomplete, null, null);

26 26 // Mid-roll MediaObject adbreakinfo = MediaHeartbeat.createAdBreakObject(mid-roll_BREAK_NAME, mid-roll_break_position, mid-roll_break_start_time); MediaObject adinfo = MediaHeartbeat.createAdObject(mid-roll_AD_NAME, mid-roll_ad_id, mid-roll_ad_position, mid-roll_ad_length); // Context ad data HashMap<String, String> admetadata = new HashMap<String, String>(); admetadata.put(custom_key_1, CUSTOM_VAL_1); admetadata.put(custom_key_2, CUSTOM_VAL_2); // 7. Track the MediaHeartbeat.Event.AdBreakStart event when the mid-roll pod // starts to play. _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakstart, adbreakinfo, null); // 8. Track the MediaHeartbeat.Event.AdStart event when the mid-roll pod's ad // starts to play. _mediaheartbeat.trackevent(mediaheartbeat.event.adstart, adinfo, admetadata); // 9. Track the MediaHeartbeat.Event.AdComplete event when the ad reaches the end, // i.e., when the adcompletes and finishes playing. _mediaheartbeat.trackevent(mediaheartbeat.event.adcomplete, null, null); // 10. Track the MediaHeartbeat.Event.AdBreakComplete event when all the ads in the // mid-roll pod finish playing. _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakcomplete, null, null); // Post-roll MediaObject adbreakinfo = MediaHeartbeat.createAdBreakObject(POSTROLL_BREAK_NAME, POSTROLL_BREAK_POSITION, POSTROLL_BREAK_START_TIME); MediaObject adinfo = MediaHeartbeat.createAdObject(POSTROLL_AD_NAME, POSTROLL_AD_ID, POSTROLL_AD_POSITION, POSTROLL_AD_LENGTH); // Context ad data HashMap<String, String> admetadata = new HashMap<String, String>(); admetadata.put(custom_key_1, CUSTOM_VAL_1); admetadata.put(custom_key_2, CUSTOM_VAL_2); // 11. Track the MediaHeartbeat.Event.AdBreakStart event when the post-roll pod // starts to play. _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakstart, adbreakinfo, null);

27 27 // 12. Track the MediaHeartbeat.Event.AdStart event when the post-roll pod's // ad starts to play. _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. _mediaheartbeat.trackevent(mediaheartbeat.event.adcomplete, null, null); // 14. Track the MediaHeartbeat.Event.AdBreakComplete event when all the ads in // the post-roll pod finish playing. _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakcomplete, null, null); // 15. Call trackcomplete() when the playback reaches the end, i.e., when the // video completes and finishes playing. _mediaheartbeat.trackcomplete();.. // 16. Call tracksessionend() when the playback session is over. This method // must be called even if the user does not watch the video to completion. _mediaheartbeat.tracksessionend();.. VOD playback with skipped ads - details Scenario: 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 a pre-roll ad break, except the application has a provision to let the user skip the ad, on the click of a skip button perhaps. Trigger User clicks Play The ad starts. Heartbeat method tracksessionstart() Network calls 1. Analytics Content Start 2. Heartbeat Content Start trackevent:adbreakstart 1. Analytics Ad Start trackevent:adstart 2. Heartbeat Ad Start The measurement library i unaware that there is a pre-roll ad. These network calls are still exactly the same as Playback with no interruptions scenario. The first frame of the ad is played. trackplay() Heartbeat Ad Play When ad content plays before main content, the

28 28 Trigger Heartbeat method Network calls heartbeats will start when the ad starts to play. The ad plays. trackevent:trackadskip Ad Heartbeats The ad is skipped. trackevent:trackadskip There is no ad complete network call. The content plays. Content Heartbeats These network calls are exactly the same as the Playback with no interruptions scenario. The content completes playing. trackcomplete() Heartbeat Content Complete This network call is exactly the same as the Playback with no interruptions scenario. The session is over. tracksessionend() SessionEnd means the end of a viewing session. This API must be called even if the user does not watch the video to completion. Parameters The parameters are identical to the parameters in the VOD playback with pre-roll ads - details scenario, except there is no ad complete and no ad-break complete call. Playback with skipped ads To view this scenario in Android, set up the following code: // Set up mediaobject MediaObject mediainfo = MediaHeartbeat.createMediaObject( Configuration.VIDEO_NAME, Configuration.VIDEO_ID, Configuration.VIDEO_LENGTH, MediaHeartbeat.StreamType.VOD ); HashMap<String, String> videometadata = new HashMap<String, String>(); videometadata.put(custom_key_1, CUSTOM_VAL_1); videometadata.put(custom_key_2, CUSTOM_VAL_2); // 1. Call tracksessionstart() when the user clicks Play or if autoplay is used, // i.e., there is an intent to start playback.

29 29 _mediaheartbeat.tracksessionstart(mediainfo, videometadata); // Pre-roll MediaObject adbreakinfo = MediaHeartbeat.createAdBreakObject(ADBREAK_NAME, ADBREAK_POSITION, ADBREAK_START_TIME); MediaObject adinfo = MediaHeartbeat.createAdObject(AD_NAME, AD_ID, AD_POSITION, AD_LENGTH); // Context ad data HashMap<String, String> admetadata = new HashMap<String, String>(); admetadata.put(custom_key_1, CUSTOM_VAL_1); admetadata.put(custom_key_2, CUSTOM_VAL_2); // 2. Track the MediaHeartbeat.Event.AdBreakStart event when the pre-roll pod starts to play. // Note that since this is a pre-roll, track the "MediaHeartbeat.Event.AdBreakStart" // event before you call trackplay(). _mediaheartbeat.trackevent(mediaheartbeat.event.adbreakstart, adbreakinfo, null); // 3. Track the MediaHeartbeat.Event.AdStart event when the pre-roll pod's ad starts to play. // Note that since this is a pre-roll, track the "MediaHeartbeat.Event.AdStart" event // before you call trackplay(). _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.AdSkip event when the user intends to and is able to // skip an ad. For example, this could be tied to a "Skip Ad" button onclick handler. // The application could have the viewer land in main content post ad. _mediaheartbeat.trackevent(mediaheartbeat.event.adskip, null, null); // 6. Call trackcomplete() when the playback reaches the end, i.e., when the video // completes and finishes playing. _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. _mediaheartbeat.tracksessionend();..