Adobe Marketing Cloud Video Heartbeat
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
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
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.
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.
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 20 30 Unknown/Non-Documented 40 50 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 2014. 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
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.
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.
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
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:
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:
Configure Analytics Video Reporting 12
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.
Video Reports 14 Quick Filters Quickly display video metrics by device or geo country:
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.
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.
Video Reports 17
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.
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()
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)
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;
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:
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.
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
Video Heartbeat Developer Guide 25 var videoheartbeat = new ADB.va.VideoHeartbeat(myDelegate, plugins); var heartbeatconfig = new ADB.va.ConfigData(); heartbeatconfig.trackingserver = "http://heartbeats.omtrdc.net"; // 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();
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 http://heartbeats.omtrdc.net. 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.
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.
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.
Video Heartbeat Developer Guide 29 4. 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.
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:
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;
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.
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.
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("http://heartbeats.omtrdc.net", "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();
Video Heartbeat Developer Guide 35 videoheartbeat.trackplay(); else videoheartbeat.trackplay(); function oncomplete(e:fl.video.videoevent):void { videoheartbeat.trackcomplete(); videoheartbeat.trackvideounload(); function onpause(e:fl.video.videoevent):void { videoheartbeat.trackpause(); function onseekstart(e:fl.video.videoevent):void { videoheartbeat.trackseekstart(); function onseekfinish(e:fl.video.videoevent):void { videoheartbeat.trackseekcomplete(); 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 http://heartbeats.omtrdc.net. 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.
Video Heartbeat Developer Guide 36 Sending extra video data on start Optionally send additional video data to track with each video. JavaScript and ActionScript All variables that are set on the AppMeasurement object (usually 's') are sent in with the initial trackplay() call to Analytics. You can set additional evars, props, contextdata, and events directly on the AppMeasurement object before the video starts. s.contextdata['my.media.meta.key1'] = 'value1'; s.evar1 = 'value1';' s.evar2 = 'value2'; s.evar3 = 'value3'; s.evar4 = 'value4'; s.media.play(myvideoid, myvideoplayhead); If you are playing multiple videos using the same instance object, be sure to clear out any variables that you do not want to persist between videos. evars set by context data that is sent with the initial trackplay() call should be set to expire on Page View. With Page View expiration, evars set on this call will show accurate data for the video views, visits, unique visitors, instances, entries, and exits metrics. evars set on this call will also show accurate data for custom events included on this call. However, these evars will not show any data for video time viewed, video completes, and video segment views. Note: Sending additional variables with the initial trackplay() call is included in stream-based pricing.
Video Heartbeat Developer Guide 37 ios Because ios does not use persistent variables on the AppMeasurement object, you'll need to send additional video data using a separate call to trackaction. // ios example: ~line 67 of VideoAnalyticsProvider.m in the sample app // that is distributed with the video heartbeat SDK #pragma mark - VideoPlayer notification handlers. - (void)onmainvideoloaded:(nsnotification *)notification { [self.videoheartbeat trackvideoload]; NSMutableDictionary *contextdata = [NSMutableDictionary dictionary]; // these 4 context data values should be sent with every extra call // they should match the values from the video that is being loaded // These are mapped to video solution variables automatically by processing // rules that were configured when you enabled video heartbeat [contextdata setobject:self.player.videoid forkey:@"a.media.name"]; [contextdata setobject:@"ios basic media player" forkey:@"a.media.playername"]; [contextdata setobject:@"ios" forkey:@"a.media.channel"]; [contextdata setobject:@"video" forkey:@"a.contenttype"]; // you can add any additional context data to the contextdata dictionary // These extra values must be mapped using context data // In this example, the processing rule can check for the "my.media.meta.load" key // you can use any key you want to trigger the processing rule [contextdata setobject:@"1" forkey:@"my.media.meta.load"]; [contextdata setobject:@"value1" forkey:@"my.media.meta.key1"]; [contextdata setobject:@"value2" forkey:@"my.media.meta.key2"]; [contextdata setobject:@"value3" forkey:@"my.media.meta.key3"]; [contextdata setobject:@"value4" forkey:@"my.media.meta.key4"]; // and so on... // the context data is attached and sent with a trackaction // this call does not increment page views [ADBMobile trackaction:self.player.videoid data:contextdata]; - (void)onplay:(nsnotification *)notification { [self.videoheartbeat trackplay]; evars set by context data that is sent with this call should be set to expire on Visit, so that the variables persist until the video start event is sent by the trackplay call. With visit expiration, evars set on this call will show accurate data for the video views, visits, unique visitors, instances, entries, and exits metrics. evars set on this call will also show accurate data for custom events set using processing rules based on this call. However, these evars will show inaccurate data for video time viewed, video completes, and video segment views for any visitors who view more than one video during a visit. The following image demonstrates a sample processing rule to capture the data sent by this call (this is the same on ios and Android):
Video Heartbeat Developer Guide 38 Note: trackaction calls are billed as standard server calls, and are not included as part of video stream-based pricing. Android Because Android does not use persistent variables on the AppMeasurement object, you'll need to send additional video data using a separate call to trackaction(). // Android example: ~line 60 of AnalyticsProvider.java in the sample app // that is distributed with the video heartbeat SDK switch (playerevent) { case VIDEO_LOAD: Log.d(LOG_TAG, "Video loaded."); _videoheartbeat.trackvideoload(); HashMap<String, Object> contextdata = new HashMap<String, Object>(); // these 4 context data values should be sent with every extra call // they should match the values from the video that is being loaded // These are mapped to video solution variables automatically by processing // rules that were configured when you enabled video heartbeat contextdata.put("a.media.name", "video ID"); contextdata.put("a.media.playername", "Android basic media player"); contextdata.put("a.media.channel", "Android"); contextdata.put("a.contenttype", "video"); // you can add any additional context data to the contextdata dictionary // These extra values must be mapped using context data // In this example, the processing rule can check for the "my.media.meta.load" key // you can use any key you want to trigger the processing rule contextdata.put("my.media.meta.load", "1"); contextdata.put("my.media.meta.key1", "value1"); contextdata.put("my.media.meta.key2", "value2"); contextdata.put("my.media.meta.key3", "value3"); contextdata.put("my.media.meta.key4", "value4"); // and so on... // the context data is attached and sent with a trackaction // this call does not increment page views Analytics.trackAction("Video metadata", contextdata); break; evars set by context data that is sent with this call should be set to expire on Visit, so that the variables persist until the video start event is sent by the trackplay call. With visit expiration, evars set on this call will show accurate data for the video views,
Video Heartbeat Developer Guide 39 visits, unique visitors, instances, entries, and exits metrics. evars set on this call will also show accurate data for custom events set using processing rules based on this call. However, these evars will show inaccurate data for video time viewed, video completes, and video segment views for any visitors who view more than one video during a visit. The following image demonstrates a sample processing rule to capture the data sent by this call (this is the same on ios and Android): Note: trackaction() calls are billed as standard server calls, and are not included as part of video stream-based pricing. Sending extra video data during playback Optionally send additional video data and events during playback. JavaScript and ActionScript You can set custom events and send additional video data using s.tl() calls during video playback. s.contextdata['a.media.name'] = medianame; s.contextdata['a.media.playername'] = mediaplayername; s.contextdata['a.media.channel'] = "web"; s.contextdata['a.contenttype'] = "video"; s.events = "event7"; s.evar1 = 'value1';' s.evar2 = 'value2'; s.linktrackvars = "events,evar1,evar2,contextdata.a.media.name,contextdata.a.media.playername,contextdata.a.media.channel,contextdata.a.contenttype"; s.linktrackevents = "event7"; s.tl(true,"o","test Video Event"); evars set on this call or set by context data that is included on this call should be set to expire on Page View. With Page View expiration, evars set on this call will show accurate data for the video views, visits, unique visitors, instances, entries, and exits metrics. evars set on this call will also show accurate data for custom events included on this call. However, these evars will not show any data for video time viewed, video completes, and video segment views. Note: s.tl() calls are billed as standard server calls, and are not included as part of video stream-based pricing.
Video Heartbeat Developer Guide 40 ios You can set custom events and send additional video data using trackaction calls. // ios example: you can make additional calls anywhere during video playback NSMutableDictionary *contextdata = [NSMutableDictionary dictionary]; // these 4 context data values should be sent with every extra call // they should match the values from the video that is being loaded // These are mapped to video solution variables automatically by processing // rules that were configured when you enabled video heartbeat [contextdata setobject:self.player.videoid forkey:@"a.media.name"]; [contextdata setobject:@"ios basic media player" forkey:@"a.media.playername"]; [contextdata setobject:@"ios" forkey:@"a.media.channel"]; [contextdata setobject:@"video" forkey:@"a.contenttype"]; // you can add any additional context data to the contextdata dictionary // These extra values must be mapped using context data // our processing rule (see screenshot below) checks for the "my.media.eventname" key // you can use any key you want to trigger the processing rule [contextdata setobject:@"1" forkey:@"my.media.eventname"]; [contextdata setobject:@"value1" forkey:@"my.media.event.key1"]; // and so on... // the context data is attached and sent with a trackaction // this call does not increment page views [ADBMobile trackaction:self.player.videoid data:contextdata]; evars set by context data that is sent with this call should be set to expire on Page View. With Page View expiration, evars set on this call will show accurate data for the video views, visits, unique visitors, instances, entries, and exits metrics. evars set on this call will also show accurate data for custom events set using processing rules based on this call. However, these evars will not show any data for video time viewed, video completes, and video segment views. The following image demonstrates a sample processing rule to capture the data sent by this call (this is the same on ios and Android): Note: trackaction calls are billed as standard server calls, and are not included as part of video stream-based pricing.
Video Heartbeat Developer Guide 41 Android You can set custom events and send additional video data using trackaction() calls. // Android example: you can make additional calls anywhere during video playback HashMap<String, Object> contextdata = new HashMap<String, Object>(); // these 4 context data values should be sent with every extra call // they should match the values from the video that is being loaded // These are mapped to video solution variables automatically by processing // rules that were configured when you enabled video heartbeat contextdata.put("a.media.name", "video ID"); contextdata.put("a.media.playername", "Android basic media player"); contextdata.put("a.media.channel", "Android"); contextdata.put("a.contenttype", "video"); // you can add any additional context data to the contextdata dictionary // These extra values must be mapped using context data // our processing rule (see screenshot below) checks for the "my.media.eventname" key // you can use any key you want to trigger the processing rule contextdata.put("my.media.eventname", "1"); contextdata.put("my.media.event.key1", "value1"); // and so on... // the context data is attached and sent with a trackaction // this call does not increment page views Analytics.trackAction("Video event", contextdata); evars set by context data that is sent with this call should be set to expire on Page View. With Page View expiration, evars set on this call will show accurate data for the video views, visits, unique visitors, instances, entries, and exits metrics. evars set on this call will also show accurate data for custom events set using processing rules based on this call. However, these evars will not show any data for video time viewed, video completes, and video segment views. The following image demonstrates a sample processing rule to capture the data sent by this call (this is the same on ios and Android): Note: trackaction() calls are billed as standard server calls, and are not included as part of video stream-based pricing.
Video Measurement Timeline 42 Video Measurement Timeline This topic provides an overview of when video data is collected. Note that the heartbeat frequency interval (10 seconds) is the maximum time between heartbeat calls. Within a 10 second interval, you might see mulitple heartbeat calls based on what is occurring in your video. You will see one or more calls to the heartbeat service every 10 seconds, including the following: Active A video playback event, such as play, buffer, and so on For example, in a 10 second interval, you might see the following video events: Active Play Buffer Bitrate change Ad start Ad play This would indicate that during this interval the user is active, is playing the main asset, encounters a buffering which leads to bitrate change, an ad starts and then plays. You can use a packet analyzer to view the s:event:type in each heartbeat call to determine the video event that occurred. Event Number Event Name Player to Analytics Player to Heartbeat Collection Heartbeat Collection to Analytics 0 Video Load Single call at beginning of the stream (when the user clicks play) Single heartbeat when requesting playback, to capture stream starts Single call with identifying content info. This includes: page name (if set) content type player name (a.media.playername) view (a.media.view) length (a.media.length) name (a.media.name)
Video Measurement Timeline 43 1 Video Start - Single heartbeat when the 1st frame is rendered, to capture startup time - 2 Heartbeat - Regular heartbeat info - 3 Pod Start - - - 4 Ad Start Single call at beginning of ad stream Ad Start - 5 Ad Heartbeat - Just like regular heartbeat, but with content-type = ad and different video name - 6 Ad Complete - Ad Heartbeat Single call per ad with all relevant ad info 7 Pod Complete - - 8 Scrub - Regular heartbeat - 9 Buffer Event - Buffer Heartbeat - 10 Post-buffer Heartbeat - Regular heartbeat enhanced with info about the timing and duration of buffer event - 11 Error - Error call with details about the error (type, impact, etc) - 12 Video Complete - Complete call (~ 2 minutes after last heartbeat is received) Single call is sent by the Heartbeat Collection server to the Analytics server with the time viewed metrics.
Video Measurement Parameters 44 Video Measurement Parameters Lists the data collection parameters sent by video heartbeat. Video Core Parameters Label Required Variable Type Context Data Variable Sent With Video Player evar a.media.playername Video Start Syndication Channel No evar a.media.channel Video Start Content Type evar a.contenttype Video Start Video Segment evar a.media.segment Heartbeat Video ID evar, prop a.media.name Video Start Video Name No classification a.media.friendlyname Video Start Video Length classification a.media.length Video Start Video View event a.media.view Video Start Video Segment View event a.media.segmentview Heartbeat Video Complete No event a.media.complete Heartbeat Video Time Spent event a.media.timeplayed Heartbeat Video Ad Parameters Label Required Variable Type Context Data Variable Sent With Pod ID evar a.media.ad.pod Ad Start Pod Name No classification a.media.ad.podfriendlyname Ad Start Pod Position (Offset) classification a.media.ad.podsecond Heartbeat Ad ID evar a.media.ad.name Ad Start Ad Name No classification a.media.ad.friendlyname Ad Start
Video Measurement Parameters 45 Ad Length classification a.media.ad.length Ad Start Ad Player Name evar a.media.ad.playername Ad Start Ad Position Within Pod evar a.media.ad.podposition Ad Start Ad View event a.media.ad.view Ad Start Ad CPM No event a.media.ad.cpm Ad Start Ad Complete event a.media.ad.complete Heartbeat Ad Time Spent event a.media.ad.timeplayed Heartbeat Video Chapter Parameters Label Required Variable Type Context Data Variable Sent With Chapter ID evar a.media.chapter.name Heartbeat Chapter Name No classification a.media.chapter.friendlyname Heartbeat Chapter Position classification a.media.chapter.position Heartbeat Chapter Offset No classification a.media.chapter.offset Heartbeat Chapter Length No classification a.media.chapter.length Heartbeat Chapter View event a.media.chapter.view Heartbeat Chapter Complete No event a.media.chapter.complete Heartbeat Chapter Time Spent event a.media.chapter.timeplayed Heartbeat
How PlayerDelegate Works 46 How PlayerDelegate Works If you have reviewed the Track Methods and Player Events topic, you might have noticed that none of the track methods take any parameters. Instead of passing video name, playhead information, and chapter information directly to these methods, video heartbeat uses a PlayerDelegate class that is queried for this information instead. As part of your implementation, you are required to extend this class to provide specific information about your player. To understand the interaction between the player event listeners, the track functions, and the PlayerDelegate, consider the following example. Event Listeners When tracking HTML 5 video, you might subscribe to the play event using the following code: var myvideo = document.getelementbyid('movie'); myvideo.addeventlistener('play',trackvideoplay,false); VideoHeartbeat Track Functions In the trackvideoplay() JavaScript function you assigned to handle the play event, you would call VideoHeartbeat.trackPlay() to let video heartbeat know that playback has started: function trackvideoplay() { VideoHeartbeat.trackPlay(); ; Note that no video information is passed to the trackplay(). PlayerDelegate When the video heartbeat track... methods are called, your implementation of PlayerDelegate is queried automatically as needed to provide any required details about the video, ad, or chapter. This removes the need for you to determine exactly what information is needed by each track function, you can provide a single object that returns the most current information available. The following is a simple example of an implementation of PlayerDelegate for an HTML 5 video player that does not track ads or chapters: var mydelegate = new ADB.va.PlayerDelegate(); mydelegate.getvideoinfo = function() { var myvideo = document.getelementbyid('movie'); var videoinfo = new ADB.va.VideoInfo(); videoinfo.id = "My Video Name"; videoinfo.playername = "HTML5 Video Player"; videoinfo.length = myvideo.duration; videoinfo.streamtype = "vod"; videoinfo.playhead = myvideo.currenttime; return videoinfo; mydelegate.getadinfo = function() { return null; mydelegate.getchapterinfo = function() { return null; mydelegate.onerror = function() { return null; mydelegate.getqosinfo = function() { // QoS reports are not available in Adobe Analytics return null;
How PlayerDelegate Works 47 In this example, when VideoHeartbeat.trackPlay() is called, your instance of VideoInfo is read to determine the current offset of the video to calculate time played. The querying happens automatically, you are required only to extend PlayerDelegate and provide an instance of the extended class when you initialize video heartbeat. Make sure you take a close look at the sample players to see how PlayerDelegate is extended.
Track Methods and Player Events 48 Track Methods and Player Events The video player being instrumented must be capable of triggering a series of events through which any subscriber can be informed about what happens inside the video player. The following tables present the one-to-one correspondence between player events and the associated call exposed by the public API of the video heartbeats library. Video Playback Event Load the main video asset Unload the main video asset Playback start Playback stop/pause Playback complete Seek start Seek complete Buffer start Buffer complete Method Call trackvideoload() trackvideounload() trackplay() trackpause() trackcomplete() trackseekstart() trackseekcomplete() trackbufferstart() trackbuffercomplete() Parameter List None None None None None None None None None The following methods must be called in pairs (that is, each track...start() must have a corresponding track...complete()): trackbufferstart() and trackbuffercomplete() trackpause() and trackplay() (note that if the player is closed before the pause resumes, the corresponding method might not be called) trackseekstart() and trackseekcomplete() (with an exception: there may be multiple trackseekstart() calls before a trackseekcomplete()) The track...start() call are not required to be followed by a track...complete() call, as there may be other track...() method calls in between. For example, the following sequence of track...() method calls is valid and describes a user who is seeking through the stream while paused, and resumes playback after two seeks: trackpause(); // Signals that the user paused the playback. trackseekstart(); // Signals that the user started a seek operation. trackseekstart(); // Signals that the user started another seek operation (before the first one was completed). trackseekcomplete(); // Signals that the second seek operation has completed. trackplay(); // Signals that the user resumed playback. Ad Playback Event An ad starts An ad completes Method Call trackadstart() trackadcomplete() Parameter List None None The trackadstart() and trackadcomplete() methods are the only track methods required in order to signal the beginning and completion of an ad.
Track Methods and Player Events 49 You do not need to (and should not) call any additional track methods to signal the transition from ad to content or vice-versa. For instance, you should not signal the pause of the main video (via trackpause()) when an ad starts. This is handled automatically inside the VideoHeartbeat library when you call trackadstart() Chapter Tracking Event A new chapter starts A chapter completes Method Call trackchapterstart() trackchaptercomplete() Parameter List None None
Migrating to Video Heartbeat 50 Migrating to Video Heartbeat This section describes the steps to migrate from milestone to video heartbeat. Note: ActionScript 3 implementations require Flash Player version 10 or higher. If you plan to support Flash Player 9, you must use ActionScript 2. Step Task Location Description Enable video reports Marketing reports and analytics UI Video heartbeat uses dedicated solution variables to track video and video ad data, so you no longer need to map video variables to Analytics variables. Once enabled, video reports are populated as soon as your report suite receives video data. Configure Analytics Video Reporting Remove context data mapping Player code Context data mapping is no longer needed. Remove Context Data Mapping Remove milestones, track seconds, and complete Player code Milestones and track seconds are replaced by heartbeat. Completes are determined by the heartbeat server. Remove Unused Tracking Methods and Configuration Remove calls to Media.monitor. Player code Media monitor is not available in heartbeat tracking, however, any custom context data, custom variables, or custom events set on the AppMeasurement object are sent with the initial play call. Sending extra video data on start Make sure you clear or update variables before each play call that you make using the same appmeasurement instance. Remove Unused Tracking Methods and Configuration Implement video heartbeat. Player code Video heartbeat provides new methods that handle much of the logic of keeping track of playhead position, and provide a more direct mapping for player events. For details, see Video Heartbeat Developer Guide. Remove Context Data Mapping Leave trackusingcontextdata enabled, then set contextdatamapping to null, since the mapping is configured automatically when you Configure Analytics Video Reporting. appmeasurement.media.trackusingcontextdata = true; appmeasurement.media.contextdatamapping = null;
Migrating to Video Heartbeat 51 Remove Unused Tracking Methods and Configuration Video heartbeat tracking with solution variables significantly reduces the amount of configuration required in your code. If set, remove the following configuration variables: autotrack autotracknetstreams adtrackseconds adtrackmilestones adtrackoffsetmilestones adsegmentbymilestones adsegmentbyoffsetmilestones completebycloseoffset completecloseoffsetthreshold SegmentByMilestones segmentbyoffsetmilestones trackevents trackmilestones trackoffsetmilestones trackseconds trackvars Remove calls to the following methods: complete monitor
Contact and Legal Information 52 Contact and Legal Information Information to help you contact Adobe and to understand the legal issues concerning your use of this product and documentation. Help & Technical Support The Adobe Marketing Cloud Customer Care team is here to assist you and provides a number of mechanisms by which they can be engaged: Check the Marketing Cloud help pages for advice, tips, and FAQs Ask us a quick question on Twitter @AdobeMktgCare Log an incident in our customer portal Contact the Customer Care team directly Check availability and status of Marketing Cloud Solutions Service, Capability & Billing Dependent on your solution configuration, some options described in this documentation might not be available to you. As each account is unique, please refer to your contract for pricing, due dates, terms, and conditions. If you would like to add to or otherwise change your service level, or if you have questions regarding your current service, please contact your Account Manager. Feedback We welcome any suggestions or feedback regarding this solution. Enhancement ideas and suggestions for Adobe Analytics can be added to our Customer Idea Exchange. Legal 2014 Adobe Systems Incorporated. All Rights Reserved. Published by Adobe Systems Incorporated. Terms of Use Privacy Center Adobe and the Adobe logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. All third-party trademarks are the property of their respective owners.