Adobe Marketing Cloud Video Heartbeat

Transcription

1 Adobe Marketing Cloud Video Heartbeat

2 Contents Measuring Video in Adobe Analytics using Video Heartbeat...4 Measuring Video FAQ...5 Before you Implement...8 Getting Started...9 Configure Analytics Video Reporting...10 Enable Video Pathing...11 Video Reports...13 Video Overview Report...13 Video Detail Report...15 Video Daypart...16 Video Metrics and Dimensions...18 Video Heartbeat Developer Guide...20 JavaScript Players...20 Download the Video Heartbeat Library...21 Implement PlayerDelegate...21 Configure Video Heartbeat...24 Track Player Events...25 Test Your Video Measurement Code...26 ActionScript Players...27 Download the Video Heartbeat Library...28 Add the AppMeasurement for Flash Library to a Project...28 Configure AppMeasurement...30 Implement PlayerDelegate...31 Last updated 2/9/2015 Video Heartbeat

3 Contents Configure Video Heartbeat...33 Track Player Events...34 Test Your Video Measurement Code...35 Sending extra video data on start...36 Sending extra video data during playback...39 Video Measurement Timeline...42 Video Measurement Parameters...44 How PlayerDelegate Works...46 Track Methods and Player Events...48 Migrating to Video Heartbeat...50 Contact and Legal Information...52 Last updated 2/9/2015 Video Heartbeat

4 Measuring Video in Adobe Analytics using Video Heartbeat 4 Measuring Video in Adobe Analytics using Video Heartbeat Important: Before implementing the new video heartbeat solution described in this document, you must reach out to your account manager and/or sales rep to get new stream pricing (migrating from server call model to stream-based model). Adobe Analytics provides support for tracking video and ad metrics, including total views/impressions, time spent, and completion rates. Native support is provided for measuring the most popular video formats on the web, including Flash, with other web and mobile libraries coming soon. This guide describes measuring video using the heartbeat service. What is "Video Heartbeat"? Video heartbeat is a new data collection service provided by Adobe that collects and aggregates video metrics. During video playback, frequent "heartbeat" calls are sent to this service to measure time played. These heartbeat calls are sent every 10 seconds, which results in granular video engagement metrics and more accurate video fallout reports. When a video or video ad is played, a single server call is sent to your Analytics data collection server with the video/ad name, player name, channel, and any additional custom variables that you want to track for that video/ad. During playback, "heartbeats" are sent at regular intervals to the heartbeat data collection service to track time played. After the video/ad is completed and/or abandoned, the heartbeat service calculates time spent metrics and then sends the data to Analytics. Heartbeat or Milestone? In addition to our new video heartbeat measurement, Adobe will continue to support the milestone video solution (released August 2011), which is also referred to as "integrated" or "SiteCatalyst 15" video measurement. If you are new to video measurement, you should implement the heartbeat measurement solution described in this guide. Heartbeat provides more accurate time spent metrics with a simplified implementation process and streamlined pricing.

5 Measuring Video FAQ 5 Measuring Video FAQ This topic provides answers to common questions. What platforms does the new heartbeat solution support? Currently, heartbeat measurement supports JavaScript, Flash, ios and Android. See Before you Implement for details. Can I use both milestone and heartbeat models at same time?. Within the same company and report suite, you can have players running both the milestone (legacy) video tracking and our new heartbeat tracking. Depending on how you configure, the video canned reports within Adobe Analytics may only show the new heartbeat data but any custom variable reports will contain video metrics from both solutions. Can I, as the customer, change the frequency of heartbeats? No, the default heartbeat frequency is 10 seconds for both content in ads. In a future release, we do expect to lower heartbeat frequency for ads down to 5 seconds. How do I send in additional metadata into Adobe Analytics during the video playback? With the new video heartbeat tracking, the old way of sending in additional metadata via the Media-monitor is gone. Video metadata and any other additional data will now go directly onto the AppMeas object. We metadata should be sent on the initial call into Adobe Analytics and be managed via auto-classifications What video reports will I see within Adobe Analytics if I still have the milestone implementation? There are 3 new video canned reports: Video Overview, Video Detail, and Video Daypart. Both milestone and heartbeat implementations will see these same new reports, provided they are configured and enabled within the Admin console. Why do I have to negotiate new stream pricing before implementing the heartbeat solution? The new heartbeat tracking solution comes with a new stream-based pricing model. Server calls will no longer be used to calculate the cost of tracking a video stream. Before implementing the new heartbeat solution, customers must reach out to their account manager and/or sales reps to update their contract and include new stream-based pricing. Benefit to the customer is that new pricing should stabilize cost of video tracking and it should be easier to forecast and budget overall video analytics spend. What is a heartbeat and what data is included in that heartbeat? A heartbeat is a "ping" to our servers letting us know the viewer is still watching the video. Heartbeats are also sent during certain events centered around quality of service like a video error and/or buffer (data will be available in Adobe Analytics in 2014). The actual heartbeat includes: QoS data (related to Primetime), user metadata, asset metadata, event timestamps, SiteCatalyst metadata. How big are the heartbeats and will it impact performance? Ave. heartbeat is 1Kb. What is a Publisher ID and how do I get one? The Publisher ID is used to configure the XML document for a customer's specific implementation. Without the ID, the player will through 404 errors in debug mode, however the video will still be tracked and heartbeats sent. To get a Publisher ID, call ClientCare and one will be provided. Can I use players provided by other vendors like Brightcove, theplatform, etc?, Adobe is player agnostic and it doesn't matter what player is used. However, in order for data to be collected, aggregated, and reported upon each individual player needs to make those events available. Adobe is working with several of the largest player provider vendors to make sure their players are compatible with our new heartbeat solution.

6 Measuring Video FAQ 6 What is a solution variable? A solution variable, sometimes called a "reserved" variable, is a variable that Adobe has allocated specifically to track and measure certain events and/or attributes. With a solution variable, a customer won't need to utilize one of their existing custom variables. Solution variables allocated for video include: Video Core: Video Name, Content Type, Player Name, Channel, Video Starts, Video Completes, and Video Time Spent. Video Ads : Ad Name, Ad Player Name, Pod Name, Ad Position in Pod, Ad Starts, Ad Completes, and Ad Time Spent If I've already configured certain custom variables for video tracking, can I continue to use them?. For video content, we allow customer to use their current custom variables for video name, content type, video start, video time spent, and video complete. By mapping your existing variables, you will not see a break in data from our canned video reports. However, for video ad tracking we will use solution variables by default for all customers. Why does Adobe want to track my video ads? With the new video reports, content data and ad data is integrated to provide insights into how programmers/publishers can optimize their ad loads and thus their monetization opportunities with the least amount of impact to viewer engagement. What happens to my server call commitments if I move to video stream pricing? Your account manager/sales rep will work with you on providing a new stream price while at the same time understanding how migration will lower overall server call usage and update commitments accordingly. Will I need consulting to help with new video heartbeat implementation? Adobe generally recommends a consulting engagement with any new video implementation. Here are some general guidelines around hours but may vary greatly per customer depending on customization and requirements: Video Consulting Hours Single Platform Multi-Platform Known and Documented Unknown/Non-Documented All projects include: Creation of player mapping Code integration with client sites/apps Set-up of reporting Basic analysis Does Adobe offer real-time reporting for video? With the recent release of Adobe Analytics 1.4, customer can track events in real-time. So customer could configure those reports to track video starts to measure trending to optimize video views. Additionally, Adobe expects to offer a new real-time report that will measure concurrent viewers or how many viewers are watching "right now". This report is targeted for 1H Can I still use Media.monitor() with new heartbeat tracking? No, Media.monitor() will no longer be available for heartbeat tracking. To track custom metadata, customer will have to pass metadata directly within AppMeasurement object with the start call going into Adobe Analytics

7 Measuring Video FAQ 7 Will video data be available in Data Warehouse, ReportBuilder, Discover, and Insight?, all video data will be available in these products provided customer has existing access to them.

8 Before you Implement 8 Before you Implement Video heartbeat provides a cost effective video measurement solution with highly granular time metrics. Before you implement, be aware of the following limitations. AppMeasurement for JavaScript 1.x is required for JavaScript implementations. If you are on s_code you need to migrate. The Visitor ID service is required by video heartbeat. To avoid duplicate visitor counts when using the JavaScript media module, the visitor ID service must also be implemented on non-video pages on your site, or you must enable a grace period. Video heartbeat does not support SSL. For ios and Android, this means that you offline must be disabled, and your report suite cannot be timestamp enabled. If you are unsure if your report suite is timestamp enabled, contact Customer Care. Custom timestamps are not supported. Additional variables sent on video start do not receive attribution for video completes or time spent metrics (you should use instances or video starts instead). See Sending extra video data on start and Sending extra video data during playback. Custom video completes are not supported, so you cannot define a custom location to determine when a video view is considered complete.

9 Getting Started 9 Getting Started This section provides an overview of the tasks required to implement video heartbeat. Step Task Discuss video heartbeat pricing with your Adobe Marketing Cloud sales representative. Details Hearbeat video introduces a new video pricing model that is based on video streams instead of server calls. Speak with your sales representative for more details. Important: Do not implement video heartbeat until you have spoken with your sales rep and have new stream-based pricing. Contact Adobe to configure your heartbeat publisher ID. Configure video reports in Analytics. Implement or migrate to video heartbeat. View video reports. Each customer is provided an ID that is associated with a configuration file on the heartbeat server. This file is configured by an Adobe representative. Contact Customer Care and tell them you need to configure "heartbeat video publisher ID" Before you implement, you need to perform a few steps to prepare your Analytics report suite to capture video data. Configure Analytics Video Reporting Enable Video Pathing See Video Heartbeat Developer Guide. After implementation, video metrics are available in dedicated video reports in the marketing reports & analytics (formerly SiteCatalyst) interface. Video Reports

10 Configure Analytics Video Reporting 10 Configure Analytics Video Reporting Each report suite that collects video metrics must be configured before video data is sent. This section walks you through the process to enable the variables that collect video data. When you finish this section, continue to Enable Video Pathing. In marketing reports & analytics, open Admin Tools > Report Suites. Select the report suite(s) where you are collecting video data, then click Edit Settings > Video Management > Video Reporting. On the Video Reporting page, enable Video Core, and optionally enable Video Ads and Video Chapters, and then click Save. If you aren't yet tracking ads or chapters, you can come back and enable additional options at any time. If this report suite is already configured to collect video data, then you are presented an additional configuration page after you click Save. If you see the Video Core Measurement page, continue to the next section. Video Core Measurement - Additional Migration Steps On this page, you must select to use solution variables or continue using custom variables. Option Continue using custom variables Description Pros: Video trending continues to work after migration. Cons: Requires you to keep 2 custom evars and 3 custom events allocated to video. You regain use of 1 custom evar and 1 custom event. To continue using custom variables: Select Use Custom Variables and then click Save: When prompted, map you current custom evars and events and then click Save:

11 Configure Analytics Video Reporting 11 Option Description Migrate to solution variables Pros: You regain use of 3 custom evars and 4 custom events. Cons: You lose ALL historical trending and comparison for video reports. This means Note: Migrating to solution variable causes you to lose ALL that you won't be able to trend video views or video time played for any dates before historical trending and you migrated to video heartbeat. Do not migrate to solution variables unless you are comparison for video reports. certain that you do not want to preserve this trending! To migrate to solution variables: Select Use Solution Variables and then click Save. Enable Video Pathing To enable video pathing, set up a processing rule to copy the a.media.name context data variable to a custom prop. Configure the rule to check for the presence of a a.media.view context data (indicating the start of a video) and the a.media.name context data:

12 Configure Analytics Video Reporting 12

13 Video Reports 13 Video Reports Adobe Analytics provides several reports and metrics to track video performance on your Web site. Video reports are listed in the Reports > Video section. Why are the Video Engagement Reports marked as "Beta"? We are working to improve the functionality and layout of these reports, so expect to see some minor changes to these reports in future releases. The data that appears on these reports is accurate and is not impacted by the beta status. Video Engagement Reports (Beta) Video Report Description Common Business Insights Video Overview Report The Video Overview Report displays several aggregate measurements to quickly monitor that video is performing as expected. A graph displays video starts next to ad impressions to let you quickly view these metrics for each video. Totals for top video metrics including unique viewers, completion rate, average video metrics, and average videos per visit. Total video and ad views for specific videos filtered by device type or country. Video Detail Report Displays detailed metrics for all videos including starts, completion rate, play percentage, and ad impressions. Totals for top video metrics including video starts, ad impressions, average ads per video. Top videos by multiple metrics Video Daypart Displays unique visitors and video views by time of day to let you quickly view when your audience is engaged. Audience engagement by time of day. Audience engagement compared to previous date ranges. Video Events and Video Variables Reports for additional Video Metrics and Dimensions are also available. Video metrics and dimensions are standard Analytics variables that can be reported directly and added to other Analytics reports. Video Conversion (Events that occur after video is viewed) by generating a report with visits that include a content type of video. Next/previous video flow using the video name prop. Video Overview Report The video overview report is designed to let you monitor video across your site. The Video Overview Report displays several aggregate measurements to quickly monitor that video is performing as expected. A graph displays video starts next to ad impressions to let you quickly view these metrics for each video.

14 Video Reports 14 Quick Filters Quickly display video metrics by device or geo country:

15 Video Reports 15 Video Performance Click-and-drag to zoom in, then hover to view granular metrics for specific videos. Click zoom. to reset the view after you Video Detail Report The Video Detail Report displays detailed metrics for all videos including starts, completion rate, play percentage, and ad impressions.

16 Video Reports 16 Video Daypart Displays unique visitors and video views by time of day to let you quickly view when your audience is engaged.

17 Video Reports 17

18 Video Metrics and Dimensions 18 Video Metrics and Dimensions Video metrics and dimensions are standard Analytics variables that can be reported directly and added to other Analytics reports. Video metric and dimension reports appear in the Video > Video Events and Video > Video Variables reports. Video Metrics Video Metric Description Video/Ad Time Viewed Counts the time, in seconds, spent watching a video or ad. Video/Ad Views Indicates that a visitor has viewed some portion of a video or ad. However, it does not provide any information about how much, or what part, of a video the visitor viewed. Video/Ad Completes Indicates that a user has viewed a complete video or ad. Video Segment View Sent on all close events, which occur on video complete or when the users stops viewing at some point before the complete occurs. Video Dimensions Video/Ad Name and Video/Ad Length expire on visit. All other variables expire with the initial Analytics video call (page view). Video Dimension Video/Ad Name Video/Ad Length Segment Content Type Description Name of the video, as passed to Media.open(). Video Name and Ad Name are automatic classifications based on the data sent on the initial Media.play() call, so you'll see an extra menu level when you view these reports. Length of the video, as passed to Media.open(). Video Length and Ad Length are automatic classifications based on the data sent on the initial Media.play() call, so you'll see an extra menu level when you view these reports. Name of the segment, as passed to Media.play(). Content type is set to "video" automatically for all video views, and to "ad" for all ad views. This report is useful to segment and compare video to other content delivered on your site.

19 Video Metrics and Dimensions 19 Video Dimension Player Name Channel Pod Name Pod Position Ad in Pod Position Ad Player Name Description Name of the video player, as passed to Media.open(). The Channel where the content is played. (web site/application) Ad pod name, as passed to Media.openAd(). The offset from the start of the video in seconds where the ad pod is located, The position of an and within a pod (first ad, second ad), as passed to Media.open(). Name of ad player, as passed to Media.openAd()

20 Video Heartbeat Developer Guide 20 Video Heartbeat Developer Guide This section contains instructions to download the video heartbeat SDKs and developer guides for each platform. Make sure you also download the developer guide that is in the docs folder when you download the SDK as it contains the specific implementation instructions for video heartbeat. Platform JavaScript Flash/ActionScript ios Process See JavaScript Players. See ActionScript Players. Video heartbeat for ios requires that you first implement the Marketing Cloud SDK in your app. For details, see ios SDK 4.x for Marketing Cloud Solutions. After your Analytics implementation is configured using the Marketing Cloud SDK, visit the Adobe Github Video Heartbeat site to download the SDK and the developer guide. Android Video heartbeat for Android requires that you first implement the Marketing Cloud SDK in your app. For details, see Android SDK 4.x for Marketing Cloud Solutions. After your Analytics implementation is configured using the Marketing Cloud SDK, visit the Adobe Github Video Heartbeat site to download the SDK and the developer guide. JavaScript Players This guide describes how to add video heartbeat measurement to any video player that provides a JavaScript API. Most web-based players provide a JavaScript API, even if the underlying video is delivered in Flash or other video formats. For example, the following players can be tracked using JavaScript: YouTube Brightcove Kaltura Ooyala HTML 5 (using native JavaScript support in the web browser and the HTML 5 video events). For other players, implementing video heartbeat requires that your video player provides a JavaScript API with the following: An API to subscribe to player events. The video heartbeat SDK requires that you call a set of simple functions as actions occur in your player. An API or class that provides player information, such as video name and playhead location. The video heartbeat SDK requires that you implement an interface that returns current video information. Requirements Integrating video heartbeat requires the following: Existing Analytics implementation. These instructions assume that you have an existing implementation of AppMeasurement that is also using the Marketing Cloud Visitor ID Service. If you have not yet implemented Analytics or the Marketing Cloud Visitor ID Service, use the Adobe Analytics Implementation Guide and the Marketing Cloud Visitor ID Service Guide to get started. VideoHeartbeat library. (download instructions are in this guide)

21 Video Heartbeat Developer Guide 21 AdobeAnalyticsPlugin (download instructions are in this guide) Note: Make sure your Analytics implementation is configured to send data to a development report suite before you start development. Example Implementations A simple HTML 5 video heartbeat implementation is provided for reference at Analytics Video Heartbeat Demo. A more robust example is available in the samples folder that is included with the Video Heartbeat library (download instructions are in this guide). Implementation Process Complete the following steps to add video heartbeat tracking to your player: Download the Video Heartbeat Library Video heartbeat is distributed using a public Github repository. 1. Browse to Adobe Github Video Heartbeat and download the latest release for your platform. 2. Extract the zip, and copy VideoHeartbeat.min.js to a location accessible to your project. Optionally, copy the non-minified version to your project for debugging. 3. Also copy AdobeAnalyticsPlugin.min.js to a location accessible to your project. Optionally, copy the non-minified version to your project for debugging. 4. Save the samples folder to a location where the sample project can be reviewed and tested. Next step: Implement PlayerDelegate Implement PlayerDelegate The PlayerDelegate is used by video heartbeat to get information about the currently playing video, ad, and chapter. First, read How PlayerDelegate Works to understand the role of PlayerDelegate in video heartbeat. Implementing this interface is where you will typically spend a majority of your implementation time. Additional information on this interface is available in the Video Heartbeat SDK guide distributed with the download. To get started creating your own PlayerDelegate implementation, create a new object that uses ADB.va.PlayerDelegate as the object prototype: var mydelegate = new ADB.va.PlayerDelegate(); Now that you have a player delegate, you need to define the functions that return information about your video and player: getvideoinfo() - returns an ADB.va.Video object. (required) getadbreakinfo() - returns an ADB.va.AdBreakInfo object. getadinfo() - returns an ADB.va.AdInfo object. getchapterinfo() - returns an ADB.va.ChapterInfo object. Using the following code as a template, add any of these functions you'd like to use to your code: mydelegate.getvideoinfo = function() { // use the ADB.va.VideoInfo object prototype var videoinfo = new ADB.va.VideoInfo(); videoinfo.id = ""; videoinfo.playername = ""; videoinfo.length = -1; videoinfo.streamtype = ADB.va.ASSET_TYPE_LINEAR; videoinfo.playhead = -1;

22 Video Heartbeat Developer Guide 22 return videoinfo; mydelegate.getadbreakinfo = function() { // use the ADB.va.AdBreakInfo object prototype var AdBreakInfo = new ADB.va.AdBreakInfo(); adbreakinfo.playername = ""; adbreakinfo.name = ""; AdInfo.position = 1; adbreakinfo.starttime = -1; return AdBreakInfo; mydelegate.getadinfo = function() { // use the ADB.va.AdInfo object prototype var AdInfo = new ADB.va.AdInfo(); AdInfo.id = ""; AdInfo.name = ""; AdInfo.length = -1; AdInfo.position = "1"; AdInfo.cpm = ""; return AdInfo; mydelegate.getchapterinfo = function() { // use the ADB.va.ChapterInfo object prototype var ChapterInfo = new ADB.va.ChapterInfo(); ChapterInfo.name = ""; ChapterInfo.length = -1; ChapterInfo.position = "1"; ChapterInfo.startTime = -1; return ChapterInfo; // you can implement this if you want, but it isn't used in Analytics reports mydelegate.onerror = function() { return null; // you can implement this if you want, but it isn't used in Analytics reports mydelegate.getqosinfo = function() { return null; Now that you have the framework in place, complete the rest of the sections in this doc to update these methods to return useful data from your player. Working example at Analytics Video Heartbeat Demo. Video Information The getvideoinfo method returns a VideoInfo object that contains details about the video player and the currently playing video. Before you can define this object, you'll need to use the API documentation provided by your player to find out how video information is retrieved. Video information is usually a property of the player object, or retrieved using a private method. For example, In HTML 5, the playhead is a property of the <video> element: document.getelementbyid('movie').currenttime; In the YouTube API, the playhead is returned by a method call exposed by the player: player.getcurrenttime(); To implement your custom getvideoinfo method, you'll need the following information:

23 Video Heartbeat Developer Guide 23 Parameter playername id name length playhead streamtype Required? No Description The name of the video player that is playing back the main content The ID of the video asset The name of the video asset (opaque string value) The duration (in seconds) of the video asset. If streamtype is set to vod, return the length of the video. For other video types, return -1 as the length. The current playhead location (in seconds) inside the video asset (excluding ad content) at the moment this method was called. The type of the video asset, one of the following: ADB.va.ASSET_TYPE_LIVE, ADB.va.ASSET_TYPE_LINEAR, ADB.va.ASSET_TYPE_VOD After you have figured out how to get the required information, update the getvideoinfo method to return a VideoInfo object with the video information. How you populate each value is up to you, and varies based on your player. For example, you might load the video player name using a configuration file, or you could hard-code the value if you use only one player. Ad Break Information Ad breaks provide insight as to when a particular ad was displayed. For example, if you have a pre-roll and a midpoint ad break, you can collect position data along with the specific ad data. If you have only one ad break, you can simply provide 1 for the position and leave the name blank. Parameter playername name position starttime Required? No No Description The name of the video player responsible with playing back the current advertisement break. The name of the ad-break. The position (index) of the pod inside the main content (starting with 1). The offset of the ad-break inside the main content (in seconds). Defaults to the playhead inside the main content at the moment of the trackadstart call. Ad Information Ad information is retrieved using a similar process used to retrieve video information, except you return an AdInfo object instead with details about the currently playing video ad. Use the API documentation provided by your Ad vendor to determine the following: Parameter id length position name cpm Required? No No Description The ID of the ad asset The duration (in seconds) of the ad asset The position of the pod inside the main content (starting with 1) The name of the ad asset (opaque string value) The CPM value associated with this ad After you have figured out how to get the required information, update the getadinfo method to return an AdInfo object with the ad information.

24 Video Heartbeat Developer Guide 24 Chapter Information If you are tracking chapters, you'll need to coordinate the chapter information returned with each call you make to trackchapterstart. Since chapters are likely defined by you and not your video player, you'll need a way to retrieve chapter definitions to populate this object. Parameter name length position starttime Required? No Description The name of the chapter (opaque string value) The duration (in seconds) of the chapter The position of the chapter inside the main content (starting from 1) The offset inside the main content where the chapter starts Update the getchapterinfo method to retrieve properties or call the required APIs: mydelegate.getchapterinfo = function() { // use the ADB.va.ChapterInfo object prototype var ChapterInfo = new ADB.va.ChapterInfo(); ChapterInfo.name = "name"; ChapterInfo.length = "length"; ChapterInfo.position = "position"; ChapterInfo.startTime = "offset"; return ChapterInfo; Next step: Configure Video Heartbeat Configure Video Heartbeat After you Implement PlayerDelegate, you are ready to add the video heartbeat code to your project. Before you proceed, make sure you have the following: A configured AppMeasurement object that uses the Marketing Cloud Visitor ID Service. An instance of your custom PlayerDelegate object. Your publisher ID (assigned by Adobe). On each HTML page where you are tracking video, add a <script> tag with a reference to AdobeAnalyticsPlugin.js and VideoHeartbeat.min.js, before the script tag where you include AppMeasurement.js: <script src="videoheartbeat.min.js"></script> <script src="adobeanalyticsplugin.min.js"></script> Inside of your AppMeasurement.js file, insert the following video configuration code along with your custom PlayerDelegate implementation: // Add your custom PlayerDelegate implementation here var mydelegate = new ADB.va.PlayerDelegate(); mydelegate.getvideoinfo = function() { //... ; //... // end custom PlayerDelegate // Instantiate AdobeAnalytics plugin. var aaplugin = new ADB.va.plugins.AdobeAnalyticsPlugin(s); // Pass your AppMeasurement object as the only parameter // Register the AdobeAnalytics plugin with the video heartbeat library. var plugins = [aaplugin]; // this step requires the custom playerdelegate object you created in the previous section

25 Video Heartbeat Developer Guide 25 var videoheartbeat = new ADB.va.VideoHeartbeat(myDelegate, plugins); var heartbeatconfig = new ADB.va.ConfigData(); heartbeatconfig.trackingserver = " // same for all Analytics customers heartbeatconfig.jobid = "sc_va"; // Same for all Analytics customers heartbeatconfig.publisher = "MY_PUBLISHER_ID"; // Set to your Adobe assigned publisher ID heartbeatconfig.debuglogging = false; // remove or set to false for production! VideoHeartbeat.configure(heartbeatConfig); Working example at Analytics Video Heartbeat Demo. Test Your Configuration Before you continue, load your code in a browser to make sure everything loads without errors. Optionally, set the debuglogging flag to true while you test: heartbeatconfig.debuglogging = true; // remove or set to false for production! Next, open your code in a browser and check the JavaScript console for errors (the code must be running on a local or remote web server). If there are no errors, you can use the JavaScript console to make a call to VideoHeartbeat.trackVideoLoad() and then VideoHeartbeat.trackPlay() to simulate a video play. If you check the network tab, you'll see a call to your Analytics data collection server, and additional calls to heartbeats.omtrdc.net. After you have tested your configuration, continue to Track Player Events. Next step: Track Player Events Track Player Events Media players that provide JavaScript event handlers are typically tracked by attaching callback functions to the video player event handlers. The next step is to call the video heartbeat track methods when specific events occur in your player. This typically involves subscribing to events, registering a callback function, and then calling the correct method in the callback. Review the Track Methods and Player Events sections for details on exactly which method you should call for each corresponding player event. The following example demonstrates event handling for HTML 5 video: var myvideo = document.getelementbyid('movie'); myvideo.addeventlistener('play',trackplay,false); myvideo.addeventlistener('ended',trackcomplete,false); myvideo.addeventlistener('seeked', seekend, false); myvideo.addeventlistener('seeking', seekstart, false); myvideo.addeventlistener('pause', pause, false); myvideo.addeventlistener('ended', complete, false); function trackplay() { var myvideo = document.getelementbyid('movie'); if (myvideo.currenttime == 0) { VideoHeartbeat.trackVideoLoad(); VideoHeartbeat.trackPlay(); else { VideoHeartbeat.trackPlay(); function pause(e) { videoheartbeat.trackstop(); function seekstart(e) { videoheartbeat.trackseekstart(); function seekend(e) { videoheartbeat.trackseekcomplete();

26 Video Heartbeat Developer Guide 26 function trackcomplete() { VideoHeartbeat.trackComplete(); VideoHeartbeat.trackVideoUnload(); The following example demonstrates event handling for a YouTube player: function onyoutubeplayerready(id){ player = document.getelementbyid("ytplayer"); if (player.addeventlistener) { player.addeventlistener('onstatechange', 'handleplayerstatechange'); else { player.attachevent('onstatechange', 'handleplayerstatechange'); function handleplayerstatechange (state) { switch (state) { case 1: case 3: // Video has begun playing/buffering if (player.getcurrenttime() == 0) { VideoHeartbeat.trackVideoLoad(); VideoHeartbeat.trackPlay(); else { VideoHeartbeat.trackPlay(); break; case 2: VideoHeartbeat.trackPause(); case 0: // Video has been paused/ended VideoHeartbeat.trackComplete(); VideoHeartbeat.trackVideoUnload(); break; Note that each player provides a different way to listen to events. Use the documentation provided by the player API to determine how to listen for player events. Next step: Test Your Video Measurement Code Test Your Video Measurement Code A simple way to test your video heartbeat implementation is to run the code in a demo environment. 1. Load your code in a test environment and use a packet analyzer to verify that Analytics server calls and heartbeat calls are being sent. You should see an initial call to your data collection server, and then multiple calls to In the initial call to your data collection server: Verify that pe=ms_s. 2. Test your implementation throughly to make sure you haven't missed any events. For example, if your player provides a pause event handler and you do not call trackpause, your time played metrics will be inflated. 3. In a packet analyzer, inspect the calls and use the Video Measurement Timeline to make sure events are being sent as expected. For example, you should see an s:event:type of load and then start when the video begins, and complete and then unload events when the video completes.

27 Video Heartbeat Developer Guide 27 ActionScript Players This guide describes how to add video heartbeat measurement to any video player that provides an ActionScript API. This includes Flash video players, and other players based on Open Source Media Framework (OSMF). Implementing video heartbeat requires that your video player provides an ActionScript API with the following: An API to subscribe to player events. The video heartbeat SDK requires that you call a set of simple functions as actions occur in your player. An API or class that provides player information, such as video name and playhead location. The video heartbeat SDK requires that you implement an interface that returns current video information. Requirements Integrating video heartbeat requires the following: Existing Analytics implementation. These instructions assume that you have an existing implementation of AppMeasurement that is also using the Marketing Cloud Visitor ID Service. If you have not yet implemented Analytics or the Marketing Cloud Visitor ID Service, use the Adobe Analytics Implementation Guide and the Marketing Cloud Visitor ID Service Guide to get started. VideoHeartbeat library. (download instructions are in this guide) AdobeAnalyticsPlugin. (download instructions are in this guide) Note: Make sure your Analytics implementation is configured to send data to a development report suite before you start development.

28 Video Heartbeat Developer Guide 28 Example Implementations A simple Flash video heartbeat implementation is provided for reference at Analytics Video Heartbeat Demo. A more robust example is available in the samples folder that is included with the Video Heartbeat library (download instructions are in this guide). Implementation Process Complete the following steps to add video heartbeat tracking to your player: Download the Video Heartbeat Library Video heartbeat is distributed using a public Github repository. 1. Browse to Adobe Github Video Heartbeat and download the latest release for your platform. 2. Extract the zip, and copy VideoHeartbeat.swc and AdobeAnalyticsPlugin.swc to a location accessible to your project. 3. Save the samples folder to a location where the sample project can be reviewed and tested. Next step: Add the AppMeasurement for Flash Library to a Project Add the AppMeasurement for Flash Library to a Project The Flash media module provides the interface to track video. 1. Launch Flash Professional and open the Flash project where you want to include a Flash video. 2. Click File > Publish Settings, and then open ActionScript Settings. 3. Add the AppMeasurement.swc, AdobeAnalyticsPlugin.swc, VisitorAPI.swc, and VideoHeartbeat.swc libraries to your project.

29 Video Heartbeat Developer Guide In the Timeline pane, select a frame that is available to the entire Flash application and open Actions. 5. Add the following ActionScript code to import the libraries: import com.adobe.mc.visitor; import com.omniture.appmeasurement; import com.adobe.primetime.va.configdata; import com.adobe.primetime.va.videoheartbeat; import com.adobe.primetime.va.core.plugin.iplugin; import com.adobe.primetime.va.plugins.aa.adobeanalyticsplugin; As you use these libraries in your project, auto complete should appear. This indicates that the library is being found successfully.

30 Video Heartbeat Developer Guide 30 If you don't see auto complete, verify that the libraries are added to your project. Next step: Configure AppMeasurement. Configure AppMeasurement Flash video measurement uses ActionScript, and is configured similar to the JavaScript implementation on your website. The standard Analytics Variables are all available in Flash. Video Heartbeat requires that you implement the Marketing Cloud visitor ID service. 1. Instantiate and configure the Marketing Cloud visitor ID service: //Configure Visitor ID Service var visitor:visitor = new Visitor("INSERT-MCORG-ID-HERE"); visitor.trackingserver = "INSERT-TRACKING-SERVER-HERE"; 2. Instantiate and configure AppMeasurement: var s:appmeasurement = new AppMeasurement(); s.account = "INSERT-RSID-HERE"; s.trackingserver = "INSERT-TRACKING-SERVER-HERE"; s.visitor = Visitor.getInstance("INSERT-MCORG-ID-HERE"); At a minimum, configure the following three variables:

31 Video Heartbeat Developer Guide 31 s.account s.trackingserver s.visitor These values can be copied directly from your s_code.js or AppMeasurement.js file. Next step: Implement PlayerDelegate. Implement PlayerDelegate The PlayerDelegate is used by video heartbeat to get information about the currently playing video, ad, and chapter. First, read How PlayerDelegate Works to understand the role of PlayerDelegate in video heartbeat. Implementing this interface is where you will typically spend a majority of your implementation time. Additional information on this interface is available in the Video Heartbeat SDK guide distributed with the download. To get started creating your own PlayerDelegate class, create a new class (File > New, ActionScript 3.0 Class) that uses com.adobe.primetime.va.playerdelegate as the object prototype: package { import com.adobe.primetime.va.playerdelegate; import com.adobe.primetime.va.adbreakinfo; import com.adobe.primetime.va.adinfo; import com.adobe.primetime.va.chapterinfo; import com.adobe.primetime.va.errorinfo; import com.adobe.primetime.va.qosinfo; import com.adobe.primetime.va.videoinfo; import com.adobe.primetime.va.assettype; import fl.video.flvplayback; public class MyDelegate extends PlayerDelegate { public function MyDelegate(player:FLVPlayback) { _player = player; override public function get videoinfo():videoinfo { var vi:videoinfo = new VideoInfo(); vi.playername = ""; vi.id = ""; vi.name = ""; vi.length = -1; vi.playhead = -1; vi.streamtype = AssetType.ASSET_TYPE_LINEAR; return vi; override public function get adbreakinfo():adbreakinfo { var abi:adbreakinfo = new AdBreakInfo(); abi.name = ""; abi.playername = ""; abi.position = 1; abi.starttime = -1; return abi; override public function get adinfo():adinfo { var ai:adinfo = new AdInfo(); ai.id = ""; ai.name = ""; ai.length = -1; ai.position = 1; ai.cpm = ""; return ai;

32 Video Heartbeat Developer Guide 32 override public function get chapterinfo():chapterinfo { var ci:chapterinfo = new ChapterInfo(); ci.name = ""; ci.length = -1; ci.position = 1; ci.starttime = -1; return ci; private var _player:flvplayback; In most cases you'll want to pass your player object to the constructor of your new class so you can use it to read the player metadata and playhead. This example uses FLVPlayback, but you can pass an object of any type. Working example at Analytics Video Heartbeat Demo. Video Information The get VideoInfo method returns a VideoInfo object that contains details about the video player and the currently playing video. Before you can define this object, you'll need to use the API documentation provided by your player to find out how video information is retrieved. Video information is usually a property of the player object, or retrieved using a private method. For example, when using FLVPlayback, the playhead is a property of the FLVPlayback object: _player.playheadtime To implement your custom get VideoInfo method, you'll need the following information: Parameter playername id name length playhead streamtype Required? No Description The name of the video player that is playing back the main content The ID of the video asset The name of the video asset (opaque string value) The duration (in seconds) of the video asset. If streamtype is set to vod, return the length of the video. For other video types, return -1 as the length. The current playhead location (in seconds) inside the video asset (excluding ad content) at the moment this method was called. The type of the video asset, one of the following: AssetType.ASSET_TYPE_LIVE, AssetType.ASSET_TYPE_LINEAR, AssetType.ASSET_TYPE_VOD After you have figured out how to get the required information, update the getvideoinfo method to return a VideoInfo object with the video information. How you populate each value is up to you, and varies based on your player. For example, you might load the video player name using a configuration file, or you could hard-code the value if you use only one player. Ad Break Information Ad breaks provide insight as to when a particular ad was displayed. For example, if you have a pre-roll and a midpoint ad break, you can collect position data along with the specific ad data. If you have only one ad break, you can simply provide 1 for the position and leave the name blank.

33 Video Heartbeat Developer Guide 33 Parameter playername name position starttime Required? No No Description The name of the video player responsible with playing back the current advertisement break. The name of the ad-break. The position (index) of the pod inside the main content (starting with 1). The offset of the ad-break inside the main content (in seconds). Defaults to the playhead inside the main content at the moment of the trackadstart call. Ad Information If you are tracking video ads, ad information is retrieved using a similar process used to retrieve video information, except you return an AdInfo object instead with details about the currently playing video ad. Use the API documentation provided by your Ad vendor to determine the following: Parameter id length position name cpm Required? No No Description The ID of the ad asset The duration (in seconds) of the ad asset The position of the pod inside the main content (starting with 1) The name of the ad asset (opaque string value) The CPM value associated with this ad After you have figured out how to get the required information, update the getadinfo method to return an AdInfo object with the ad information. Chapter Information If you are tracking chapters, you'll need to coordinate the chapter information returned with each call you make to trackchapterstart. Since chapters are likely defined by you and not your video player, you'll need a way to retrieve chapter definitions to populate this object. Parameter name length position starttime Required No Description The name of the chapter (opaque string value) The duration (in seconds) of the chapter The position of the chapter inside the main content (starting from 1) The offset inside the main content where the chapter starts Update the getchapterinfo method to retrieve properties or call the required APIs. Next step: Configure Video Heartbeat Configure Video Heartbeat After you Implement PlayerDelegate, you are ready to add the video heartbeat code to your project. Before you proceed, make sure you have the following: A configured AppMeasurement object that uses the Marketing Cloud Visitor ID Service. An instance of your custom PlayerDelegate object.

34 Video Heartbeat Developer Guide 34 Your publisher ID (assigned by Adobe). The following snippet demonstrates the code required to configure Video Heartbeat. This is in addition to the code you added to configure the Marketing Cloud visitor ID service and AppMeasurement. // Instantiate AdobeAnalytics plugin. var aaplugin:adobeanalyticsplugin = new AdobeAnalyticsPlugin(s); // Register the AdobeAnalytics plugin with the VHL. var plugins:vector.<iplugin> = new Vector.<IPlugin>(); plugins.push(aaplugin); // create player delegate var pd:mydelegate = new MyDelegate(player); // create video heartbeat var videoheartbeat:videoheartbeat = new VideoHeartbeat(pd, plugins); // Instantiate the configuration object. var heartbeatconfig:configdata = new ConfigData(" "sc_va", "unknown"); // replace "unknown" with your Adobe-assigned publisher ID // Set this to true to enable the "quietmode" heartbeatconfig.quietmode = false; // Set this to true to activate the debug tracing heartbeatconfig.debuglogging = false; videoheartbeat.configure(heartbeatconfig); Working example at Analytics Video Heartbeat Demo. Test Your Configuration Before you continue, load your code in a browser to make sure everything loads without errors. Optionally, set the debuglogging flag to true while you test: heartbeatconfig.debuglogging = true; // remove or set to false for production! Next, publish your project and check the console for errors. If you check the network tab, you'll see a call to your Analytics data collection server, and additional calls to heartbeats.omtrdc.net. Next step: Track Player Events Track Player Events Flash media players are typically tracked by attaching callback functions to the video player event handlers. The next step is to call the video heartbeat track methods when specific events occur in your player. This typically involves subscribing to events, registering a callback function, and then calling the correct method in the callback. Review the Track Methods and Player Events sections for details on exactly which method you should call for each corresponding player event. The following example demonstrates event handling for a Flash video player (FLVPlayback): import fl.video.videoevent; /* configure player events */ player.addeventlistener(fl.video.videoevent.playing_state_entered, onplay); player.addeventlistener(fl.video.videoevent.paused_state_entered, onpause); player.addeventlistener(fl.video.videoevent.scrub_start, onseekstart); player.addeventlistener(fl.video.videoevent.scrub_finish, onseekfinish); player.addeventlistener(fl.video.videoevent.complete, oncomplete); function onplay(e:fl.video.videoevent):void { if (player.playheadtime == 0) { videoheartbeat.trackvideoload();