Adobe Marketing Cloud Video Heartbeat 2.x Developer's Guide for ios

Transcription

1 Adobe Marketing Cloud Video Heartbeat 2.x Developer's Guide for ios

2 Contents Video Heartbeat 2.x Developer Guide for ios...4 Release notes for the ios VideoHeartbeat 2.x SDK4 Getting started..4 Download the ios SDK5 Implement the ios library...5 Migrating to version 2.x in ios...7 Implementation guide...7 Set up and configure your MediaHeartbeat instance...7 Track core playback...9 Track ads...11 Track chapters...13 Standard Metadata Parameters...14 Track buffering...16 Seeking.16 QoS updates17 Tracking errors...18 Inactive video sessions and resuming...18 Opt-out and privacy settings...19 AppleTV implementation guide with tvos19 Configure a Native App for tvos...19 Video Measurement Parameters19 Sample player20 Ratings Partners Integration20 Debugging...20 Validate implementations...21 Scenarios21 VOD main content...21 Live main content49 API docs..54 Last updated 9/28/2017 Video Heartbeat 2.x Developer's Guide for ios

3 Contents FAQs54 Contact and Legal Information...54 Last updated 9/28/2017 Video Heartbeat 2.x Developer's Guide for ios

4 4 Video Heartbeat 2.x Developer Guide for ios Release notes for the ios 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, ADBMediaHeartbeat. 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) is the initial release of the 2.x ios libraries. Getting started Before you can use Video Heartbeat 2.0 in ios, you must set up a Marketing 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 ios in the next section, ensure that you have completed the following tasks: Set up a Marketing Cloud account - Contact an Adobe representative to assist you in setting up a Marketing Cloud account for doing video analytics. Implement ADBMobile for ios in your application - For more information about the Adobe Mobile SDK documentation, see ios SDK 4.x for Marketing Cloud Solutions. Implement the Visitor ID service - For more information about the Visitor ID service, see Marketing 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.

5 5 An API that provides player information - This information includes details such as the media name and the play head position. Download the ios SDK Download the SDK To download the SDK: 1. Browse to 2. Navigate to the tag that refers to the latest library version for ios. 3. Click and download the archive. Implement the ios library After you download the ios 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 ios SDK Important: Before you get the SDK, you must set up a mobile SDK and download the Video Heartbeat SDK. For more information, see Getting started. 1. Expand the VideoHeartbeatLibrary-ios-tvos-v2.*.zip. For more information about downloading this file, see Getting started. 2. Verify that the following software components exist in the libs directory: ADBMediaHeartbeat.h: The Objective-C header file that is used for ios video heartbeat tracking APIs. ADBMediaHeartbeatConfig.h: The Objective-C header file for the SDK configuration. VideoHeartbeat.a: A bitcode-enabled fat binary that contains the library builds for ios devices (armv7, armv7s, arm64) and simulators (i386 and x86_64). This binary should be linked when target is intended for an ios app. VideoHeartbeat_TV.a: A bitcode-enabled fat binary containing the library builds for new Apple TV devices (arm64) and simulator (x86_64). This binary should be linked when the target is intended for an Apple TV (tvos) app. This library is used with ios devices and simulators for video heartbeat tracking APIs. Add the SDK to your project To add the SDK to your project: 1. Launch the Xcode IDE and open your app. 2. In Project Navigator, drag the libs directory and drop it under your project. 3. Ensure that the Copy Items if Needed checkbox is selected, the Create Groups is selected, and none of the checkboxes in Add to Target are selected.

6 6 4. Click Finish. 5. In Project Navigator, select your app and select your targets. 6. Link the required frameworks and libraries in the Linked Frameworks and Libraries section on the General tab: ios App Targets Apple TV (tvos) Target:

7 7 AdobeMobileLibrary_TV.a VideoHeartbeat_TV.a libsqlite3.0.tbd SystemConfiguration.framework 7. Verify that your app builds without errors. Migrating to version 2.x in ios This information helps you migrate from version 1.5 to version 2.x of the ios library. In version 2.x, all of the public methods are consolidated into the ADBMediaHeartbeat class to make it easier on developers. All configurations have been consolidated into the ADBMediaHeartbeatConfig 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 ios library. 1. Import the library. #import "ADBMediaHeartbeat.h" #import "ADBMediaHeartbeatConfig.h" 2. Create a ADBMediaHeartbeatConfig instance. This section helps you to understand the MediaHeartbeat config parameters, and to set correct config values on your MediaHeartbeat instance for accurate tracking.

8 8 Here is the ADBMediaHeartbeatConfig 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. unknown appversion Version of the video player app/sdk. unknown playername Name of the video player on use, i.e., "AVPlayer", "HTML5 Player", "My Custom VideoPlayer". Empty String ssl Property that indicates whether the heartbeat calls should be made over HTTPS. No debuglogging Gets the preference for debug log output. No Here is a sample ADBMediaHeartbeatConfig initialization: // Media Heartbeat Initialization ADBMediaHeartbeatConfig *config = [[ADBMediaHeartbeatConfig alloc] init]; 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 = <YES/NO>; config.debuglogging = <YES/NO>; 3. Implement the ADBMediaHeartbeatDelegate protocol. Here is the ADBMediaHeartbeatDelegate reference: Method name getqosobject Description Returns the ADBMediaObject instance containing 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 ADBMediaObject (QoS Object) reference:

9 9 Variable name bitrate startuptime fps droppedframes Description The bitrate of media in bits per second The start up time of media in seconds The start up time of media in seconds The number of dropped frames so far VideoAnalyticsProvider : VideoAnalyticsProvider // Replace <bitrate>, <startuptime>, <fps> and <droppeframes> // with the current playback QoS values. - (ADBMediaObject *)getqosobject { return [ADBMediaHeartbeat createqosobjectwithbitrate:<bitrate> startuptime:<startuptime> fps:<fps> droppedframes:<droppedframes>]; // Return the current video player playhead position. // Replace <currentplaybacktime> with the video player current playback time - (NSTimeInterval)getCurrentPlaybackTime { return 4. Use the ADBMediaHeartBeatConfig and ADBMediaHeartBeatDelegate to create the ADBMediaHeartbeat instance. //Replace <ADBMediaHeartBeatDelegate> with your delegate instance _mediaheartbeat = [[ADBMediaHeartbeat alloc] initwithdelegate: <ADBMediaHeartBeatDelegate> config:config]; Important: Make sure that your ADBMediaHeartbeat instance is accessible and does not get deallocated until the end of the video session. This instance will be used for all the following video tracking events. Track core playback Add the library to your project by completing the tasks in Implement the ios library and Set up and configure your MediaHeartbeat instance. 1. Identify when the user triggers the intention of playback (the user clicks Play and/or autoplay is on) and create an ADBMediaObject instance using the video information. Here is the ADBMediaObject (Media Object) Reference:

10 10 Variable name name mediaid length streamtype Description Video name. Video unique identifier. Video length Stream type (see constants ADBMediaHeartbeatStreamType) Required Here is the ADBMediaHeartbeatStreamType constants reference: Constant name ADBMediaHeartbeatStreamTypeVOD ADBMediaHeartbeatStreamTypeLIVE ADBMediaHeartbeatStreamTypeLINEAR Description Stream type for Video on Demand. Stream type for LIVE content. Stream type for LINEAR content. // Replace <VIDEO_NAME> with the video name. // Replace <VIDEO_ID> with a unique video identifier. // Replace <VIDEO_LENGTH> with the video length. ADBMediaObject *mediaobject = [ADBMediaHeartbeat createmediaobjectwithname:<video_name> mediaid:<video_id> length:<video_length> streamtype:adbmediaheartbeatstreamtypevod]; 2. Call tracksessionstart in the ADBMediaHeartbeat instance to begin tracking a video session: - void)onmainvideoloaded:(nsnotification *)notification { [_mediaheartbeat tracksessionstart:mediaobject Note: The tracksessionstart call 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). 3. Identify the event from the video player for the beginning of the video playback (the first frame of the main content is rendered on the screen) and call trackplay. -(void)onvideoplay:(nsnotification *)notification { [_mediaheartbeat trackplay]; 4. Identify the event from the video player for the completion of the video playback (user watched to the end of the content) and call trackcomplete. -(void)onvideocomplete:(nsnotification *)notification { [_mediaheartbeat trackcomplete]; 5. 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. - void)onmainvideounloaded:(nsnotification *)notification { [_mediaheartbeat tracksessionend];

11 11 Note: tracksessionend marks the end of a video tracking session. If the session was successfully watched to completion (the 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). 6. Identify the event from the video player for video paused and call trackpause. -(void)onvideopause:(nsnotification *)notification { [_mediaheartbeat trackpause]; Note: Identify any scenario in which the Video Player will pause and make sure that trackpause is properly called. For example: The application goes to the background, the video pauses, etc. 7. Identify the event from the video player for video play and/or video resume from pause and call trackplay. -(void)onvideoplay:(nsnotification *)notification { [_mediaheartbeat trackplay]; Note: This might be the same event source that was used for "How to track video playback". Make sure that each trackpause API call is paired with a following trackplay API call when the video playback resumes Track ads Here is the ADBMediaHeartbeatEvent Ad tracking constants reference: Constant name ADBMediaHeartbeatEventAdBreakStart ADBMediaHeartbeatEventAdBreakComplete ADBMediaHeartbeatEventAdStart ADBMediaHeartbeatEventAdComplete ADBMediaHeartbeatEventAdSkip 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 AdBreak boundary starts, then create ADBMediaObject instance using AdBreak information. Here is the ADBMediaObject (AdBreak Object) Reference: 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. id adbreakobject = [ADBMediaHeartbeat createadbreakobjectwithname:[adbreak_name] position:[position] starttime:[start_time]];

12 12 2. Using track API, track ADBMediaHeartbeatEventAdBreakStart event. - (void)onadbreakstart:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakstart mediaobject:adbreakobject 3. Identify when Ad boundary starts, then create ADBMediaObject instance using Ad information. Here is the ADBMediaObject (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. id adobject = [ADBMediaHeartbeat createadobjectwithname:[ad_name] adid:[ad_id] position:[position] length:[length]]; 4. Create Ad context data dictionary if you intend to provide custom ad metadata while tracking an ad. NSMutableDictionary *addictionary = [[NSMutableDictionary alloc] init]; [addictionary setobject:@"sample affiliate" forkey:@"affiliate"]; [addictionary setobject:@"sample campaign" forkey:@"campaign"]; [addictionary setobject:@"sample creative" forkey:@"creative"]; 5. Using track API, track ADBMediaHeartbeatEventAdStart event. - (void)onadstart:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adobject data:addictionary]; 6. Identify when playback hits Ad end boundary, then track ADBMediaHeartbeatEventAdComplete event. - (void)onadcomplete:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventadcomplete mediaobject:nil 7. Optionally, identify if Ad playback did not complete and was skipped, ex; if user seeks out of the Ad, you should track the Ad skip event using ADBMediaHeartbeatEventAdSkip. - (void)onadskip:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventadskip mediaobject:nil 8. If there are any additional ads within the same AdBreak, repeat Steps 3 through Identify if the playback hits AdBreak end boundary. On AdBreak complete, track the event using ADBMediaHeartbeatEventAdBreakComplete. - (void)onadbreakcomplete:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakcomplete

13 13 mediaobject:nil Track chapters 1. Identify when playback hits chapter start boundary. On chapter start create ADBMediaObject instance using Chapter information. Here is the ADBMediaObject (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. id chapterobject = [ADBMediaHeartbeat createchapterobjectwithname:[chapter_name] position:[position] length:[length] starttime:[start_time]]; 2. Create Chapter context data dictionary if you intend to provide custom chapter metadata while tracking chapter. NSMutableDictionary *chapterdictionary = [[NSMutableDictionary alloc] init]; [chapterdictionary setobject:@"sample segment type" forkey:@"segmenttype"]; [chapterdictionary setobject:@"sample segment name" forkey:@"segmentname"]; [chapterdictionary setobject:@"sample segment info" forkey:@"segmentinfo"]; 3. Using track API, track ADBMediaHeartbeatEventChapterStart event. - (void)onchapterstart:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventchapterstart mediaobject:chapterobject data:chapterdictionary]; 4. Identify if the playback hits a Chapter end boundary. On chapter complete, track the event using ADBMediaHeartbeatEventChapterComplete. - (void)onchaptercomplete:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventchaptercomplete mediaobject:nil 5. Optionally, identify if Chapter playback did not complete and was skipped. If for example, the user seeks out of the chapter boundary, rack chapter skip event using ADBMediaHeartbeatEventChapterSkip. - (void)onchapterskip:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventchapterskip mediaobject:nil

14 14 6. If there are any additional chapters, repeat Steps 1 through 5. Standard Metadata Parameters The list of video and ad data-collection parameters that are sent by video heartbeat. 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. Standard metadata keys Here is the ADBStandardMetadataKeys.h reference: Constant name ADBVideoMetadataKeySHOW ADBVideoMetadataKeySEASON ADBVideoMetadataKeyEPISODE ADBVideoMetadataKeyASSET_ID ADBVideoMetadataKeyGENRE ADBVideoMetadataKeyFIRST_AIR_DATE ADBVideoMetadataKeyFIRST_DIGITAL_DAT ADBVideoMetadataKeyRATING ADBVideoMetadataKeyORIGINATOR ADBVideoMetadataKeyNETWORK ADBVideoMetadataKeySHOW_TYPE ADBVideoMetadataKeyAD_LOAD ADBVideoMetadataKeyMVPD ADBVideoMetadataKeyAUTHORIZED ADBVideoMetadataKeyDAY_PART ADBVideoMetadataKeyFEED ADBVideoMetadataKeySTREAM_FORMAT ADBAdMetadataKeyADVERTISER ADBAdMetadataKeyCAMPAIGN_ID ADBAdMetadataKeyCREATIVE_ID Description Show Season Episode Asset Genre First air date First digital date Rating Originator Network Show type Ad load mvpd Authorization Day part Feed Stream format Advertiser Campaign Id Creative Id Type Video Video Video Video Video Video Video Video Video Video Video Video Video Video Video Video Video Ad Ad Ad

15 15 Constant name ADBAdMetadataKeyPLACEMENT_ID ADBAdMetadataKeySITE_ID ADBAdMetadataKeyCREATIVE_URL Description Placement Id Site Id Creative Url Type Ad Ad Ad Implementation for standard ad metadata Here is the Standard Metadata Constants reference: Constant name Description ADBMediaObjectKeyStandardVideoMetadata ADBMediaObjectKeyStandardAdMetadata Constant for attaching standard video metadata on MediaInfo ADBMediaObject Constant for attaching standard ad metadata on AdInfo ADBMediaObject 1. Create a dictionary of standard Ad metadata key value pairs using the ADBStandardMetadataKeys specified above. 2. Set the standard ad metadata dictionary on AdObject ADBMediaObject instance using the Standard Metadata constant for ad metadata. 3. Provide this AdObject while invoking trackevent API for ADBMediaHeartbeatEventAdStart Here is a sample implementation: // Sample implementation for using standard metadata keys for Ad NSMutableDictionary *standardadmetadata = [[NSMutableDictionary alloc] init]; [standardadmetadata setobject:@"sample Advertiser" forkey:adbadmetadatakeyadvertiser]; [standardadmetadata setobject:@"sample Campaign" forkey:adbadmetadatakeycampaign_id]; [adobject setvalue:standardadmetadata forkey:adbmediaobjectkeystandardadmetadata]; [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adobject Implementation for standard video metadata Here is the Standard Metadata Constants reference: Constant name ADBMediaObjectKeyStandardVideoMetadata ADBMediaObjectKeyStandardAdMetadata Description Constant for attaching standard video metadata on MediaInfo ADBMediaObject Constant for attaching standard ad metadata on AdInfo ADBMediaObject 1. Create a dictionary of standard Video metadata key value pairs using the ADBStandardMetadataKeys specified above. 2. Set the standard video metadata dictionary on MediaInfo ADBMediaObject instance using the Standard Metadata constant for video metadata. 3. Provide this MediaInfo object while invoking the tracksessionstart API.

16 16 Sample implementation: // Sample implementation for using standard video metadata keys NSMutableDictionary *standardvideometadata = [[NSMutableDictionary alloc] init]; [standardvideometadata setobject:@"sample Show" forkey:adbvideometadatakeyshow]; [standardvideometadata setobject:@"sample Season" forkey:adbvideometadatakeyseason]; [standardvideometadata setobject:@"sample Episode" forkey:adbvideometadatakeyepisode]; [mediaobject setvalue:standardvideometadata forkey:adbmediaobjectkeystandardvideometadata]; [_mediaheartbeat tracksessionstart:mediaobject Track buffering Here is the ADBMediaHeartbeatEvent buffer tracking constants reference: Constant name ADBMediaHeartbeatEventBufferStart ADBMediaHeartbeatEventBufferComplete Description Constant for tracking Buffer Start event Constant for tracking Buffer Complete event 1. Listen for the playback buffering events from media player. On buffer start event notification, track buffering using ADBMediaHeartbeatEventBufferStart event. - (void)onbufferstart:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventbufferstart mediaobject:nil 2. On buffer complete notification from media player, track the end of buffering using ADBMediaHeartbeatEventBufferComplete event. - (void)onbuffercomplete:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventbuffercomplete mediaobject:nil Seeking Here is the ADBMediaHeartbeatEvent seek tracking constants reference: Constant name ADBMediaHeartbeatEventBufferStart ADBMediaHeartbeatEventBufferComplete Description Constant for tracking Buffer Start event Constant for tracking Buffer Complete event

17 17 1. Listen for the playback seeking events from media player. On seek start event notification, track seeking using ADBMediaHeartbeatEventSeekStart event. - (void)onseekstart:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventseekstart mediaobject:nil 2. On seek complete notification from media player, track the end of seeking using ADBMediaHeartbeatEventSeekComplete event. - (void)onseekcomplete:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventseekcomplete mediaobject:nil QoS updates Here is the ADBMediaHeartbeatEvent QoS tracking constants reference: Constant name ADBMediaHeartbeatEventBitrateChange Description Constant for tracking Bitrate change 1. Listen for the QoS updates from media player. 2. On bitrate change event notification, create ADBMediaObject with QoS information. ADBMediaObject (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 id qosobject = [ADBMediaHeartbeat createqosobjectwithbitrate:[bitrate] startuptime:[startup_time] fps:[fps] droppedframes:[dropped_frames]]; 3. Track bitrate change using the ADBMediaHeartbeatEventBitrateChange event. - (void)onbitratechange:(nsnotification *)notification { [_mediaheartbeat trackevent:adbmediaheartbeateventbitratechange mediaobject:qosobject

18 18 Tracking errors Before you configure error tracking, see Implement the ios library. To track video player errors: - (void)onplayererror:(nsnotification *)notification { [_mediaheartbeat 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 Track core playback. 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 MediaHeartbeat (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 ADBMediaObjectKeyVideoResumed to. - (void)onmainvideoloaded:(nsnotification *)notification { //Replace <VIDEO_NAME> with the video name. //Replace <VIDEO_ID> with a video unique identifier. //Replace <VIDEO_LENGTH> with the video length. ADBMediaObject *mediaobject = [ADBMediaHeartbeat createmediaobjectwithname:<video_name> mediaid:<video_id> length:<video_length> streamtype:adbmediaheartbeatstreamtypevod]; //Set to YES if this user is resuming a previously closed video session [mediaobject setvalue:@(yes) forkey:adbmediaobjectkeyvideoresumed];

19 19 [_mediaheartbeat tracksessionstart:mediaobject data:videometadata]; Opt-out and privacy settings You can control whether or not Video Heartbeat activity is allowed on a specific device. MediaHeartbeat respects AdobeMobileLibrary s privacy and opt-out settings. To opt-out of Video Heartbeat tracking, ensure that you opt out on AdobeMobileLibrary. For more information on AdobeMobileLibrary s opt-out and privacy, see Opt-Out and Privacy Settings. AppleTV implementation guide with tvos You can use this information to implement MediaHeartbeat on Apple TV with tvos. With the release of the new Apple TV, you can now create applications to run in the native tvos environment. You can either create a purely native app, using any of several frameworks available in ios, or you can create your app using XML templates and JavaScript. Starting with MediaHeartbeatLibrary version 2.0, support for tvos is available. Configure a Native App for tvos The following steps are to be performed in your Xcode project. This guide is written assuming your project has a target that is an Apple TV app targeting tvos. For more information about tvos, see tvos Developer site. 1. Drag the VideoHeartbeat_TV.a library file into your project s lib folder. 2. In the Build Phases tab of your tvos app s target, expand the Link Binary with Libraries section and add the following libraries: VideoHeartbeat_TV.a AdobeMobileLibrary_TV.a libsqlite3.0.tbd SystemConfiguration.framework You should be able to use the SDK as you normally would for ios. For more information about how to use the ios SDK, see the ios documentation. 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

20 20 Sample player A sample player is included in the [ ]/samples directory of the SDK. Ratings Partners Integration Parter Nielsen Documentation Digital Content Ratings powered by Adobe Debugging 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 Sample code to enable debug logging: // Media Heartbeat Initialization ADBMediaHeartbeatConfig *config = [[ADBMediaHeartbeatConfig alloc] init]; config.debuglogging = YES; // Use this space for setting other config values ADBMediaHeartbeat *_mediaheartbeat = [[ADBMediaHeartbeat alloc] initwithdelegate:self config: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, and so on.) 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.

21 21 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 auto-start. [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 it will be required to use a HTTP Proxy tool to view the HTTP / HTTPS traffic between the Application and Heartbeats/Adobe Analytics. HTTP calls for video analytics tracking will be 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 (also known as 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. Adobe Debug Optionally, you can debug payloads (Heartbeat and Adobe Analytics) going out of Video Heartbeat Library using the Adobe Debug tool. This 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 for information. Scenarios Scenarios help you understand how Video Heartbeat works. For more information about setting up a scenario in ios, 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 This scenario comprises one VOD asset, with no ads, and is played once from beginning to end.

22 22 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. 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> 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"

23 23 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> eg.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 s:asset:type Value "complete" "main" Playback with no interruptions In this scenario, there is content that is 40 seconds long content and is played until the end without any interruptions. To view this scenario in ios, set up the following code: when the user clicks Play ADBMediaObject *mediaobject = [ADBMediaHeartbeat createmediaobjectwithname:video_name length:video_length streamtype:adbmediaheartbeatstreamtypevod]; NSMutableDictionary *videocontextdata = [[NSMutableDictionary alloc] init]; [videocontextdata setobject:custom_val_1 forkey:custom_key_1]; [videocontextdata setobject:custom_val_2 forkey: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:mediaobject data:videocontextdata];......

24 24 // 2. Call trackplay when the playback actually starts, i.e., when the // first frame of main content 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];.. 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 Playback with no interruptions scenario. The network calls happen at the same time, but the payload is different. Trigger The user clicks Play The ad starts. Heartbeat method tracksessionstart trackevent:adbreakstart trackevent:adstart Network calls The measurement library 1. Analytics Content Start does not know that there is 2. Heartbeat Content Start a pre-roll ad, so these network calls are still identical to the Playback with no interruptions scenario. 1. Analytics Ad Start 2. Heartbeat Ad Start The frame of ad #1 is played. trackplay Heartbeat Ad Play The ad content plays before main content, and the heartbeats start when the ad starts. The ad is played. Ad Heartbeats Ad #2 completes playing. trackevent:trackadcomplete Heartbeat Ad Complete The end of the ad is reached. The first frame of ad #2 is played. trackevent:adstart 1. Analytics Ad Start 2. Heartbeat Ad Start The ad plays. Ad Heartbeats Ad #2 completes playing. trackevent:trackadcomplete trackevent:adbreakcomplete Heartbeat Ad Complete The end of the ad and the pod is reached.

25 25 Trigger Heartbeat method Network calls 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. 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>

26 26 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" Playback with a pre-roll ad break In this scenario, the VOD content consists of a pre-roll ad, a second pre-roll ad, and then the content is played. To view this scenario in ios, set up the following code: // Set up mediaobject ADBMediaObject *mediaobject = [ADBMediaHeartbeat createmediaobjectwithname:video_name length:video_length streamtype:adbmediaheartbeatstreamtypevod]; NSMutableDictionary *videocontextdata = [[NSMutableDictionary alloc] init]; [videocontextdata setobject:custom_val_1 forkey:custom_key_1]; [videocontextdata setobject:custom_val_2 forkey:custom_key_2]; // 1. Call tracksessionstart when the user clicks Play or if autoplay is used, // i.e., there is an intent to start playback. [_mediaheartbeat tracksessionstart:mediaobject data:videocontextdata]; // Pre-roll ADBMediaObject *adbreakinfo = [ADBMediaHeartbeat createadbreakobjectwithname:ad_break_name position:ad_break_position starttime:ad_break_start_time]; ADBMediaObject *adinfo = [ADBMediaHeartbeat createadobjectwithname:ad_name adid:ad_id position:ad_position length:ad_length]; // context ad data NSMutableDictionary *addictionary = [[NSMutableDictionary alloc] init]; [addictionary setobject:@"custom-val1" forkey:@"custom-key1"]; [addictionary setobject:@"custom-val2" forkey:@"custom-key2"]; // 2. Track the ADBMediaHeartbeatEventAdBreakStart event when the pre-roll pod // starts to play. Note that since this is a pre-roll, you must track the // "ADBMediaHeartbeatEventAdBreakStart" event before you call trackplay.

27 27 [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakstart mediaobject:adbreakobject // 3. Track the ADBMediaHeartbeatEventAdStart event when the pre-roll pod's // ad starts to play. Note that since this is a pre-roll, you must track // the "ADBMediaHeartbeatEventAdStart" event before you call trackplay. [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adobject data:addictionary]; // 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 ADBMediaHeartbeatEventAdComplete event when the ad reaches // the end, i.e., when the video completes and finishes playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadcomplete mediaobject:nil // 6. Track the ADBMediaHeartbeatEventAdStart event when the pre-roll pod's // second ad starts to play. [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adbreakobject // 7. Track the ADBMediaHeartbeatEventAdComplete event when the second ad // reaches the end, i.e., it completes and finishes playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadcomplete mediaobject:nil // 8. Track the ADBMediaHeartbeatEventAdBreakComplete event when all the // ads in the pod finish playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakcomplete mediaobject:adbreakobject // 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 In this scenario, VOD content is played back with a pre-roll ad, the content, a mid-roll ad, the content, and a post-roll ad.

28 28 To view this scenario in ios, set up the following code: // Set up mediaobject ADBMediaObject *mediaobject = [ADBMediaHeartbeat createmediaobjectwithname:video_name length:video_length streamtype:adbmediaheartbeatstreamtypevod]; NSMutableDictionary *videocontextdata = [[NSMutableDictionary alloc] init]; [videocontextdata setobject:custom_val_1 forkey:custom_key_1]; [videocontextdata setobject:custom_val_2 forkey:custom_key_2]; // 1. Call tracksessionstart when the user clicks Play or if autoplay is used, // i.e., there is an intent to start playback. [_mediaheartbeat tracksessionstart:mediaobject data:videocontextdata]; // Pre-roll ADBMediaObject *adbreakinfo = [ADBMediaHeartbeat createadbreakobjectwithname:ad_break_name position:ad_break_position starttime:ad_break_start_time]; ADBMediaObject *adinfo = [ADBMediaHeartbeat createadobjectwithname:ad_name adid:ad_id position:ad_position length:ad_length]; // Context ad data NSMutableDictionary *addictionary = [[NSMutableDictionary alloc] init]; [addictionary setobject:@"custom-val1" forkey:@"custom-key1"]; [addictionary setobject:@"custom-val2" forkey:@"custom-key2"]; // 2. Track the ADBMediaHeartbeatEventAdBreakStart event when the // pre-roll pod starts to play. Note that since this is a pre-roll, // you must track the ADBMediaHeartbeatEventAdBreakStart event // before you call trackplay. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakstart mediaobject:adbreakobject data:addictionary]; // 3. Track the ADBMediaHeartbeatEventAdStart when the pre-roll // pod's ad starts to play. Note that since this is a pre-roll, // you must track the ADBMediaHeartbeatEventAdStart before you // call trackplay. [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adobject data:addictionary];

29 29 // 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 ADBMediaHeartbeatEventAdComplete event when the ad // reaches the end, i.e., when it completes and finishes playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadcomplete mediaobject:nil // 6. Track the ADBMediaHeartbeatEventAdBreakComplete event when all // of the ads in the pod finish playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakcomplete mediaobject:nil // Mid-roll ADBMediaObject *adbreakinfo = [ADBMediaHeartbeat createadbreakobjectwithname:midroll_break_name position:midroll_break_position starttime:midroll_break_start_time]; ADBMediaObject *adinfo = [ADBMediaHeartbeat createadobjectwithname:midroll_ad_name adid:midroll_ad_id position:midroll_ad_position length:midroll_ad_length]; // context ad data NSMutableDictionary *midrolladdictionary = [[NSMutableDictionary alloc] init]; [midrolladdictionary setobject:@"custom-val1" forkey:@"custom-key1"]; [midrolladdictionary setobject:@"custom-val2" forkey:@"custom-key2"]; // 7. Track the ADBMediaHeartbeatEventAdBreakStart event when the mid-roll pod // starts to play. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakstart mediaobject:adbreakobject // 8. Track the ADBMediaHeartbeatEventAdStart event when the mid-roll pod's // ad starts to play. [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adobject data:midrolladdictionary]; // 9. Track the ADBMediaHeartbeatEventAdComplete event when the ad reaches // the end, i.e., when it completes and finishes playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadcomplete mediaobject:nil // 10. Track the ADBMediaHeartbeatEventAdBreakComplete event when all the // ads in the mid-roll pod finish playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakcomplete mediaobject:nil

30 30 // Post-roll ADBMediaObject *postrollbreakinfo = [ADBMediaHeartbeat createadbreakobjectwithname:postroll_break_name position:postroll_break_position starttime:postroll_break_start_time]; ADBMediaObject *adinfo = [ADBMediaHeartbeat createadobjectwithname:postroll_ad_name adid:postroll_ad_id position:postroll_ad_position length:postroll_ad_length]; // Context ad data NSMutableDictionary *postrolladdictionary = [[NSMutableDictionary alloc] init]; [postrolladdictionary setobject:@"custom-val1" forkey:@"custom-key1"]; [postrolladdictionary setobject:@"custom-val2" forkey:@"custom-key2"]; // 11. Track the ADBMediaHeartbeatEventAdBreakStart event when the // post-roll pod starts to play. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakstart mediaobject:adbreakobject // 12. Track the ADBMediaHeartbeatEventAdStart event when the // post-roll pod's ad starts to play. [_mediaheartbeat trackevent:adbmediaheartbeateventadstart mediaobject:adobject data:postrolladdictionary]; // 13. Track the ADBMediaHeartbeatEventAdComplete event when the // post-roll pod's ad finishes playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadcomplete mediaobject:nil // 14. Track the ADBMediaHeartbeatEventAdBreakComplete event when // all the ads in the post-roll pod finish playing. [_mediaheartbeat trackevent:adbmediaheartbeateventadbreakcomplete mediaobject:nil // 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 This scenario comprises VOD content playback with a skipped ad.

31 31 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() trackevent:adbreakstart() trackevent:adstart Network calls The measurement 1. Analytics Content Start library is unaware that 2. Heartbeat Content Start there is a pre-roll ad. These network calls are still exactly the same as Playback with no interruptions scenario. 1. Analytics Ad Start 2. Heartbeat Ad Start The first frame of the ad is played. trackplay() Heartbeat Ad Play When ad content plays before main content, the 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.