Video Heartbeat - Adobe Marketing Cloud

Transcription

Adobe® Marketing Cloud
Video Heartbeat
Contents
Measuring Video in Adobe Analytics using Video Heartbeat..............................5
Release Notes for Video Heartbeat........................................................................6
Getting Started.........................................................................................................8
Federated Analytics.................................................................................................9
Federated Analytics Rules Form...........................................................................................10
Video Analytics Reporting....................................................................................18
Configure Analytics Video Reporting.....................................................................................18
Video Dashboards.................................................................................................................20
Video Overview........................................................................................................................................21
Video Detail..............................................................................................................................................22
Video Daypart..........................................................................................................................................23
Video Concurrent Viewers........................................................................................................................24
Video Reports.......................................................................................................................24
Content (Core) Variables and Events.......................................................................................................25
Ad Variables and Events..........................................................................................................................27
Chapter Variables and Events..................................................................................................................28
Quality Variables and Events....................................................................................................................29
Video Heartbeat 1.5 Developer Guide..................................................................32
How VideoPlayerPluginDelegate Works................................................................................32
JavaScript VideoPlayerPluginDelegate....................................................................................................32
iOS VideoPlayerPluginDelegate...............................................................................................................33
Android VideoPlayerPluginDelegate........................................................................................................35
ActionScript VideoPlayerPluginDelegate..................................................................................................36
Video Measurement Parameters...........................................................................................37
Standard Metadata Parameters............................................................................................41
Last updated 8/16/2016
Video Heartbeat
Contents
Track Methods and Player Events.........................................................................................43
Video Measurement Timeline................................................................................................45
Scenario and Timeline Illustrations..........................................................................................................46
Tracking Explained...................................................................................................................................47
Non-Linear Tracking Scenarios................................................................................................................63
Pause tracking..........................................................................................................................................64
JavaScript Players.................................................................................................................67
Download the Video Heartbeat Library - JS.............................................................................................68
Implement VideoPlayerPluginDelegate - JS.............................................................................................68
Attaching Custom Metadata.....................................................................................................................71
Standard metadata keys for JavaScript....................................................................................................72
Sample implementation on JavaScript.....................................................................................................73
Configure the Video Heartbeat Library.....................................................................................................73
Implement VideoPlayerPluginDelegate - JS.............................................................................................75
Track Player Events..................................................................................................................................79
Test Your Video Measurement Code........................................................................................................81
Debug Logging.........................................................................................................................................81
iOS Players...........................................................................................................................82
Download the Video Heartbeat Library....................................................................................................83
Configure AdobeMobileLibrary.................................................................................................................83
Implement VideoPlayerPluginDelegate....................................................................................................84
Standard metadata keys for iOS..............................................................................................................89
Sample implementation on iOS................................................................................................................90
Configure the Video Heartbeat Library.....................................................................................................91
Track Player Events..................................................................................................................................93
Test Your Video Measurement Code........................................................................................................93
Debug Logging.........................................................................................................................................93
Android Players.....................................................................................................................94
Download the Video Heartbeat Library....................................................................................................95
Configure AdobeMobile Library................................................................................................................95
Implement VideoPlayerPluginDelegate....................................................................................................96
Standard metadata keys for Android......................................................................................................100
Video Heartbeat
Sample implementation on Android.......................................................................................................101
Configure the Video Heartbeat Library...................................................................................................102
Track Player Events................................................................................................................................103
Test Your Video Measurement Code......................................................................................................104
Debug Logging.......................................................................................................................................104
ActionScript Players............................................................................................................105
Download the Video Heartbeat Library..................................................................................................106
Add the AppMeasurement for Flash library to a Project.........................................................................106
Configure AppMeasurement..................................................................................................................107
Implement VideoPlayerPluginDelegate..................................................................................................108
Attaching Custom Metadata...................................................................................................................112
Configure the Video Heartbeat Library...................................................................................................112
Track Player Events................................................................................................................................114
Test Your Video Measurement Code......................................................................................................115
Debug Logging.......................................................................................................................................116
OTT (Over-the-Top) Analytics..............................................................................................117
Roku.......................................................................................................................................................118
AppleTV.................................................................................................................................................118
Video Heartbeat 2.x Developer Guides..............................................................119
Migrating to Video Heartbeat..............................................................................120
What's New in Version 1.5...................................................................................................121
Measuring Video FAQ..........................................................................................123
Documentation Updates.....................................................................................127
Historical Release Notes.....................................................................................132
Contact and Legal Information...........................................................................134
Video Heartbeat
Measuring Video in Adobe Analytics using Video
Heartbeat
5
Measuring Video in Adobe Analytics using Video
Heartbeat
Last Updated: June 30, 2016
Important: Before implementing the new video heartbeat solution described in this document, you must reach
out to your account manager and/or sales representative 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 ten 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.
Release Notes for Video Heartbeat
6
Information about new features and enhancements in video heartbeat.
This section contains the following information:
• Beta Release Notes
• Current Release Notes
• Documentation Updates, Historical Release Notes, and Marketing Cloud Release Notes
Beta Release Notes
The Summer 2015 Beta release of video heartbeat includes the following changes:
New Features
Feature
Description
Nielsen tracking
Manage Digital Content Ratings, powered by Adobe as it relates to video content.
DCR, an integration by Adobe and Nielsen, lets developers measure video
viewership, app launches, app crashes, advertisements, page views, and more.
For more information, see the following topics:
JavaScript:
• Manage Digital Content Ratings - JS
•
•
•
iOS:
• Manage Digital Content Ratings - iOS
•
•
•
Android:
• Manage Digital Content Ratings - Android
•
•
•
Current Release Notes
The November 5, 2015 release of video heartbeat includes the following changes:
New Features
Feature
Quartile events
7
Description
Added the following new Video Core parameters and events:
• 10% Progress Marker
For more information, see Content (Core) Variables and Events and Video
Measurement Parameters.
Average Minute Audience
event
Added the following new Video Core event:
• Average Minute Audience
For more information, see Content (Core) Variables and Events and Video
Measurement Parameters.
Important: To take advantage of and access these new events, you must perform the following steps:
1. Update to our latest video heartbeat tracking server.
he new tracking server is specific to each customer and should look like this: <Customer Analytics Visitor
Namespace>.hb.omtrdc.net (the previous version was heartbeats.omtrdc.net). More details can be
provided by your Adobe consultant.
The tracking server must be updated across all platforms that you’ve enabled with heartbeats.
2. In the Admin console, re-enable Video Core within the report suite video settings.
Documentation Updates, Historical Release Notes, and Marketing Cloud Release Notes
Resource
Description
Documentation Updates
View detailed information about updates to this guide that might not be included in
these release notes.
Historical Release Notes
View information about new features and enhancements in previous releases of
video heartbeat.
Marketing Cloud Release
Notes
View the latest release notes for the Adobe Marketing Cloud solutions.
Getting Started
8
Getting Started
Information that you should consider before implementing or migrating to video heartbeat.
• Business Considerations
• Technical Considerations
Business Considerations
Video heartbeat introduces a new way to measure video that is much more granular than milestones. Before you
implement or migrate, be aware of the following information:
• Video heartbeat introduces new reports and metrics that Adobe Analytics users might need help understanding.
• Heartbeat 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 representative and
have new stream-based pricing.
Technical Considerations
Video heartbeat provides a cost-effective video measurement solution with highly granular time metrics. Before you
implement or migrate, 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 custom timestamps. For iOS and Android, this means that your application cannot
be offline-enabled, and your report suite cannot be timestamp enabled. If you are unsure if your report suite is
timestamp enabled, contact Customer Care.
• Custom video completes are not supported, so you cannot define a custom location to determine when a video
view is considered complete.
Federated Analytics
9
Federated Analytics
Federated Analytics is an Adobe Video Analytics feature allowing standardized cross-platform sharing of video
data between partners, governed by rules/logic. The Customer can control the data that will be shared during each
video playback, down to an individual video level. The Partner can specify where the data should be sent, within
Adobe, based on defined triggers.
• What is Federated Analytics?
• Benefits of Federated Analytics
• Use Cases for Federated Analytics
• Prerequisites to Using Federated Analytics
What is Federated Analytics?
With Federated Analytics, Adobe is providing a way for organizations to automate and streamline the sharing of
video data in real-time, safely and securely, to gain more insight into their audiences.
Many publishers and advertisers need to share data to facilitate programming and media decisions; however, data
is typically sent via email, usually in spreadsheets, with metrics that are not standardized between organizations.
Federated Analytics solves these latency and data standardization issues, and facilitates the discovery of new
insights through data sharing. This feature enables standardized cross-platform sharing of video data, governed by
specified rules that determine what data to share and where to send it.
The “sharer” is able to control the data, down to an individual video level, that will be shared during each video
playback. The “receiver” can specify where the data should be sent (a specified report suite), based on defined
triggers. For instance, providers of syndicated content will be able to get real-time data from wherever their content
is played, as the playback is happening. Additionally, sites that own the customer experience can prescribe what
data they want to share.
Benefits of Federated Analytics
Benefits of Federated Analytics include:
• Standardization: Video and video ad metrics are measured and reported the same way across your own sites
and apps as well as any other syndication partners.
• Control: The sharer of data can control what data to share, down to the granularity of a video. The receiver can
specify via triggers the report suite to ingest the data.
• Data During Playback: Receive data in your specified report suites as the playback occurs on your syndication
partners’ sites or apps.
• Ease of Implementation: Enable by simply changing your tracking server.
Use Cases for Federated Analytics
Use cases for Federated Analytics include the following:
Federated Analytics
10
Prerequisites to Using Federated Analytics
Before using Federated Analytics, the following prerequisites must be met:
1. Both the Customer and Partner must sign an Adobe Addendum. Contact your Adobe sales representative or
account manager to obtain the addendum.
2. Download the Federated Analytics Rules Form.
3. Both Customer and Partner must complete the form.
4. Contact Adobe Client Care to schedule a call with an Adobe team to review and input the rules.
5. The Customer must implement Video Analytics (heartbeats) across any of sites and/or Apps from which it wants
to share data. See Getting Started.
Federated Analytics Rules Form
An example of the Federated Analytics Form and a link to download the form.
Note: After both the Sharer and Receiver have completed the Federated Analytics Rules form, contact your
Adobe sales representative for further instructions. To download the form, click here. Replace the sample
information with the information for your implementation and add rows to the table as necessary.
Definitions: Consider the following definitions as you implement Federated Analytics in your environment:
• Sharer: This is the company that owns the experience and/or viewer and has implemented Video Analytics
(heartbeats) on its site and/or Apps.
Sharers define the triggers and data they want to share for each video call.
• Receiver: The Receiver is the company that receives the data stream from the Sharer.
Federated Analytics
11
Based on their defined inbound rules (for example, platform), the Receiver can route data to specific report suites.
Expressions: When setting up rules, Expressions are used to determine the triggers and define the data set that
should be shared.
The following expressions are supported:
• Equal
• Contains
• All
• Any
• General Information
• Triggers
• Receiver Rules
• Data to Share
General Information
Customer & Partner Information
Sharer
Receiver
Outbound data rule name
Inbound data rule name
Triggers
A trigger is data that Video Heartbeat looks for and initiates the application of the defined rule sets.
Tip: One required trigger will always be the report suite of the Sharer to whom the data is being sent.
Here are a few examples of triggers.
Sharer's Trigger for Data Sharing
Sharing Triggers
Context Data Name
Expression
Context Data Value
Trigger #1
Receiver Rules
Receivers of shared data can specify to which report suite they want the data sent, based on a specific value/dimension
that is collected. In the example below, the player name includes the platform on which content is played, and based
on the player name, data can be sent to the Sharer’s platform-specific report suites. Any Context Data variable value
can be used to define where to send the data.
Receiver's Report Suite Rules
Rules
Context Data Name Expression
Context Data Value Receiver's Report Suite
to Ingest Data
Rule 1
a.media.playerName equal
mobile
Default Rule
This rule will be applied only if all of the previous conditions are not met.
mobilersid
Federated Analytics
12
Data to Share
Here is a list of all Context Data Variables that are collected by default. Sharers can determine which pieces of data
they want to share with the Receiver.
• The data to share is segmented by Video, Chapters, Video Ads, and QoE, and Visitor information.
For more information about each data point, see Video Measurement Parameters.
• Sharers can specify that they want to share the entire hit by selecting All.
• The Sharer can select one of the following options:
• S to share the data by entering Y or N.
• O to obfuscate certain pieces of data by Y or N.
The Receiver can select one of the following options:
• D to drop inbound data by entering Y or N.
• O to obfuscate certain pieces of data by entering Y or N.
• Custom metadata can be shared with the Receiver.
The metadata is an all or nothing trigger.
• If Drop or Obfuscate is left blank, it is assumed that the response is No.
• The X option is not available.
Video Core
Data points sharing: S= Share (Y/N), D= Drop at inbound (Y/N), O=Obfuscate(Y/N). Mark with Y/N every data
point that you want to share.
Sharer
Video Core
All
vid
aid
mid
Video Length
Receiver
S(hare)
Y
Y
Y
Y
Y
a.media.length
Content
Y
a.media.name
Content Segment
Y
a.media.segment
Content Type
Y
O(bfuscate)
D(rop)
O(bfuscate)
Federated Analytics
13
a.contentType
Content Player Name
Y
a.media.playerName
Content Channel
Y
a.media.channel
Content Starts
Y
a.media.view
Content Starts
Y
a.media.play
Content Completes
Y
a.media.complete
Content Segment Views
Y
a.media.segmentView
Content Time Spent
Y
a.media.timePlayed
Video Time Spent
Y
a.media.totalTimePlayed
Video Name
Y
a.media.friendlyName
a.media.sdkVersion
a.media.vhlVersion
Custom metadata
Custom user ids
Chapters
Y
Y
Y
Y
Federated Analytics
14
Sharer
Chapters
All
Chapter Starts
Receiver
S(hare)
O(bfuscate)
D(rop)
O(bfuscate)
Y
Y
c.a.media.chapter.view
Chapter
Y
c.a.media.chapter.name
Chapter Name
Y
c.a.media.chapter.friendlyName
Chapter Position
Y
c.a.media.chapter.position
Chapter Length
Y
c.a.media.chapter.length
Chapter Offset
Y
c.a.media.chapter.offset
Chapter Time Spent
Y
c.a.media.chapter.timePlayed
Chapter Completes
Y
c.a.media.chapter.complete
Custom metadata
Ads
Receiver
Sharer
Ads
S(hare)
O(bfuscate)
D(rop)
O(bfuscate)
Federated Analytics
15
All
Ad
Y
Y
a.media.ad.name
At Time Spent
Y
a.media.ad.timePlayed
Ad Name
Y
a.media.ad.friendlyName
Ad Length
Y
a.media.ad.length
Pod Position
Y
a.media.ad.podSecond
Ad Pod
Y
a.media.ad.pod
Ad in Pod Position
Y
a.media.ad.podPosition
Pod Name
Y
a.media.ad.podFriendlyName
Ad Player Name
Y
a.media.ad.playerName
Ad Starts
Y
a.media.ad.view
Ad Completes
Y
a.media.ad.complete
Custom metadata
QoE
Y
Federated Analytics
16
Sharer
QoE
All
Time to Start
Receiver
S(hare)
Y
Y
a.media.qoe.timeToStart
Buffer Events
Y
a.media.qoe.bufferCount
Total Buffer Duration
Y
a.media.qoe.bufferTime
Bitrate Changes
Y
a.media.qoe.bitrateChangeCount
Average Bitrate
Y
a.media.qoe.bitrateAverageBucket
Errors/Error Events
Y
a.media.qoe.errorCount
Dropped Frames
Y
a.media.qoe.droppedFrameCount
Drops before Start
Y
a.media.qoe.dropBeforeStart
Buffer Impacted Steams
Y
a.media.qoe.buffer
Bitrate Change Impacted Streams
Y
a.media.qoe.bitrateChange
Average Bitrate
a.media.qoe.bitrateAverage
Y
O(bfuscate)
D(rop)
O(bfuscate)
Federated Analytics
17
Error Impacted Streams
Y
a.media.qoe.error
Dropped Frame Impacted Streams
Y
a.media.qoe.droppedFrames
Enable Catch All
Enable Catch All
Yes
rsid
For more information about the existing Video Solution variables and events, see the following information:
• Video Core:
https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/c_content_variables_events.html
• Video Ads:
https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/c_ad_variables_events.html
• Video Chapter:
https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/c_chapter_variables_events.html
• Video QoE:
https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/c_quality_variables_events.html
• Variable types: https://marketing.adobe.com/resources/help/en_US/sc/appmeasurement/hbvideo/video_params.html
Video Analytics Reporting
18
Information about the process to enable video reporting as well an introduction to the video reports.
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.
Note: To take advantage of new capabilities, existing Video Analytics customers should re-enable video
tracking for their RSIDs.
1. In marketing reports & analytics, open Admin Tools > Report Suites.
2. Select the report suite(s) where you are collecting video data, then click Edit Settings > Video Management >
Video Reporting.
3. On the Video Reporting page, enable Video Core, and optionally enable Video Ads, Video Chapters, and
Video Quality.
Video measurement includes four modules:
• Video Core: Core video measurement is used for video content. This will use Solution (or Custom) Evars to
keep track of Content, Content Type, Content Player Name, and Content Channel. Solution (or Custom) Events
will be used for Video Initiates, Content Starts, Content Completes, and Content Time Spent.
• Video Ads: Video ad measurement is used for the measurement of ads within the video content. This will use
Solution Evars to measure Ad, Ad Player Name, Ad Pod, and Ad in Pod Position. Solution Events will be used
for Ad Starts, Ad Completes, Ad Time Spent, and Video Time Spent.
• Video Chapters: Video chapters measurement is used for the measurement of chapters. A chapter is a
sub-division of content within a single video. This will use a Solution Evar to store the Chapter ID. Solution
Events will be used for Chapter Starts, Chapter Completes, and Chapter Time Spent. Additional chapter metadata
of Chapter Name and Chapter Position will be provided as classifications of Chapter ID.
• Video Quality: Video quality measurement is used for measuring the quality of the content playback. This will
use Solution Evars to store Time to Start, Buffer Events, Total Buffer Duration, Bitrate Switches, Avg Bitrate,
Errors, and Dropped Frames. Solution Events will be used for Time to Start, Drops before Start, Buffer Impacted
19
Streams, Buffer Events, Total Buffer Duration, Bitrate Change Impacted Streams, Bitrate Changes, Avg Bitrate,
Error Impacted Streams, Error Events, Dropped Frame Impacted Streams, and Dropped Frames.
Enabling each module reserves a set of variables and creates a new set of reports. With the exception of Quality,
there will be no data in reports unless the corresponding implementation has been completed. Implementing the
Core module also implements the Quality module if you enable it.
If you aren't yet tracking ads, chapters, or playback quality, you can come back and enable additional options at
any time.
4. Click Save.
If this report suite is already configured to collect video data, you are presented an additional configuration page
after you click Save. If you see the Video Core Measurement page, continue to the next step.
5. (Conditional) On the Video Core Measurement page, select to continue using custom variables or to use solution
variables.
Option
Continue using custom variables.
Description
Pros: Video trending continues to work after migration.
Cons: Requires you to keep two custom eVars and three custom events
allocated to video.You regain use of one custom eVar and one custom event.
To continue using custom variables:
1. Select Use Custom Variables, then click Save.
2. When prompted, map your current custom eVars and events and then click
Save:
Migrate to solution variables.
Pros: You regain use of three custom eVars and four custom events.
Cons: You lose ALL historical trending and comparison for video reports.
Note: Migrating to solution
This means that you won't be able to trend video views or video time played
variables causes you to
for any dates before you migrated to video heartbeat. Do not migrate to
lose ALL historical trending
solution variables unless you are certain that you do not want to preserve
this trending!
20
Option
Description
and comparison for video
reports.
Note: We recommend all customers use solution variables and use
processing rules to put video data into existing props and eVars only
if they need to preserve historical continuity.
To migrate to solution variables:
1. Select Use Solution Variables, then click Save.
Video Dashboards
Adobe Analytics provides several reports and metrics to track video performance on your website.
In addition to the metrics and dimensions available when you enable each of the modules, there are three additional
dashboard-style reports that become available when you enable the Video Core module. Enabling the Ads module
also changes the appearance of a couple of these dashboard-style reports by adding additional metrics and filters.
Video reports are listed in the Reports > Reports & Analytics > Video section.
Video Report
Description
Common Business Insights
Video Overview
Displays several aggregate measurements • Totals for top video metrics including unique
to quickly monitor that videos are performing viewers, completion rate, average video
metrics, and average videos per visit.
as expected. A graph displays video starts
• Total content and ad starts for videos filtered
next to ad impressions to let you quickly view
by device type or country.
these metrics for each video.
Video Detail
Displays detailed metrics for all videos
including starts, concurrent viewers,
completion rate, play percentage, and ad
impressions.
Video Daypart
Displays content starts by time of day to let • Audience engagement by time of day.
• Audience engagement compared to previous
you quickly view when your audience is
date ranges.
engaged.
Video Events and
Video Variables
Reports for additional Video Reports are also • Video Conversion (Events that occur after
available. Video metrics and dimensions are video is viewed) by generating a report with
visits that include a content type of video.
standard Analytics variables that can be
• Next/previous video flow using the video
reported directly and added to other Analytics
name prop.
reports.
Video Concurrent
Viewers
Displays concurrent viewers during one day. • Per-minute audience engagement over a
The data can be filtered by content, device
24-hour interval.
type, or country.
• Totals for top video metrics including video
initiates, content and ad starts, and average
videos per visit.
• Total content and ad starts for videos filtered
21
Video Overview
The Video Overview dashboard is designed to let you monitor videos across your site.
The Video Overview display displays several aggregate measurements to quickly monitor that videos are performing
as expected. A graph displays content starts next to ad starts to let you quickly view these metrics for each video.
Quick Filters
Quickly display video metrics by device or geo country:
Video Performance
Click-and-drag to zoom in, then hover to view granular metrics for specific videos. Click
after you zoom.
to reset the view
Video Detail
The Video Detail dashboard displays detailed metrics for all videos, including concurrent viewers, content starts,
completion rate, time spent, and ad starts.
22
23
Video Daypart
The Video Daypart dashboard displays content starts by time of day to let you quickly view when your audience is
engaged.
24
Video Concurrent Viewers
The Video Concurrent Viewers dashboard displays concurrent viewers during one day. The data can be filtered by
content, device type, or country.
Tip: No data will be displayed if the selected interval is not an entire day.
Video Reports
Video variables and events are standard Analytics variables that can be reported directly and added to other Analytics
reports.
Video variables and events reports appear in the Video Content, Video Ads, Video Chapters, and Video Quality
entries of the Video menu section.
25
Content (Core) Variables and Events
Content (Core) variables and events are standard Analytics variables that can be reported directly and added to
other Analytics reports.
• Content (Core) Variables
• Content (Core) Events
Content (Core) Variables
Variable
Description
Video Name
The name of the video, as set on the name property of the VideoInfo. Video Name
is an automatic classification, so you'll see an extra menu level when you view
these reports.
Video Length
The length of the video (in seconds), as set on the length property of the
VideoInfo. Video Length is an automatic classification, so you'll see an extra menu
level when you view these reports.
This metric is used to draw the Drop-Off report.
Content
The ID of the content, as set on the id property of the VideoInfo.
26
Variable
Description
Content Segment
The interval describing the part of the content that has been viewed, in minutes
(e.g. [0-10]). The segment is computed as min and max of the playhead values
during a playback session.
Content Type
The type of the content, as set on the streamType property of the VideoInfo.
Content Player Name
The name of the player, as set on the playerName property on the VideoInfo.
Content Channel
The channel where the content is played, as set on the channel property on the
AdobeAnalyticsPlugin.
Content (Core) Events
Variable
Description
Video Initiates
The number of video initiates. A video initiate is an attempt to watch a video (e.g.
a user clicking the Play button, loading a video with auto-play)
Content Starts
The number of content starts. A content start is counted when the first frame of
the content has been rendered (from VHL 1.5).
Content Completes
The number of content completes. A content complete is counted when the
trackComplete() method is called.
Content Segment Views
The number of views of the content. A Content Segment View is counted when
there is at least one frame viewed.
Content Time Spent
The total amount of time (in seconds) spent watching the content (excluding ads).
Video Time Spent
The total amount of time (in seconds) spent watching the video (ads included).
This metric is available only if the Video Ads module is enabled.
10% Progress Marker
The number of playbacks that have passed the x% marker of the content. This
metric is set to 1 if the marker is passed at least once during a playback session
and the content length was provided via VHL configuration.
25% Progress Marker
50% Progress Marker
75% Progress Marker
95% Progress Marker
27
Variable
Description
Average Minute Audience
Average Minute Audience metric is computed as Total Content Time Spent, for
one specific video, divided by that Video’s Length for all of its playback sessions.
This metric will NOT be computed in the following cases where:
• Content length is not provided.
• Content length is zero or has a negative value.
Average Minute Audience across multiple videos with varying video lengths is
coming soon
Paused Impacted Streams
Pause Events
Total Pause Duration
Content Resumes
The number of streams impacted by pause. This metric is set to 1 only if at least
one pause event occurred during a playback session.
The number of pause events. This metric is computed as a count of pause periods
that occurred during a playback session.
The total amount of time (in seconds) spent in pause. This metric is computed as
a sum of all pause event durations that occurred during a playback session.
The number of resumes of the content. A Resume is counted for each playback
that resumes after more than 30 minutes of buffer, pause, or stall period OR if this
value is set by the player on the VideoInfo object before trackPlay.
Ad Variables and Events
Ad variables and events are standard Analytics variables that can be reported directly and added to other Analytics
reports.
• Ad Variables
• Ad Events
Ad Variables
Variable
Description
Ad Name
The name of the ad, as set on the name property of the AdInfo. Ad Name is an
automatic classification, so you'll see an extra menu level when you view these
reports.
Ad Length
The length of the ad (in seconds), as set on the name property of the AdInfo. Ad
Length is an automatic classification, so you'll see an extra menu level when you
view these reports.
Ad
The ID of the ad, as set on the id property of the AdInfo.
28
Variable
Description
Pod Name
The name of the ad break, as specified on the name property of the AdBreakInfo.
Pod Name is an automatic classification, so you'll see an extra menu level when
you view these reports.
Pod Position
The offset of the ad break inside the content (in seconds), as specified on the
startTime property of the AdBreakInfo. Pod Position is an automatic classification,
so you'll see an extra menu level when you view these reports.
Ad Pod
The auto-generated ID of the ad break.
Ad in Pod Position
The position (index) of the ad inside the parent ad break, as specified on the position
property of the AdInfo.
Ad Player Name
The name of the player responsible with rendering the ad, as specified on the
playerName property of the AdBreakInfo.
Ad Events
Event
Description
Ad Time Spent
The total amount of time (in seconds) spent watching the ad.
Ad Starts
The number of ad starts. An ad start is counted when the trackAdPlay() method
is called.
Ad Completes
The number of ad completes. An ad complete is counted when the
trackAdComplete() method is called.
Chapter Variables and Events
Chapter variables and events are standard Analytics variables that can be reported directly and added to other
Analytics reports.
• Chapter Variables
• Chapter Events
29
Chapter Variables
Variable
Description
Chapter Name
The name of the chapter, as set on the name property of the ChapterInfo. Chapter
Name is an automatic classification, so you'll see an extra menu level when you
view these reports.
Chapter Position
The position (index) of the chapter inside the content, as specified on the position
property of the ChapterInfo. Chapter Position is an automatic classification, so
you'll see an extra menu level when you view these reports.
Chapter Offset
The offset of the chapter inside the content (in seconds), as set on the startTime
property of the ChapterInfo. Chapter Offset is an automatic classification, so you'll
see an extra menu level when you view these reports.
Chapter Length
The length of the chapter (in seconds), as set on the length property of the
ChapterInfo. Chapter Length is an automatic classification, so you'll see an extra
menu level when you view these reports.
Chapter
The auto-generated ID of the chapter.
Chapter Events
Event
Description
Chapter Starts
The number of chapter starts. A chapter start is counted when the first frame of
the chapter has been rendered.
Chapter Completes
The number of chapter completes. A chapter complete is counted when the
trackChapterComplete() method is called.
Chapter Time Spent
The total amount of time (in seconds) spent watching the chapter.
Quality Variables and Events
Quality variables and events are standard Analytics variables that can be reported directly and added to other
Analytics reports.
• Quality Variables
• Quality Events
30
Quality Variables
Variable
Description
Time to Start
The amount of time (in seconds) taken for the video to start (from VHL 1.5 only).
This metric is computed as the time difference between the time when trackPlay
method is called and when the first frame was rendered. A custom valued could
be set for this metric using the trackSessionStart method.
Buffer Events
The number of buffer events. This metric is computed as a count of buffer events
The total amount of time (in seconds) spent buffering. This value is computed as
a sum of all buffer events durations that occurred during a playback session.
Bitrate Changes
The number of bitrate changes. This value is computed as a sum of all bitrate
change events that occurred during a playback session.
Average Bitrate
The average bitrate (in kbps). The value is predefined buckets at 100kbps intervals.
The Average Bitrate is computed as a weighted average of all bitrate values related
to the play duration that occurred during a playback session, then is included to
the appropriate bucket.
Errors
The number of errors occurred. This value is computed as a sum of all error events
Dropped Frames
The number of dropped frames. This value is computed as a sum of all frames
dropped during a playback session.
Quality Events
Event
Description
Time to Start
The amount of time (in seconds) taken for the video to start (from VHL 1.5 only).
This metric is computed as the time difference between the time when the
trackPlay method is called and when the first frame was rendered. A custom
valued could be set for this metric using the trackSessionStart method.
Drops before Start
The number of times a user quit the video before its start (from VHL 1.5 only). This
metric is set to 1 only if no content was rendered, regardless of ads.
Buffer Impacted Streams
The number of streams impacted by buffering. This metric is set to 1 only if at least
one buffer event occurred during a playback session.
31
Event
Description
Buffer Events
The number of buffer events. This metric is computed as a count of buffer events
The total amount of time (in seconds) spent buffering. This metric is computed as
a sum of all buffer event durations that occurred during a playback session.
Bitrate Change Impacted
Streams
The number of streams in which bitrate changes occurred. This metric is set to 1
only if at least one bitrate change event occurred during a playback session.
Average Bitrate
The average bitrate (in kbps). This metric is computed as a weighted average of
all bitrate values related to the play duration that occurred during a playback
session.
Bitrate Changes
The number of bitrate changes. This metric is computed as a sum of all bitrate
change events that occurred during a playback session.
Error Impacted Streams
The number of streams in which errors occurred. This metric is set to 1 only if at
least one error event occurred during a playback session.
Errors
The number of errors occurred. This metric is computed as a sum of all error
events that occurred during a playback session.
Dropped Frame Impacted
Streams
The number of streams in which frames were dropped. This metric is set to 1 only
if at least one frame was dropped during a playback session.
Dropped Frames
The number of dropped frames. This metric is computed as a sum of all frames
dropped during a playback session.
Video Heartbeat 1.5 Developer Guide
32
This section contains instructions to download the video heartbeat SDKs and developer guides for your 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
iOS
Process
See JavaScript 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.
Flash/ActionScript
See ActionScript Players.
How VideoPlayerPluginDelegate Works
Information to help you understand how the VideoPlayerPluginDelegate plugin works across JavaScript, iOS,
Android, and ActionScript players.
Note: This video player plugin delegate was previously named PlayerDelegate in version 1.4.
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 VideoPlayerPluginDelegate class
(ADB_VHB_VideoPlayerPluginDelegate on iOS) 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
VideoPlayerPluginDelegate, consider the following examples:
JavaScript VideoPlayerPluginDelegate
Examples to understand the interaction between the player event listeners, the track functions, and the
VideoPlayerPluginDelegate on JavaScript.
Event Listeners
VideoPlayerPlugin Track Functions
33
In the trackVideoPlay() JavaScript function you assigned to handle the play event, you would call
VideoPlayerPlugin.trackPlay() to let video heartbeat know that playback has started:
function trackVideoPlay() {
VideoPlayerPlugin.trackPlay();
};
Note that no video information is passed to the trackPlay().
VideoPlayerPluginDelegate
When the video heartbeat track... methods are called, your implementation of VideoPlayerPluginDelegate 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:
function SampleVideoPlayerPluginDelegate(player) {
this._player = player;
}
SampleVideoPlayerPluginDelegate.prototype.getVideoInfo = function() {
var videoInfo = new VideoInfo();
videoInfo.id = this._player.getVideoId(); // e.g. “vid123-a”
videoInfo.name = this._player.getVideoName(); // e.g. “My sample video”
videoInfo.length = this._player.getVideoLength(); // e.g. 240 seconds
videoInfo.streamType = AssetType.ASSET_TYPE_VOD;
videoInfo.playerName = this._player.getName(); // e.g. “Sample video player”
videoInfo.playhead = this._player.getCurrentPlayhead(); // e.g. 115 (obtained from the
video player)
return videoInfo;
};
SampleVideoPlayerPluginDelegate.prototype.getAdBreakInfo = function() {
return null; // no ads in this scenario
};
SampleVideoPlayerPluginDelegate.prototype.getAdInfo = function() {
};
SampleVideoPlayerPluginDelegate.prototype.getChapterInfo = function() {
return null; // no chapters in this scenario
};
SampleVideoPlayerPluginDelegate.prototype.getQoSInfo = function() {
return null; // no QoS information in this sample
};
Note: The onError callback that was part of the PlayerDelegate in version 1.4 is removed from the
VideoPlayerPluginDelegate in version 1.5.
In this example, when 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
VideoPlayerPluginDelegate and provide an instance of the extended class as a parameter to VideoPlayerPlugin
when you initialize video heartbeat.
Make sure you take a close look at the sample players to see how VideoPlayerPluginDelegate is extended.
iOS VideoPlayerPluginDelegate
VideoPlayerPluginDelegate on iOS.
34
In the trackVideoPlay function you assigned to handle the play event, you would call [videoPlayerPlugin
trackPlay] to let video heartbeat know that playback has started:
- (void)trackVideoPlay
{
[videoPlayerPlugin trackPlay];
}
Note that no video information is passed to the trackPlay.
need for you to determine exactly what information is needed by each track function, you can provide a single object
---------------------------------sample VideoPlayerPluginDelegate.h
---------------------------------@class VideoPlayer;
@interface SampleVideoPlayerPluginDelegate : ADB_VHB_VideoPlayerPluginDelegate
- (instancetype)initWithPlayer:(VideoPlayer *)player NS_DESIGNATED_INITIALIZER;
@end
---------------------------------sample VideoPlayerPluginDelegate.m
---------------------------------@interface SampleVideoPlayerPluginDelegate ()
@property(strong, nonatomic) VideoPlayer *player;
@end
@implementation SampleVideoPlayerPluginDelegate
- (instancetype)initWithPlayer:(VideoPlayer *)player {
self = [super init];
if (self) {
_player = player;
}
return self;
}
- (ADB_VHB_VideoInfo *)getVideoInfo {
ADB_VHB_VideoInfo *videoInfo = [[ADB_VHB_VideoInfo alloc] init];
videoInfo.id = self.player.videoId; // e.g. “vid123-a”
videoInfo.name = self.player.videoName; // e.g. “My sample video”
videoInfo.length = self.player.videoLength; // e.g. 240 seconds
videoInfo.streamType = ADB_VHB_AssetType.ASSET_TYPE_VOD;
videoInfo.playerName = self.player.name; // e.g. “Sample video player”
videoInfo.playhead = self.player.currentPlayhead; // e.g. 115
return videoInfo;
}
- (ADB_VHB_AdBreakInfo *)getAdBreakInfo {
return nil; // no ads in this scenario
}
- (ADB_VHB_AdInfo *)getAdInfo {
}
- (ADB_VHB_ChapterInfo *)getChapterInfo {
return nil; // no chapters in this scenario
}
- (ADB_VHB_QoSInfo *)getQoSInfo {
35
return nil; // no QoS information in this sample
}
@end
ADB_VHB_VideoPlayerPluginDelegate in version 1.5.
In this example, when [videoPlayerPlugin 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 ADB_VHB_VideoPlayerPluginDelegate and provide an instance of the extended class as a parameter
to ADB_VHB_VideoPlayerPlugin when you initialize video heartbeat.
Make sure you take a close look at the sample players to see how ADB_VHB_VideoPlayerPluginDelegate is
extended.
Android VideoPlayerPluginDelegate
VideoPlayerPluginDelegate on Android.
In the trackVideoPlay() Java function you assigned to handle the play event, you would call vpPlayer.trackPlay()
to let video heartbeat know that playback has started:
private void trackVideoPlay() {
vpPlugin.trackPlay();
};
public class SampleVideoPlayerPluginDelegate extends VideoPlayerPluginDelegate {
VideoPlayerDelegate(VideoPlayer player) {
_player = player;
}
@Override
public VideoInfo getVideoInfo() {
VideoInfo videoInfo = new VideoInfo();
videoInfo.id = _player.getVideoId(); // e.g. “vid123-a”
videoInfo.name = _player.getVideoName(); // e.g. “My sample video”
videoInfo.length = _player.getVideoLength(); // e.g. 240 seconds
videoInfo.playerName = _player.getName(); // e.g. “Sample video player”
videoInfo.playhead = _player.getCurrentPlayhead(); // e.g. 115
return videoInfo;
}
@Override
public AdBreakInfo getAdBreakInfo() {
}
@Override
public AdInfo getAdInfo() {
36
}
@Override
public ChapterInfo getChapterInfo() {
}
@Override
public QoSInfo getQoSInfo() {
}
private final VideoPlayer _player;
}
ActionScript VideoPlayerPluginDelegate
VideoPlayerPluginDelegate on ActionScript.
function trackVideoPlay() {
VideoPlayerPlugin.trackPlay();
};
public function SampleVideoPlayerPluginDelegate(player:VideoPlayer) {
_player = player;
}
override public function get videoInfo():VideoInfo {
var videoInfo:VideoInfo = new VideoInfo();
videoInfo.id = _player.videoId; // e.g. “vid123-a”
videoInfo.name = _player.videoName; // e.g. “My sample video”
videoInfo.length = _player.videoLength; // e.g. 240 seconds
videoInfo.playerName = _player.name; // e.g. “Sample video player”
videoInfo.playhead = _player.currentPlayhead; // e.g. 115
return videoInfo;
}
37
override public function get adBreakInfo():AdBreakInfo {
}
override public function get adInfo():AdInfo {
}
override public function get chapterInfo():ChapterInfo {
}
override public function get qosInfo():QoSInfo {
}
private var _player:VideoPlayer;
}
Video Measurement Parameters
List of data-collection parameters sent by video heartbeat.
• Video Core Parameters
• Video Ad Parameters
• Video Chapter Parameters
• Video Quality Parameters
• Other Parameters
Video Core Parameters
Label
Required? Variable Type Context Data Variable
Clickstream/API
Variable Name
Sent With
Video Name
No
classification
a.media.friendlyName
N/A
Video Start
Video Length
Yes
classification
a.media.length
N/A
Video Start
Content
Yes
eVar
a.media.name
video
Video Start
Content
Segment
Yes
eVar
a.media.segment
videosegment
Heartbeat
Content Type
Yes
eVar
a.contentType
videocontenttype
Video Start
38
Label
Clickstream/API
Variable Name
Sent With
Content
Player Name
Yes
eVar
a.media.playerName
videoplayername
Video Start
Content
Channel
No
eVar
a.media.channel
videochannel
Video Start
Video Initiates Yes
event
a.media.view
videostart
Video Start
Content Starts No
event
a.media.play
videoplay
Heartbeat
Content
Completes
No
event
a.media.complete
videocomplete
Heartbeat
Content
Segment
Views
Yes
event
a.media.segmentView
videosegmentviews
Heartbeat
Content Time Yes
Spent
event
a.media.timePlayed
videotime
Heartbeat
Video Time
Spent
event
a.media.totalTimePlayed
videototaltime
Heartbeat
10% Progress No
Marker
event
a.media.progress10
videoprogress10
Heartbeat
25% Progress No
Marker
event
a.media.progress25
videoprogress25
Heartbeat
50% Progress No
Marker
event
a.media.progress50
videoprogress50
Heartbeat
75% Progress No
Marker
event
a.media.progress75
videoprogress75
Heartbeat
95% Progress No
Marker
event
a.media.progress95
videoprogress95
Heartbeat
Average
Minute
Audience
No
event
a.media.averageMinuteAudience videoaverageminuteaudience Heartbeat
Video Path
Yes
prop
a.media.name
videopath
Video Start
Paused
Impacted
Streams
No
event
a.media.pause
videopause
Heartbeat
Pause Events No
event
a.media.pauseCount
videopausecount
Heartbeat
Total Pause
Duration
event
a.media.pauseTime
videopausetime
Heartbeat
Yes
No
39
Label
Clickstream/API
Variable Name
Sent With
Content
Resumes
No
videoresume
Heartbeat
event
a.media.resume
Video Ad Parameters
Label
Clickstream/API
Variable Name
Sent With
Ad Name
No
classification
a.media.ad.friendlyName
N/A
Ad Start
Ad Length
Yes
classification
a.media.ad.length
N/A
Ad Start
Ad
Yes
eVar
a.media.ad.name
videoad
Ad Start
Pod Name
No
classification
a.media.ad.podFriendlyName N/A
Ad Start
Pod Position
Yes
classification
a.media.ad.podSecond
N/A
Ad Start
Ad Pod
Yes
eVar
a.media.ad.pod
videoadpod
Ad Start
Ad in Pod
Position
Yes
eVar
a.media.ad.podPosition
videoadinpod
Ad Start
Ad Player
Name
Yes
eVar
a.media.ad.playerName
videoplayername
Ad Start
Ad Starts
Yes
event
a.media.ad.view
videostart
Ad Start
Ad Completes Yes
event
a.media.ad.complete
videocomplete
Heartbeat
Ad Time
Spent
event
a.media.ad.timePlayed
videoadtime
Heartbeat
Clickstream/API
Variable Name
Sent With
Yes
Video Chapter Parameters
Label
Chapter
Name
No
classification
a.media.chapter.friendlyName N/A
Heartbeat
Chapter
Position
Yes
classification
a.media.chapter.position
N/A
Heartbeat
Chapter
Offset
No
classification
a.media.chapter.offset
N/A
Heartbeat
Chapter
Length
No
classification
a.media.chapter.length
N/A
Heartbeat
Chapter
Yes
eVar
a.media.chapter.name
videochapter
Heartbeat
40
Label
Clickstream/API
Variable Name
Sent With
Chapter
Starts
Yes
event
a.media.chapter.view
videochapterstart
Heartbeat
Chapter
Completes
No
event
a.media.chapter.complete
videochaptercomplete
Heartbeat
event
a.media.chapter.timePlayed videochaptertime
Chapter Time Yes
Spent
Heartbeat
Video Quality Parameters
Label
Time to Start No
eVar
a.media.qoe.timeToStart
event
eVar
Clickstream/API
Variable Name
Sent With
videoqoetimetostartevar Heartbeat
videoqoetimetostart
Buffer
Events
No
Total Buffer
Duration
No
Bitrate
Changes
No
Average
Bitrate
No
eVar
a.media.qoe.bitrateAverageBucket videoqoebitrateaverageevar Heartbeat
Errors / Error No
Events
eVar
a.media.qoe.errorCount
Dropped
Frames
eVar
a.media.qoe.bufferCount
event
eVar
videoqoebuffercount
a.media.qoe.bufferTime
event
eVar
videoqoebuffertimeevar Heartbeat
videoqoebuffertime
a.media.qoe.bitrateChangeCount videoqoebitratechangecountevar Heartbeat
event
No
videoqoebuffercountevar Heartbeat
videoqoebitratechangecount
event
videoqoeerrorcountevar Heartbeat
videoqoeerrorcount
a.media.qoe.droppedFrameCount videoqoedroppedframecountevar Heartbeat
event
videoqoedroppedframecount
Drops before No
Start
event
a.media.qoe.dropBeforeStart videoqoedropbeforestart Heartbeat
Buffer
Impacted
Streams
No
event
a.media.qoe.buffer
videoqoebuffer
Bitrate
Change
Impacted
Streams
No
event
a.media.qoe.bitrateChange
videoqoebitratechange Heartbeat
Heartbeat
41
Label
Clickstream/API
Variable Name
Sent With
Average
Bitrate
No
event
a.media.qoe.bitrateAverage videoqoebitrateaverage Heartbeat
Error
Impacted
Streams
No
event
a.media.qoe.error
videoqoeerror
Dropped
Frame
Impacted
Streams
No
event
a.media.qoe.droppedFrames
videoqoedroppedframes Heartbeat
Heartbeat
Other Parameters
Label
Required?
Variable Type Context Data Variable
Clickstream/API
Variable Name
Sent With
SDK
Version
No
N/A*
a.media.sdkVersion
N/A
Heartbeat
VHL Version No
N/A*
a.media.vhlVersion
N/A
Heartbeat
Stalling
Impacted
Streams
No
N/A*
a.media.qoe.stall
N/A
Heartbeat
Stalling
Events
No
N/A*
a.media.qoe.stallCount
N/A
Heartbeat
Total
Stalling
Duration
No
N/A*
a.media.qoe.stallTime
N/A
Heartbeat
* You must create your own processing rule if you want to use this parameter.
Standard Metadata Parameters
List of data-collection parameters sent by video heartbeat.
Important: This feature is valid only on Mobile and JavaScript platforms.
This section contains the following:
• Video metadata
• Ad metadata
42
Video metadata
Name
Context data key
Show
a.media.show
Season
a.media.season
Episode
a.media.episode
Asset ID
a.media.asset
Description
Data type: String
Data type: String
Data type: String
This is the TMS_ID, an industry
standard ID to identify a piece of
TV/video content. TMS = Tribune
Media Service, which is now
known as Gracenote.
Metadata key name
SHOW
SEASON
EPISODE
ASSET_ID
Data type: String
Genre
a.media.genre
First air date
a.media.airDate
Data type: String
Original TV air date of the asset.
GENRE
FIRST_AIR_DATE
Data type: String
First Digital Date
a.media.digitalDate
First date when this video asset
was available on Digital.
FIRST_DIGITAL_DATA
Data type: String
Content Rating
a.media.rating
Originator
a.media.originator
Network
a.media.network
Show type
a.media.type
Ad Loads
a.media.adLoad
MVPD
a.media.pass.mvpd
Authorized
a.media.pass.auth
Day Part
a.media.dayPart
Feed Type
a.media.feed
Data type: String
Data type: String
Data type: String
Data type: String
Data type: String
Data type: String
Data type: String
Data type: String
This determines the type of feed.
For example, for living
RATING
ORIGINATOR
NETWORK
SHOW_TYPE
AD_LOAD
MVPD
AUTHORIZED
DAY_PART
FEED
Name
43
Context data key
Description
Metadata key name
programming, the feed types are
East HD or West HD.
Data type: String
Stream Format
a.media.format
Clip Classification. If the content
is a full episode, pass a value of
1; otherwise pass a value of 0. The
default value is 0.
STREAM_FORMAT
Data type: String
Ad metadata
Property name
Context data key
Advertiser
a.media.ad.advertiser
Description
The company or brand whose
product is featured in the ad.
Metadata key name
ADVERTISER
Data Type: String
Campaign ID
a.media.ad.campaign
Client paramaters.
CAMPAIGN_ID
Data Type: String
Creative ID
a.media.ad.creative
Client paramaters.
CREATIVE_ID
Data Type: String
Placement ID
a.media.ad.placement
Client paramaters.
PLACEMENT_ID
Data Type: String
Site ID
a.media.ad.site
Client paramaters.
SITE_ID
Data Type: String
Creative URL
a.media.ad.creativeURL
The URL of the creative or ad that
is being delivered.
CREATIVE_URL
Data Type: String
Track Methods and Player Events
Information about the correspondence between player events and the associated call exposed by the public API of
the video heartbeat library.
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
44
correspondence between player events and the associated call exposed by the public API of the video heartbeat
library.
• Video Playback
• Rules and Practices
• Ad Playback
• Chapter Tracking
• QoS Tracking
• Error Tracking
Video Playback
Event
Method Call
Parameter List
Load the main video asset
trackVideoLoad()
None
Unload the main video asset
trackVideoUnload()
None
Autoplay ON, or user clicks play
trackSessionStart()
None
Playback start
trackPlay()
None
Playback stop/pause
trackPause()
None
Playback complete
trackComplete()
None
Seek start
trackSeekStart()
None
Seek complete
trackSeekComplete()
None
Buffer start
trackBufferStart()
None
Buffer complete
trackBufferComplete()
None
Rules and Practices
• Methods to be called in pairs:
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())
• trackAdStart() and trackAdComplete() (unless the user seeks out of the ad without playing it to completion)
• trackChapterStart() and trackChapterComplete() (unless the user seeks out of the chapter without playing
it to completion)
The track...Start() call is 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).
45
trackSeekComplete(); // Signals that the second seek operation has completed.
trackPlay(); // Signals that the user resumed playback.
• Tracking the completion of content:
The trackComplete() method is used to signal the completion of the video (i.e., the content was played to the
end). You should call trackComplete() before calling trackVideoUnload() if the video was completed. When
the user quits the video before its completion (e.g., by switching to another video in a playlist), you should not call
trackComplete(). Instead, you should simply close the tracking session by calling trackVideoUnload().
Ad Playback
Event
Method Call
Parameter List
An ad starts
trackAdStart()
None
An ad completes
trackAdComplete()
None
The trackAdStart() and trackAdComplete() methods are the only track methods required in order to signal the
beginning and completion of an ad.
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 by the VideoPlayerPlugin when you call trackAdStart().
Chapter Tracking
Event
Method Call
Parameter List
A new chapter starts
trackChapterStart()
None
A chapter completes
trackChapterComplete()
None
Event
Method Call
Parameter List
A switch to another bitrate occurs
trackBitrateChange()
None
Event
Method Call
Parameter List
An error occurs at the player level
trackVideoPlayerError()
String errorId - unique error
QoS Tracking
Error Tracking
identifier
An error occurs at the application
level
trackApplicationError()
Video Measurement Timeline
This topic provides a scenario to illustrate when video data is collected.
String errorId
46
Scenario and Timeline Illustrations
This topic describes a scenario to illustrate when video data is collected and contains illustrations to show the video
and actions timelines.
• Scenario Overview
• Video Timeline
• Actions Timeline
Scenario Overview
A video (VOD) is loaded and played into a web page or application that has the following components:
Component
Playback content
Details
Main content of 80 seconds split in two chapters.
• Chapter 1 - chapter duration: 40 seconds
• Chapter 2 - chapter duration: 40 seconds
Three ad breaks:
• One pre-roll before first chapter that contains two ads:
• AD 1 - ad duration: 20 seconds
• One mid-roll between chapters that contains one ad:
• One post-roll at the end of the content that contains one ad:
User interactions
• Start the content after it is loaded.
• Skip back 15 seconds of content inside Chapter 1 at second 35.
• Pause the main content for 45 seconds during Chapter 2.
Playback events
• Buffering on start for 15 seconds.
• Player error occurs during Chapter 1 at second 37.
• Re-buffering for 15 seconds during Chapter 2 at second 60.
• Bitrate changed during Chapter 2 at second 75.
47
Video Timeline
Actions Timeline
Tracking Explained
This topic describes when video data is collected and contains information about the actions a user takes along with
video heartbeat Library methods used, Analytics and video heartbeat library calls made, and implementation details.
See Scenario and Timeline Illustrations to view illustrations depicting the processes explained below.
The scenario illustrated in the following table is a typical end-to-end playback where there is little interaction and
content is played to the end.
48
Note: VideoPlayerPluginDelegate must provide the most up-to-date information it has when queried:
VideoInfo (including playhead), AdBreakInfo, AdInfo, ChapterInfo, and QoSInfo.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
1
0
0
Actions:
Auto-play or Play button pressed
Video Heartbeat Library:
trackVideoLoad
trackSessionStart
Analytics Tracking Calls:
SC Video Start Call
Video Heartbeat Tracking Calls:
HB start event
HB AA start event
Implementation Details:
• Start the tracking library internal session by calling trackVideoLoad
• Set VideoInfo before any tracking method is called
• Start tracking the startup time by calling trackSessionStart
method
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
2
10
0
Actions:
N/A
N/A
N/A
Action #
Actions
Timeline
(seconds)
49
Main Content
Timeline
(seconds)
HB start event
This call is sent because the app takes longer than 10 seconds to
start the stream (long buffering scenario).
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
3
15
0
Actions:
Ad start (AD1)
trackAdStart
trackPlay
SC Ad Start Call
HB start event
HB ad start event
HB AA ad start event
HB play event
• Set AdBreakInfo before the trackAdStart method is called for
the first ad on the current ad break (pre-roll).
• Set AdBreakInfo.position to 1 because the first ad break is
inside the current main content.
• Set AdBreakInfo.startTime to 0. The startTime is the offset
in the main content (in seconds) where the ad break starts. This
can also be seen as the value of the playhead when the ad break
is reached.
• Set AdInfo for AD 1 before the trackAdStart method is called.
Action #
Actions
Timeline
(seconds)
50
Main Content
Timeline
(seconds)
• Set AdInfo.position to 1 for AD 1 because the first ad is inside
the current ad break.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
4
25
0
Actions:
N/A
N/A
N/A
HB ad play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
5
35
0
Actions:
Ad complete (AD1)
Ad start (AD2)
trackAdComplete
trackAdStart
SC Ad Start Call
Action #
Actions
Timeline
(seconds)
51
Main Content
Timeline
(seconds)
HB ad play event
HB ad complete event
HB ad start event
• Set AdInfo to NULL for AD 1 after the trackAdComplete method
is called.
• Set AdInfo.position to 2 for AD 2 because the second ad is
inside current ad break.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
6
45
0
Actions:
N/A
N/A
N/A
HB ad play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
7
50
0
Actions:
Ad complete (AD2)
Action #
Actions
Timeline
(seconds)
52
Main Content
Timeline
(seconds)
trackAdComplete
trackChapterStart
N/A
HB ad play event
HB chapter start event
HB play event
is called.
• Set AdBreakInfo to Null for the current ad break (pre-roll) after the
trackAdComplete method is called.
• Set ChapterInfo for Chapter 1 before the trackChapterStart
method is called.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
8
60
10
Actions:
N/A
N/A
N/A
HB play event
Action #
Actions
Timeline
(seconds)
53
Main Content
Timeline
(seconds)
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
9
70
20
Actions:
N/A
N/A
N/A
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
10
80
30
Actions:
N/A
N/A
N/A
HB play event
Action #
Actions
Timeline
(seconds)
54
Main Content
Timeline
(seconds)
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
11
85
35
Actions:
Seek Back 15"
trackSeekStart
N/A
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
12
85
20
Actions:
N/A
trackSeekComplete
N/A
HB play event
Action #
Actions
Timeline
(seconds)
55
Main Content
Timeline
(seconds)
Make sure VideoPlayerPluginDelegate will report the new
playhead (20) after trackSeekComplete is called.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
13
95
30
Actions:
N/A
N/A
N/A
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
14
102
37
Actions:
Player error occurred
trackError
N/A
HB error event
Action #
Actions
Timeline
(seconds)
56
Main Content
Timeline
(seconds)
• Set error type and message on trackError method.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
15
105
40
Actions:
Ad start (AD3)
trackChapterComplete
trackAdStart
SC Ad Start Call
HB play event
HB chapter complete event
HB ad start event
• Set ChapterInfo to NULL for Chapter 1 after the
trackChapterComplete method is called.
the first ad on the current ad break (mid-roll).
• Set AdBreakInfo.position to 2 because the second ad break
is inside the current main content.
is reached.
• set AdInfo for AD 3 before the trackAdStart method is called.
the current ad break.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
16
115
40
57
Actions:
Ad complete (AD3)
trackAdComplete
trackChapterStart
N/A
HB ad play event
HB chapter start event
HB play event
is called.
• Set AdBreakInfo to Null for the current ad break (mid-roll) after
the trackAdComplete method is called.
• Set ChapterInfo for Chapter 2 before the trackChapterStart
method is called.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
17
120
45
Actions:
Pause button is pressed
trackPause
N/A
Action #
Actions
Timeline
(seconds)
58
Main Content
Timeline
(seconds)
HB play event
HB pause event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
18
135
45
Actions:
Play button is pressed after 15"
trackPlay
N/A
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
19
145
55
Actions:
N/A
N/A
N/A
Action #
Actions
Timeline
(seconds)
59
Main Content
Timeline
(seconds)
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
20
150
60
Actions:
Buffer start event occurred
trackBufferStart
N/A
HB play event
HB buffer event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
21
160
60
Actions:
N/A
N/A
N/A
Action #
Actions
Timeline
(seconds)
60
Main Content
Timeline
(seconds)
HB buffer event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
22
165
60
Actions:
Buffer end event occurred after 15"
trackBufferComplete
N/A
HB buffer event
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
23
175
70
Actions:
N/A
N/A
N/A
Action #
Actions
Timeline
(seconds)
61
Main Content
Timeline
(seconds)
HB play event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
24
180
75
Actions:
Bitrate change occurred
trackBitrateChange
N/A
HB bitrate change event
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
25
185
80
Actions:
Ad start (AD4)
trackChapterComplete
trackAdStart
SC Ad Start Call
Action #
Actions
Timeline
(seconds)
62
Main Content
Timeline
(seconds)
HB play event
HB chapter complete event
HB ad start event
• Set ChapterInfo to NULL for Chapter 2 after the
trackChapterComplete method is called.
the first ad on the current ad break (post-roll).
• Set AdBreakInfo.position to 3 because the third ad break is
inside the current main content.
is reached.
current ad break.
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
26
195
80
Actions:
N/A
N/A
N/A
HB play event
Action #
Actions
Timeline
(seconds)
63
Main Content
Timeline
(seconds)
N/A
Action #
Actions
Timeline
(seconds)
Main Content
Timeline
(seconds)
27
200
80
Actions:
Ad complete (AD4)
trackAdComplete
trackComplete
trackUnload
N/A
HB play event
HB complete event
is called.
• Set AdBreakInfo to Null for the current ad break (post-roll) after
the trackAdComplete method is called.
• Close the main content by calling trackComplete.
• Close the tracking library internal session by calling trackUnload.
• Destroy the heartbeat library instance calling the destroy method.
Non-Linear Tracking Scenarios
This topic describes when video data is collected in non-linear scenarios and contains information about the actions
a user takes along with video heartbeat Library methods used, Analytics and video heartbeat library calls made,
and implementation details.
64
The scenario illustrated in Tracking Explained is a typical end-to-end playback where there is little interaction and
content is played to the end.
The following table illustrates tracking scenarios where the user seeks around more or drops from the stream.
Use Case
Scenario
Video Heartbeat Library
Implementation Details
Skip to next video
• playlist of videos, no
ads, no chapters
• trackVideoLoad
You can reuse one VHL instance
but make sure to call
trackVideoUnload/trackVideoLoad
and update the player delegate
videoInfo between the two
clips.
• trackSessionStart
(optional)
• trackPlay
User clicks Next.
• trackVideoUnload
• ...
• trackVideoLoad
• ...
Chapter seek
• one video content
• trackVideoLoad
• 3 chapters
• trackSessionStart
(optional)
• seek from chapter 1 to
chapter 3
• tracktrackChapterStart
User seeks forward.
• trackSeekStart
• trackSeekComplete
When the user starts seeking,
wait until it completes then call
trackChapterStart with the
new chapter info. You should
NOT call
trackChapterComplete on the
source chapter, because it was
not seen through the end.
• tracktrackChapterStart
• tracktrackChapterComplete
• trackComplete
• trackVideoUnload
• destroy
Pause tracking
The Pause tracking support was added on VHL 1.6. In the same time the buffer and pause behaviors have been
unified in order to have the same way of tracking and same metrics. VHL will send a new pause Video Heartbeat
event at each 10 seconds during pause and will stop after 30 minutes, at this point the session will be closed. If the
playback is resumed after 30 minutes of pause, VHL will automatically create a new tracking session and send a
resume event.
For the implementation that are not passing to VHL all information about the player state, a new artificial tracking
event was build called "stall" in order to define a state of the player that VHL does not know about. One simple
example is when the player is in buffer mode, the playhead has same value during that period but the VHL was not
informed due to the fact that the player is not exposing the event or just because the buffer event was not properly
instrumented. The stalling event is tracked in the same way as paused.
Pause duration less than 30 minutes
In this scenario, complete the following tasks:
1. Start playback for a content that is 10 minutes long.
2. Pause the playback after 3 minutes.
3. Resume the content after 20 minutes and play the content until the end.
Expected events
• An Analytics video initiate event after the session starts.
• A video heartbeats start event after the session starts.
• video heartbeats play events every 10 seconds until the session is paused.
• video heartbeats pause events every 10 seconds while the session is paused.
• video heartbeats play events every 10 seconds after pause;
• A video heartbeats complete event when the playback is complete.
• A complete video call sent to Analytics when a session has ended.
Add pause metrics to analytics: has paused and number of pauses.
Expected metrics
• 1 content start and 10 minutes of total time spent.
• All video solution events + has pause event, 1 pause event count.
Abandon during pause
1. Start playback for a content that is 10 minutes long.
2. Pause the playback after 3 minutes;
3. Close the content after 10 minutes.
65
Expected results
• An Analytics video initiate event when the session starts.
• A video heartbeats start event when the session starts.
• video heartbeats play events every 10 seconds until the session is paused.
• video heartbeats pause events every 10 seconds during the pause.
• A close video call sent to Analytics when a session has ended.
Pause duration more than 30 minutes
1. start playback for a content that is 10 minutes long.
2. pause the playback after 3 minutes.
3. resume the content after 40 minutes and play the content to the end.
Expected events
• An Analytics video initiate event after the session starts.
• A video heartbeats start event when the session starts.
• Video heartbeats play events every 10 seconds until the content is paused.
• Video heartbeats pause events every 10 seconds during pause for 30 minutes.
• A close video call sent to Analytics once a session has ended.
• No video heartbeats event for 10 minutes until playback resumes.
66
67
• An Analytics video initiate event after a new tracking session starts after the playback resumes (including a
new SID).
• A video heartbeats start event after the session starts (playback resumes).
• A video heartbeats resume event after the session starts (playback resumes).
• Video heartbeats play events every 10 seconds.
• A video heartbeats complete event after the playback is complete.
• A complete video call sent to Analytics after a session has ended.
Add resume metric to analytics: has resume.
Expected metrics
• 1 content starts and 3 minutes of total time spent.
• All video solution events + has pause event, and 1 pause event count.
• 1 content starts and 7 minutes of total time spent.
• All video solution events + has resume event.
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.
This section was last updated 06/18/2015.
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 measurement 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 library 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.
• Video heartbeat library. (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.
68
Example Implementations
An example is available in the samples folder that is included with the video heartbeat library.
Implementation Process
Complete the following steps to add video heartbeat tracking to your player:
Download the Video Heartbeat Library - JS
The video heartbeat library 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. Save the samples folder to a location where the sample project can be reviewed and tested.
Next step: Configure AppMeasurement
Implement VideoPlayerPluginDelegate - JS
The VideoPlayerPluginDelegate is used by video heartbeat to get information about the currently playing video, ad,
and chapter.
First, read How VideoPlayerPluginDelegate Works to understand the role of VideoPlayerPluginDelegate in video
heartbeat. Implementing this interface is where you will typically spend a majority of your implementation time.
To get started creating your own VideoPlayerPluginDelegate implementation, create a new object that uses
ADB.va.VideoPlayerPluginDelegate as the object prototype:
var myDelegate = new VideoPlayerPluginDelegate();
Now that you have a player delegate, you need to define the functions that return information about your video and
player:
function VideoPlayerPluginDelegate() {}
VideoPlayerPluginDelegate.prototype.getVideoInfo = function() {};
VideoPlayerPluginDelegate.prototype.getAdBreakInfo = function() {};
VideoPlayerPluginDelegate.prototype.getAdInfo = function() {};
VideoPlayerPluginDelegate.prototype.getChapterInfo = function() {};
VideoPlayerPluginDelegate.prototype.getQoSInfo = function() {};
With that framework in place, the following sections explain how to update these methods to return useful data from
your player:
• Video Information
• Ad Break Information
• Ad Information
• Chapter Information
• Example
69
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:
Parameter
Required?
Description
playerName
Yes
The name of the video player that is playing back the main content.
id
Yes
The ID of the video asset.
name
No
The name of the video asset (opaque string value).
length
Yes
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.
playhead
Yes
The current playhead location (in seconds) inside the video asset (excluding
ad content) at the moment this method was called.
streamType
Yes
The type of the video asset.
resumed
No
Set to true if this is a resumed video playback session (for example, when
playback of VOD content starts from where the user previously left it).
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
Required?
Description
playerName
Yes
The name of the video player responsible with playing back the current
advertisement break.
name
No
The name of the ad-break.
position
Yes
The position (index) of the pod inside the main content (starting with 1).
startTime
No
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.
70
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
Required?
Description
id
Yes
The ID of the ad asset.
length
Yes
The duration (in seconds) of the ad asset.
position
Yes
The position (index) of the ad inside the parent ad-break (starting with 1).
name
No
The name of the ad asset (opaque string value).
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
Required?
Description
name
No
The name of the chapter (opaque string value).
length
Yes
The duration (in seconds) of the chapter.
position
Yes
The position of the chapter inside the main content (starting from 1).
startTime
Yes
The offset inside the main content where the chapter starts.
Update the getChapterInfo method to retrieve properties or call the required APIs.
Example
The following is an example of a valid video player plugin delegate:
}
71
video player)
return videoInfo;
};
};
};
};
};
Next step: Configure the Video Heartbeat Library
Attaching Custom Metadata
You can attach your own metadata to calls made to Adobe Analytics.
The video heartbeat library provides support for custom metadata to be attached to the analytics calls. The relevant
APIs for this functionality are defined on the AdobeAnalyticsPlugin:
AdobeAnalyticsPlugin.prototype.setVideoMetadata = function(data) {};
AdobeAnalyticsPlugin.prototype.setAdMetadata = function(data) {};
AdobeAnalyticsPlugin.prototype.setChapterMetadata = function(data) {};
The integration code may call these methods on the AdobeAnalyticsPlugin to set custom metadata for the video,
the ad and/or the chapter. The metadata for the video will be automatically associated with the ads and chapters.
You need to set the metadata before calling the relevant track...() method on the VideoPlayerPlugin by
completing the following tasks:
• Set the video metadata before calling trackVideoLoad()
• Set the ad metadata before calling trackAdStart()
• Set the chapter metadata before calling trackChapterStart()
This will ensure that the metadata is taken into consideration by the video heartbeat library when processing the
track...() call.
72
The code snippet below illustrates how to set custom metadata for video, ads and chapters:
// Before calling trackVideoLoad():
adobeAnalyticsPlugin.setVideoMetadata({
isUserLoggedIn: "false",
tvStation: "Sample TV station",
programmer: "Sample programmer"
});
// [...]
// Before calling trackAdStart():
adobeAnalyticsPlugin.setAdMetadata({
affiliate: "Sample affiliate",
campaign: "Sample ad campaign"
});
// [...]
// Before calling trackChapterStart():
adobeAnalyticsPlugin.setChapterMetadata({
segmentType: "Sample segment type"
});
Note: Clearing the custom metadata - The custom metadata set on the AdobeAnalyticsPlugin is persistent.
It is not reset automatically by the video heartbeat library. To clear the custom metadata, you can pass NULL
as the input argument for each of the set...Metadata() methods. For example, you should do this for ads
and chapters once they are complete. Otherwise, the custom metadata will be applied to subsequent ads /
chapters. It is your responsibility to ensure that the appropriate metadata is set before the trackVideoLoad()
/ trackAdStart() / trackChapterStart() call.
Standard metadata keys for JavaScript
Here are the standard metadata keys for JavaScript:
ADB.va.plugins.aa.VideoMetadataKeys = {
SHOW,
SEASON,
EPISODE,
ASSET_ID,
GENRE,
FIRST_AIR_DATE,
FIRST_DIGITAL_DATE,
RATING,
ORIGINATOR,
NETWORK,
SHOW_TYPE,
AD_LOAD,
MVPD,
AUTHORIZED,
DAY_PART,
FEED,
STREAM_FORMAT
};
ADB.va.plugins.aa.AdMetadataKeys = {
ADVERTISER,
CAMPAIGN_ID,
CREATIVE_ID,
PLACEMENT_ID,
SITE_ID,
CREATIVE_URL
};
73
Sample implementation on JavaScript
Here is a sample implementation on JavaScript.
To set standard metadata or partner metadata information, the application must use context metadata APIs and set
the expected key-value pair by using one of the following APIs on AdobeAnalyticsPlugin:
• setVideoMetadata - for setting video metadata
• setAdMetadata - for setting ad metadata
To attach custom metadata and standard metadata keys, see the following information:
• Attaching Custom Metadata
• Standard metadata keys for JavaScript
Tip: The class that implements Video Analytics is VideoAnalyticsProvider.
// import Standard Metadata namespace
var VideoMetadataKeys = ADB.va.plugins.aa.VideoMetadataKeys;
var AdMetadataKeys = ADB.va.plugins.aa.AdMetadataKeys;
// setting Standard Video Metadata
var contextData = {};
contextData[VideoMetadataKeys.SEASON] = "sample season";
contextData[VideoMetadataKeys.SHOW] = "sample show";
contextData[VideoMetadataKeys.EPISODE] = "sample episode";
contextData[VideoMetadataKeys.ASSET_ID] = "sample asset id";
contextData[VideoMetadataKeys.GENRE] = "sample genre";
contextData[VideoMetadataKeys.FIRST_AIR_DATE] = "sample air date";
contextData[VideoMetadataKeys.FIRST_DIGITAL_DATE] = "sample digital date";
contextData[VideoMetadataKeys.RATING] = "sample rating";
contextData[VideoMetadataKeys.ORIGINATOR] = "sample originator";
contextData[VideoMetadataKeys.NETWORK] = "sample network";
contextData[VideoMetadataKeys.SHOW_TYPE] = "sample show type";
contextData[VideoMetadataKeys.AD_LOAD] = "sample ad load";
contextData[VideoMetadataKeys.MVPD] = "sample mvpd";
contextData[VideoMetadataKeys.AUTHORIZED] = "true";
contextData[VideoMetadataKeys.DAY_PART] = "sample day part";
contextData[VideoMetadataKeys.FEED] = "sample feed";
contextData[VideoMetadataKeys.STREAM_FORMAT] = "sample format";
// setting Standard Ad Metadata
var contextData = {};
contextData[AdMetadataKeys.ADVERTISER] = "sample advertiser";
contextData[AdMetadataKeys.CAMPAIGN_ID] = "sample campaign";
contextData[AdMetadataKeys.CREATIVE_ID] = "sample creative";
contextData[AdMetadataKeys.CREATIVE_URL] = "sample url";
contextData[AdMetadataKeys.SITE_ID] = "sample site";
contextData[AdMetadataKeys.PLACEMENT_ID] = "sample placement";
this._aaPlugin.setAdMetadata(contextData);
Configure the Video Heartbeat Library
You can configure each of the video heartbeat library components on an individual basis.
After you Implement VideoPlayerPluginDelegate, you are ready to add the video heartbeat code to your project.
Before you proceed, make sure you have the following:
• An instance of your custom VideoPlayerPluginDelegate object.
• A properly configured ADBMobileConfig.json file.
For more information, see Configure AppMeasurement.
• Your Marketing Cloud Org ID or Publisher ID (assigned by Adobe).
74
Note: Existing customers using the Publisher ID can continue using it, but we recommend that you start
using your Marketing Cloud Org ID instead. Contact Adobe Customer Care to obtain a Marketing Cloud Org
ID.
On each HTML page where you are tracking video, add a <script> tag with a reference to
VideoHeartbeat.min.js:
<script src="VideoHeartbeat.min.js"></script>
The following code sample illustrates how to instantiate and configure the video heartbeat components:
// Video Player plugin
var vpPluginDelegate = new CustomVideoPlayerPluginDelegate(<my-player>);
var vpPlugin = new VideoPlayerPlugin(vpPluginDelegate);
var vpPluginConfig = new VideoPlayerPluginConfig();
vpPluginConfig.debugLogging = true; // set this to false for production apps.
vpPlugin.configure(vpPluginConfig);
// Adobe Analytics plugin
var aaPluginDelegate = new CustomAdobeAnalyticsPluginDelegate();
var aaPlugin = new AdobeAnalyticsPlugin(appMeasurement, aaPluginDelegate);
var aaPluginConfig = new AdobeAnalyticsPluginConfig();
aaPluginConfig.channel = <syndication-channel>;
aaPluginConfig.debugLogging = true; // set this to false for production apps.
aaPlugin.configure(aaPluginConfig);
// Adobe Heartbeat plugin
var ahPluginDelegate = new CustomAdobeHeartbeatPluginDelegate();
var ahPlugin = new AdobeHeartbeatPlugin(ahPluginDelegate);
var ahPluginConfig = new AdobeHeartbeatPluginConfig(<tracking-server>, <publisher>);
ahPluginConfig.ovp = <online-video-platform-name>;
ahPluginConfig.sdk = <player-SDK-version>;
ahPluginConfig.debugLogging = true; // set this to false for production apps.
ahPluginConfig.ssl = false; // set this to true to enable Heartbeat calls through HTTPS
ahPlugin.configure(ahPluginConfig);
// Heartbeat
var plugins = [vpPlugin, aaPlugin, ahPlugin];
var heartbeatDelegate = new CustomHeartbeatDelegate();
var heartbeat = new Heartbeat(heartbeatDelegate, plugins);
var heartbeatConfig = new HeartbeatConfig();
heartbeatConfig.debugLogging = true; // set this to false for production apps.
heartbeat.configure(heartbeatConfig);
The configuration of each of the video heartbeat components follows the builder pattern:
• A configuration object is built
• The configuration object is passed as a parameter to the configure method of the component
The list below describes all the configuration parameters:
• VideoPlayerPlugin
• debugLogging: activates logging inside this plugin. Optional. Default value: false
• AdobeAnalyticsPlugin
• channel: the name of the syndication channel. Optional. Default value: the empty string
• AdobeHeartbeatPlugin
• trackingServer: the server to which all the heartbeat calls are sent. Mandatory. Use the value provided by your
Adobe consultant.
75
• publisher: the name of the publisher. Mandatory. Use the value provided by your Adobe consultant.
• ssl: Indicates whether the heartbeat calls should be made over HTTPS. Optional. Default value: false
• ovp: the name of the online video platform through which content gets distributed. Optional. Default value:
"unknown"
• sdk: the version of the video player app/SDK. Optional. Default value: "unknown"
• quietMode: activates the "quiet" mode of operation, in which all output HTTP calls are suppressed. Default value:
false
• Heartbeat
• debugLogging: activates logging within the core Heartbeat component. Optional. Default value: false
Note: Setting the debugLogging flag to true on any of the video heartbeat components will activate fairly
extensive tracing messaging which may impact performance. While these messages are useful during
development and debugging, you should set all debugLogging flags to false for the production version of your
player app. Note that the debugLogging flags default to false, so logging is disabled by default.
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 trackVideoLoad()
and then 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 the Video Heartbeat tracking server.
After you have tested your configuration, continue to Track Player Events.
Next step: Track Player Events
Implement VideoPlayerPluginDelegate - JS
and chapter.
To get started creating your own VideoPlayerPluginDelegate implementation, create a new object that uses
ADB.va.VideoPlayerPluginDelegate as the object prototype:
var myDelegate = new VideoPlayerPluginDelegate();
Now that you have a player delegate, you need to define the functions that return information about your video and
player:
function VideoPlayerPluginDelegate() {}
VideoPlayerPluginDelegate.prototype.getVideoInfo = function() {};
76
VideoPlayerPluginDelegate.prototype.getAdBreakInfo = function() {};
VideoPlayerPluginDelegate.prototype.getAdInfo = function() {};
VideoPlayerPluginDelegate.prototype.getChapterInfo = function() {};
VideoPlayerPluginDelegate.prototype.getQoSInfo = function() {};
your player:
• Ad Information
• Example
Video Information
to find out how video information is retrieved. Video information is usually a property of the player object or retrieved
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();
Parameter
Required?
Description
playerName
Yes
id
Yes
name
No
length
Yes
playhead
Yes
streamType
Yes
resumed
No
77
Parameter
Required?
Description
playerName
Yes
name
No
position
Yes
startTime
No
Ad Information
Parameter
Required?
Description
id
Yes
length
Yes
position
Yes
name
No
Chapter Information
Parameter
Required?
Description
name
No
length
Yes
position
Yes
startTime
Yes
Example
The following is an example of a valid video player plugin delegate:
}
video player)
return videoInfo;
};
};
};
};
};
78
79
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) {
vpPlugin.trackVideoLoad();
} else {
}
}
function pause(e) {
vpPlugin.trackPause();
}
function seekStart(e) {
vpPlugin.trackSeekStart();
}
function seekEnd(e) {
vpPlugin.trackSeekComplete();
}
function trackComplete() {
vpPlugin.trackComplete();
vpPlugin.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) {
} else {
}
break;
case 2:
case 0:
// Video has been paused/ended
break;
}
}
80
81
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 the
Video Heartbeat tracking server.
In the initial call to your Analytics 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.
Debug Logging
You can enable or disable logging for each video heartbeat component.
82
The video heartbeat library provides an extensive tracing/logging mechanism that is put in place throughout the
entire video-tracking stack. You can enable or disable this logging for each video heartbeat component by setting
the debugLogging flag on the configuration object.
The log messages follow this format:
Format: [<timestamp>] [<level>] [<tag>] [<message>]
Example: [16:01:48 GMT+0200.848] [INFO]
[com.adobe.primetime.va.plugins.videoplayer::VideoPlayerPlugin] \
Data from delegate > ChapterInfo: name=First chapter, length=15, position=1, startTime=0
There are several sections delimited by pairs of square brackets as follows:
• timestamp: This is the current CPU time (time-zoned for GMT)
• level: There are 4 message levels defined:
• INFO – Usually the input data from the application (validate player name, video ID, etc.)
• DEBUG – Debug logs, used by the developers to debug more complex issues
• WARN – Indicates potential integration/configuration errors or Heartbeats SDK bugs
• ERROR – Indicates important integration errors or Heartbeats SDK bugs
• tag: The name of the sub-component that issued the log message (usually the class name)
• message: The actual trace message
You can use the logs output by the video heartbeat library to verify the implementation. A good strategy is to search
through the logs for the string #track. This will highlight all the track...() APIs called by your application.
For instance, this is what the logs filtered for #track could look like:
[17:47:48
[17:47:48
[17:47:48
[17:47:48
[17:47:49
[17:47:49
[17:48:10
[17:48:10
GMT+0200 (EET).942] [INFO] [plugin::player] #trackVideoLoad()
GMT+0200 (EET).945] [INFO] [plugin::player] #trackPlay()
GMT+0200 (EET).945] [INFO] [plugin::player] #trackPlay() > Tracking session auto-start.
GMT+0200 (EET).945] [INFO] [plugin::player] #trackSessionStart()
GMT+0200 (EET).446] [INFO] [plugin::player] #trackChapterStart()
GMT+0200 (EET).446] [INFO] [plugin::player] #trackChapterComplete()
GMT+0200 (EET).771] [INFO] [plugin::player] #trackComplete()
GMT+0200 (EET).774] [INFO] [plugin::player] #trackVideoUnload()
Using this validation method, you can easily spot implementation issues (e.g., the integration code never calls
trackAdComplete() when an ad completes playback).
iOS Players
This guide describes how to add video heartbeat measurement to any video player that provides an Objective-C
API.
Implementing video heartbeat requires that your video player provides an Objective-C API with the following:
Requirements
Integrating video heartbeat requires the following:
• Existing Analytics implementation.
83
These instructions assume that you have an existing implementation of AppMeasurement that is also using the
Marketing Cloud Visitor ID Service. On iOS these two components are bundled together in the AdobeMobileLibrary.
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 the next section of this guide.
Download the Video Heartbeat Library
2. Extract the zip, and copy the video heartbeat library to a location accessible to your project.
Next step: Configure AdobeMobileLibrary
Configure AdobeMobileLibrary
Information to help you configure the AdobeMobileLibrary.
AdobeMobileLibrary bundles the AppMeasurement library and Marketing Cloud visitor ID service components for
mobile applications. The video heartbeat library uses these components to send calls to Adobe Analytics. The
standard Analytics Variables are all available.
You must configure the AdobeMobileLibrary, using the JSON file described below.
Configure the AdobeMobileLibrary in the JSON config file included with your Adobe Mobile SDK. The following
sample config file includes settings that you must obtain from your Adobe representative. These settings include
the RSID, tracking-server URL, and Marketing Cloud visitor ID:
ADBMobileConfig.json:
{
"version" : "1.0",
"analytics" : {
"rsids" : "<rsid>",
"server" : "<tracking-server>",
"charset" : "UTF-8",
"ssl" : false,
"offlineEnabled" : false,
84
"lifecycleTimeout" : 30,
"batchLimit" : 50,
"privacyDefault" : "optedin",
"poi" : []
},
"marketingCloud": {
"org": "<marketing-cloud-org-id>"
},
"target" : {
"clientCode" : "amsdk",
"timeout" : 5
},
"audienceManager" : {
"server" : ""
}
}
Next step: Implement VideoPlayerPluginDelegate
Implement VideoPlayerPluginDelegate
The VideoPlayerPluginDelegate is used by the video heartbeat library to get information about the currently playing
video, ad, and chapter.
First, read How VideoPlayerPluginDelegate Works to understand the role of VideoPlayerPluginDelegate.
Implementing this interface is where you will typically spend the majority of your implementation time.
To get started creating your own VideoPlayerPluginDelegate implementation, instantiate an
ADB_VHB_VideoPlayerPluginDelegate object:
ADB_VHB_VideoPlayerPluginDelegate *vpPluginDelegate =
[[CustomVideoPlayerPluginDelegate alloc] initWithPlayer:<my-player>];
Next, you need to define the functions that return information about your video and player:
@interface ADB_VHB_VideoPlayerPluginDelegate : NSObject
- (ADB_VHB_VideoInfo *) getVideoInfo;
- (ADB_VHB_AdBreakInfo *) getAdBreakInfo;
- (ADB_VHB_AdInfo *) getAdInfo;
- (ADB_VHB_ChapterInfo *) getChapterInfo;
- (ADB_VHB_QoSInfo *) getQoSInfo;
85
@end
your player:
• Ad Information
• Example
Video Information
The getVideoInfo method returns an ADB_VHB_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.
Parameter
Required?
Description
playerName
Yes
id
Yes
name
No
The name of the video asset (opaque string value.)
length
Yes
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.
playhead
Yes
streamType
Yes
resumed
No
Set to YES if this is a resumed video playback session (for example, when
After you have figured out how to get the required information, update your getVideoInfo method to return an
ADB_VHB_VideoInfo object with the video information. How you populate each value is up to you, and varies based
on your player.
Parameter
Required?
Description
playerName
Yes
name
No
position
Yes
86
Parameter
Required?
Description
startTime
No
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
ADB_VHB_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
Required?
Description
id
Yes
length
Yes
position
Yes
name
No
After you have figured out how to get the required information, update the getAdInfo method to return an
ADB_VHB_AdInfo object with the ad information.
Chapter Information
Parameter
Required?
Description
name
No
length
Yes
position
Yes
startTime
Yes
Example
The following is a sample video player plugin delegate:
---------------------------------sample VideoPlayerPluginDelegate.h
----------------------------------
@class VideoPlayer;
@interface SampleVideoPlayerPluginDelegate : ADB_VHB_VideoPlayerPluginDelegate
- (instancetype)initWithPlayer:(VideoPlayer *)player NS_DESIGNATED_INITIALIZER;
@end
---------------------------------sample VideoPlayerPluginDelegate.m
----------------------------------
@interface SampleVideoPlayerPluginDelegate ()
@property(strong, nonatomic) VideoPlayer *player;
@end
@implementation SampleVideoPlayerPluginDelegate
- (instancetype)initWithPlayer:(VideoPlayer *)player {
self = [super init];
if (self) {
_player = player;
}
return self;
}
- (ADB_VHB_VideoInfo *)getVideoInfo {
ADB_VHB_VideoInfo *videoInfo = [[ADB_VHB_VideoInfo alloc] init];
videoInfo.id = self.player.videoId; // e.g. “vid123-a”
videoInfo.name = self.player.videoName; // e.g. “My sample video”
videoInfo.length = self.player.videoLength; // e.g. 240 seconds
videoInfo.streamType = ADB_VHB_AssetType.ASSET_TYPE_VOD;
videoInfo.playerName = self.player.name; // e.g. “Sample video player”
videoInfo.playhead = self.player.currentPlayhead; // e.g. 115
return videoInfo;
}
- (ADB_VHB_AdBreakInfo *)getAdBreakInfo {
}
- (ADB_VHB_AdInfo *)getAdInfo {
87
88
}
- (ADB_VHB_ChapterInfo *)getChapterInfo {
return nil; // no chapters in this scenario
}
- (ADB_VHB_QoSInfo *)getQoSInfo {
return nil; // no QoS information in this sample
}
@end
Next step: Attaching Custom Metadata
@property(nonatomic, copy) NSDictionary *videoMetadata;
@property(nonatomic, copy) NSDictionary *adMetadata;
@property(nonatomic, copy) NSDictionary *chapterMetadata;
the ad, and/or the chapter. Note that the metadata for the video will automatically be associated with the ads and
chapters as well.
You need to set the metadata prior to calling the relevant track...() method on the VideoPlayerPlugin, as
follows:
track...() call.
// Before calling trackVideoLoad:
NSMutableDictionary *videoMetadata = [[NSMutableDictionary alloc] init];
[videoMetadata setObject:@"false" forKey:@"isUserLoggedIn"];
[videoMetadata setObject:@"Sample TV station" forKey:@"tvStation"];
[videoMetadata setObject:@"Sample programmer" forKey:@"programmer"];
_analyticsPlugin.videoMetadata = [videoMetadata dictionary];
// [...]
// Before calling trackAdStart:
NSMutableDictionary *adMetadata = [[NSMutableDictionary alloc] init];
[adMetadata setObject:@"Sample affiliate" forKey:@"affiliate"];
[adMetadata setObject:@"campaign" forKey:@"campaign"];
_analyticsPlugin.adMetadata = [adMetadata dictionary];
// [...]
89
// Before calling trackChapterStart:
NSMutableDictionary *chapterMetadata = [[NSMutableDictionary alloc] init];
[chapterMetadata setObject:@"Sample segment type" forKey:@"segmentType"];
_analyticsPlugin.chapterMetadata = [chapterMetadata dictionary];
It is not reset automatically by the video heartbeat library. To clear the custom metadata, you can pass nil
Standard metadata keys for iOS
Here are the standard metadata keys for iOS:
Class: ADB_VHB_ StandardMetadataKeys.h
The following constant strings define the standard metadata keys for video:
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataSHOW;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataSEASON;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyASSET_ID;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyGENRE;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyFIRST_AIR_DATE;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyFIRST_DIGITAL_DATE;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyRATING;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyORIGINATOR;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyNETWORK;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeySHOW_TYPE;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyAD_LOAD;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyMVPD;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyAUTHORIZED;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyDAY_PART;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeyFEED;
• FOUNDATION_EXPORT NSString *const ADBVideoMetadataKeySTREAM_FORMAT;
The following constant strings define standard metadata keys for ads:
• FOUNDATION_EXPORT NSString *const ADBAdMetadataADVERTISER;
• FOUNDATION_EXPORT NSString *const ADBAdMetadataCAMPAIGN_ID;
• FOUNDATION_EXPORT NSString *const ADBAdMetadataKeyCREATIVE_ID;
• FOUNDATION_EXPORT NSString *const ADBAdMetadataKeyPLACEMENT_ID;
• FOUNDATION_EXPORT NSString *const ADBAdMetadataKeySITE_ID;
• FOUNDATION_EXPORT NSString *const ADBAdMetadataKeyCREATIVE_URL;
90
Sample implementation on iOS
Here is a sample implementation on iOS.
• Standard metadata keys for iOS
#import "ADBStandardMetadataKeys.h"
NSMutableDictionary *standardVideoMetadata = [[NSMutableDictionary alloc] init];
[standardVideoMetadata setObject:@"Sample Show" forKey:ADBVideoMetadataKeySHOW];
[standardVideoMetadata setObject:@"Sample Season" forKey:ADBVideoMetadataKeySEASON];
[standardVideoMetadata setObject:@"Sample Episode" forKey:ADBVideoMetadataKeyEPISODE];
[standardVideoMetadata setObject:@"Sample Asset Id" forKey:ADBVideoMetadataKeyASSET_ID];
[standardVideoMetadata setObject:@"Sample Genre" forKey:ADBVideoMetadataKeyGENRE];
[standardVideoMetadata setObject:@"Sample Air Date" forKey:ADBVideoMetadataKeyFIRST_AIR_DATE];
[standardVideoMetadata setObject:@"Sample Digital Date"
forKey:ADBVideoMetadataKeyFIRST_DIGITAL_DATE];
[standardVideoMetadata setObject:@"Sample Rating" forKey:ADBVideoMetadataKeyRATING];
[standardVideoMetadata setObject:@"Sample Originator" forKey:ADBVideoMetadataKeyORIGINATOR];
[standardVideoMetadata setObject:@"Sample ShowType" forKey:ADBVideoMetadataKeySHOW_TYPE];
[standardVideoMetadata setObject:@"Sample Ad Load" forKey:ADBVideoMetadataKeyAD_LOAD];
[standardVideoMetadata setObject:@"Sample MVPD" forKey:ADBVideoMetadataKeyMVPD];
[standardVideoMetadata setObject:@"Sample Authorized" forKey:ADBVideoMetadataKeyAUTHORIZED];
[standardVideoMetadata setObject:@"Sample Network" forKey:ADBVideoMetadataKeyNETWORK];
[standardVideoMetadata setObject:@"Sample Day Part" forKey:ADBVideoMetadataKeyDAY_PART];
[standardVideoMetadata setObject:@"Sample Feed" forKey:ADBVideoMetadataKeyFEED];
[standardVideoMetadata setObject:@"Sample Stream format"
forKey:ADBVideoMetadataKeySTREAM_FORMAT];
[_analyticsPlugin setVideoMetadata:standardVideoMetadata];
// Setting standard metadata for Ad
NSMutableDictionary *standardAdMetadata = [[NSMutableDictionary alloc] init];
[standardAdMetadata setObject:@"Sample Advertiser" forKey:ADBAdMetadataKeyADVERTISER];
91
[standardAdMetadata setObject:@"Sample Campaign" forKey:ADBAdMetadataKeyCAMPAIGN_ID];
[standardAdMetadata setObject:@"Sample Creative Id" forKey:ADBAdMetadataKeyCREATIVE_ID];
[standardAdMetadata setObject:@"Sample Creative URL" forKey:ADBAdMetadataKeyCREATIVE_URL];
[standardAdMetadata setObject:@"Sample Placement ID" forKey:ADBAdMetadataKeyPLACEMENT_ID];
[standardAdMetadata setObject:@"Sample Site Id" forKey:ADBAdMetadataKeySITE_ID];
[_analyticsPlugin setAdMetadata:standardAdMetadata];
After you implement VideoPlayerPluginDelegate, and optionally attach any of your own custom metadata, you are
ready to add the video heartbeat code to your project. Before you proceed, make sure you have the following:
For more information, see Configure AdobeMobileLibrary.
ID.
ADB_VHB_VideoPlayerPluginDelegate *vpPluginDelegate = [[CustomVideoPlayerPluginDelegate alloc]
initWithPlayer:<my-player>];
ADB_VHB_VideoPlayerPlugin *vpPlugin = [[ADB_VHB_VideoPlayerPlugin alloc]
initWithDelegate:vpPluginDelegate];
ADB_VHB_VideoPlayerPluginConfig *vpPluginConfig = [[ADB_VHB_VideoPlayerPluginConfig alloc]
init];
vpPluginConfig.debugLogging = YES; // set this to NO for production apps.
[vpPlugin configure:vpPluginConfig];
ADB_VHB_AdobeAnalyticsPluginDelegate *aaPluginDelegate = [[CustomAdobeAnalyticsPluginDelegate
alloc] init];
ADB_VHB_AdobeAnalyticsPlugin *aaPlugin = [[ADB_VHB_AdobeAnalyticsPlugin alloc]
initWithDelegate:aaPluginDelegate];
ADB_VHB_AdobeAnalyticsPluginConfig *aaPluginConfig = [[ADB_VHB_AdobeAnalyticsPluginConfig alloc]
init];
aaPluginConfig.debugLogging = YES; // set this to NO for production apps.
[aaPlugin configure:aaPluginConfig];
ADB_VHB_AdobeHeartbeatPluginDelegate *ahPluginDelegate = [[CustomAdobeHeartbeatPluginDelegate
alloc] init];
ADB_VHB_AdobeHeartbeatPlugin *ahPlugin = [[ADB_VHB_AdobeHeartbeatPlugin alloc]
initWithDelegate:ahPluginDelegate];
ADB_VHB_AdobeHeartbeatPluginConfig *ahPluginConfig = [[ADB_VHB_AdobeHeartbeatPluginConfig alloc]
initWithTrackingServer:<tracking-server> publisher:<publisher>];
ahPluginConfig.debugLogging = YES; // set this to NO for production apps.
92
ahPluginConfig.ssl = NO; // set this to YES to enable Heartbeat calls through HTTPS
[ahPlugin configure:ahPluginConfig];
//Heartbeat
NSArray *plugins = @[vpPlugin, aaPlugin, ahPlugin];
ADB_VHB_HeartbeatDelegate *heartbeatDelegate = [[CustomHeartbeatDelegate alloc] init];
ADB_VHB_Heartbeat *heartbeat = [[ADB_VHB_Heartbeat alloc] initWithDelegate:heartbeatDelegate
plugins:plugins];
ADB_VHB_HeartbeatConfig *heartbeatConfig = [[ADB_VHB_HeartbeatConfig alloc] init];
heartbeatConfig.debugLogging = YES; // set this to NO for production apps.
[heartbeat configure:heartbeatConfig];
• debugLogging: activates logging inside this plugin. Optional. Default value: NO
Adobe consultant.
"unknown"
• Heartbeat
• debugLogging: activates logging within the core Heartbeat component. Optional. Default value: NO
Note: Setting the debugLogging flag to YES on any of the video heartbeat components will activate fairly
development and debugging, you should set all debugLogging flags to NO for the production version of your
player app. Note that the debugLogging flags default to NO, so logging is disabled by default.
Before you continue, run your app and check that it runs without errors. Optionally, set the debugLogging flag to
YES while you test:
heartbeatConfig.debugLogging = YES; // remove or set to NO for production!
93
Track Player Events
Call the video heartbeat track methods when specific events occur in your player.
This process 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 shows a simple playback scenario:
[vpPlugin trackVideoLoad]; // when a video is loaded
[vpPlugin trackSessionStart]; // when the user clicks the 'Play' button
[vpPlugin trackPlay]; // when playback begins (frames are being rendered)
[vpPlugin trackComplete]; // when the playback reaches the end of the content
[vpPlugin trackVideoUnload]; // after calling trackComplete()
Note that different players provide different ways to listen to events. Use the documentation provided by the player
2. Test your implementation thoroughly to make sure you haven't missed any events. For example, if your player
and complete when the video completes.
Debug Logging
Example: [16:01:48 GMT+0200.848] [INFO]
94
through the logs for the string #track. This will highlight all the track... APIs called by your application.
[17:47:48
[17:47:48
[17:47:48
[17:47:48
[17:47:49
[17:47:49
[17:48:10
[17:48:10
GMT+0200
GMT+0200
GMT+0200
GMT+0200
GMT+0200
GMT+0200
GMT+0200
GMT+0200
(EET).942] [INFO] [plugin::player] #trackVideoLoad
(EET).945] [INFO] [plugin::player] #trackPlay
(EET).945] [INFO] [plugin::player] #trackPlay > Tracking session auto-start.
(EET).945] [INFO] [plugin::player] #trackSessionStart
(EET).446] [INFO] [plugin::player] #trackChapterStart
(EET).446] [INFO] [plugin::player] #trackChapterComplete
(EET).771] [INFO] [plugin::player] #trackComplete
(EET).774] [INFO] [plugin::player] #trackVideoUnload
trackAdComplete when an ad completes playback).
Android Players
This guide describes how to add video heartbeat measurement to any video player that provides a Java API.
Implementing video heartbeat requires that your video player provides a Java API with the following:
Requirements
• An existing Analytics implementation.
These instructions assume that you have an existing implementation of AppMeasurement that is also using the
Marketing Cloud Visitor ID Service. On Android these two components are bundled together in the
AdobeMobileLibrary. 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.
• Video heartbeat library. Download instructions are in the next section of this guide.
95
2. Extract the zip, and copy the video heartbeat library to a location accessible to your project.
Next step: Configure AdobeMobile Library
Configure AdobeMobile Library
Information to help you configure the AdobeMobile Library.
AdobeMobileLibrary bundles the AppMeasurement library and Marketing Cloud visitor ID service components for
mobile applications. The video heartbeat library uses these components to send calls to Adobe Analytics. The
standard Analytics Variables are all available.
You must configure the AdobeMobileLibrary, using the JSON file described below.
Configure the AdobeMobileLibrary in the JSON config file included with your Adobe Mobile SDK. The following
sample config file includes settings that you must obtain from your Adobe representative. These settings include
the RSID, tracking-server URL, and Marketing Cloud visitor ID:
ADBMobileConfig.json:
{
"version" : "1.0",
"analytics" : {
"rsids" : "<rsid>",
"server" : "<tracking-server>",
"charset" : "UTF-8",
"ssl" : false,
"offlineEnabled" : false,
"lifecycleTimeout" : 30,
"batchLimit" : 50,
"privacyDefault" : "optedin",
"poi" : []
},
"marketingCloud": {
"org": "<marketing-cloud-org-id>"
},
"target" : {
96
"clientCode" : "amsdk",
"timeout" : 5
},
"audienceManager" : {
"server" : ""
}
}
Next step: Implement VideoPlayerPluginDelegate
and chapter.
First, read How VideoPlayerPluginDelegate Works to understand the role of VideoPlayerPluginDelegate.
Implementing this interface is where you will typically spend the majority of your implementation time.
To get started creating your own VideoPlayerPluginDelegate implementation, instantiate an
VideoPlayerPluginDelegate object:
VideoPlayerPluginDelegate vpPluginDelegate =
new CustomVideoPlayerPluginDelegate(<my-player>);
Next, you need to define the functions that return information about your video and player:
public class VideoPlayerPluginDelegate {
public VideoInfo getVideoInfo() {}
public AdBreakInfo getAdBreakInfo() {}
public AdInfo getAdInfo() {}
public ChapterInfo getChapterInfo() {}
public QoSInfo getQoSInfo() {}
}
your player:
• Ad Information
• Example
97
Video Information
to find out how video information is retrieved.
Parameter
Required?
Description
playerName
Yes
id
Yes
The ID of the video asset
name
No
length
Yes
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.
playhead
Yes
streamType
Yes
resumed
No
After you have figured out how to get the required information, update your getVideoInfo method to return an
VideoInfo object with the video information. How you populate each value is up to you, and varies based on your
player.
Parameter
Required?
Description
playerName
Yes
name
No
position
Yes
startTime
No
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
Parameter
Required?
Description
id
Yes
length
Yes
98
Parameter
Required?
Description
position
Yes
name
No
Chapter Information
Parameter
Required?
Description
name
No
length
Yes
position
Yes
startTime
Yes
Example
The following is a sample video player plugin delegate:
VideoPlayerDelegate(VideoPlayer player) {
_player = player;
}
@Override
public VideoInfo getVideoInfo() {
VideoInfo videoInfo = new VideoInfo();
videoInfo.id = _player.getVideoId(); // e.g. “vid123-a”
videoInfo.name = _player.getVideoName(); // e.g. “My sample video”
videoInfo.length = _player.getVideoLength(); // e.g. 240 seconds
videoInfo.playerName = _player.getName(); // e.g. “Sample video player”
videoInfo.playhead = _player.getCurrentPlayhead(); // e.g. 115
return videoInfo;
}
99
@Override
public AdBreakInfo getAdBreakInfo() {
}
@Override
public AdInfo getAdInfo() {
}
@Override
public ChapterInfo getChapterInfo() {
}
@Override
public QoSInfo getQoSInfo() {
}
private final VideoPlayer _player;
}
Next step: Attaching Custom Metadata
The video heartbeat library provides support for custom metadata to be attached to the Analytics calls. The relevant
public void setVideoMetadata(Map<String, String> data) {}
public void setAdMetadata(Map<String, String> data) {}
public void setChapterMetadata(Map<String, String> data) {}
the ad, and/or the chapter. Note that the metadata for the video will automatically be associated with the ads and
chapters as well.
follows:
100
track...() call.
HashMap<String, String> videoMetadata = new HashMap<String, String>();
videoMetadata.put("isUserLoggedIn", "false");
videoMetadata.put("tvStation", "Sample TV station");
videoMetadata.put("programmer", "Sample programmer");
adobeAnalyticsPlugin.setVideoMetadata(videoMetadata);
// [...]
HashMap<String, String> adMetadata = new HashMap<String, String>();
adMetadata.put("affiliate", "Sample affiliate");
adMetadata.put("campaign", "Sample ad campaign");
adobeAnalyticsPlugin.setAdMetadata(adMetadata);
// [...]
HashMap<String, String> chapterMetadata = new HashMap<String, String>();
chapterMetadata.put("segmentType", "Sample segment type");
adobeAnalyticsPlugin.setChapterMetadata(chapterMetadata);
It is not reset automatically by the video heartbeat library. To clear the custom metadata, you can pass null
Standard metadata keys for Android
Here are the standard metadata keys for Android:
Class: com.adobe.primetime.va.plugins.aa.VideoMetadataKeys
Here are the constants:
• public static final String SHOW;
• public static final String SEASON;
• public static final String EPISODE;
• public static final String ASSET_ID;
• public static final String GENRE;
• public static final String FIRST_AIR_DATE;
• public static final String FIRST_DIGITAL_DATE;
• public static final String RATING;
• public static final String ORIGINATOR;
101
• public static final String NETWORK;
• public static final String SHOW_TYPE;
• public static final String AD_LOAD;
• public static final String MVPD;
• public static final String AUTHORIZED;
• public static final String DAY_PART;
• public static final String FEED;
• public static final String STREAM_FORMAT;
Class: com.adobe.primetime.va.plugins.aa.AdMetadataKeys
Here are the constants:
• public static final String ADVERTISER;
• public static final String CAMPAIGN_ID;
• public static final String CREATIVE_ID;
• public static final String PLACEMENT_ID;
• public static final String SITE_ID;
• public static final String CREATIVE_URL;
Sample implementation on Android
Here is a sample implementation on Android.
• Standard metadata keys for Android
import com.adobe.primetime.va.plugins.aa.VideoMetadataKeys;
// Setting standard metadata for Video
HashMap<String, String> videoMetadata = new HashMap<String, String>();
videoMetadata.put(VideoMetadataKeys.EPISODE, "Sample Episode");
videoMetadata.put(VideoMetadataKeys.SEASON, "Sample Season");
videoMetadata.put(VideoMetadataKeys.SHOW, "Sample Show");
videoMetadata.put(VideoMetadataKeys.ASSET_ID, "Sample Asset ID");
videoMetadata.put(VideoMetadataKeys.GENRE, "Sample Genre");
videoMetadata.put(VideoMetadataKeys.FIRST_AIR_DATE, "Sample air date");
videoMetadata.put(VideoMetadataKeys.FIRST_DIGITAL_DATE, "Sample digital date");
videoMetadata.put(VideoMetadataKeys.RATING, "Sample Rating");
videoMetadata.put(VideoMetadataKeys.ORIGINATOR, "Sample Originator");
videoMetadata.put(VideoMetadataKeys.SHOW_TYPE, "Sample Show Type");
videoMetadata.put(VideoMetadataKeys.AD_LOAD, "ad load");
videoMetadata.put(VideoMetadataKeys.MVPD, "sample mvpd");
videoMetadata.put(VideoMetadataKeys.AUTHORIZED, "false");
videoMetadata.put(VideoMetadataKeys.NETWORK, "Sample TV Network");
videoMetadata.put(VideoMetadataKeys.DAY_PART, "sample day part");
videoMetadata.put(VideoMetadataKeys.FEED, "sample feed type");
videoMetadata.put(VideoMetadataKeys.STREAM_FORMAT, "sample stream format");
_aaPlugin.setVideoMetadata(videoMetadata);
import com.adobe.primetime.va.plugins.aa.AdMetadataKeys;
// Setting standard metadata for Ad
102
HashMap<String, String> adMetadata = new HashMap<String, String>();
adMetadata.put(AdMetadataKeys.CREATIVE_ID, "Sample creative id");
adMetadata.put(AdMetadataKeys.CAMPAIGN_ID, "Sample ad campaign");
adMetadata.put(AdMetadataKeys.ADVERTISER, "Sample advertiser");
adMetadata.put(AdMetadataKeys.CREATIVE_URL, "Sample creative url");
adMetadata.put(AdMetadataKeys.PLACEMENT_ID, "Sample placement");
adMetadata.put(AdMetadataKeys.SITE_ID, "Sample site");
_aaPlugin.setAdMetadata(adMetadata);
After you implement VideoPlayerPluginDelegate, and optionally attach any of your own custom metadata, you are
ready to add the video heartbeat code to your project. Before you proceed, make sure you have the following:
For more information, see Configure AdobeMobile Library.
ID.
VideoPlayerPluginDelegate vpPluginDelegate = new CustomVideoPlayerPluginDelegate(<my-player>);
VideoPlayerPlugin vpPlugin = new VideoPlayerPlugin(vpPluginDelegate);
VideoPlayerPluginConfig vpPluginConfig = new VideoPlayerPluginConfig();
AdobeAnalyticsPluginDelegate aaPluginDelegate = new CustomAdobeAnalyticsPluginDelegate();
AdobeAnalyticsPlugin aaPlugin = new AdobeAnalyticsPlugin(aaPluginDelegate);
AdobeAnalyticsPluginConfig aaPluginConfig = new AdobeAnalyticsPluginConfig();
AdobeHeartbeatPluginDelegate ahPluginDelegate = new CustomAdobeHeartbeatPluginDelegate();
AdobeHeartbeatPlugin ahPlugin = new AdobeHeartbeatPlugin(ahPluginDelegate);
AdobeHeartbeatPluginConfig ahPluginConfig = new AdobeHeartbeatPluginConfig(<tracking-server>,
<publisher>);
// Heartbeat
List<IPlugin> plugins = new ArrayList<IPlugin>();
plugins.add(vpPlugin);
plugins.add(aaPlugin);
plugins.add(ahPlugin);
103
HeartbeatDelegate heartbeatDelegate = new CustomHeartbeatDelegate();
Heartbeat heartbeat = new Heartbeat(heartbeatDelegate, plugins);
HeartbeatConfig heartbeatConfig = new HeartbeatConfig();
Adobe consultant.
"unknown"
• Heartbeat
development and debugging, you should set all debugLogging flags to false for the production version of
your player app. Note that the debugLogging flags default to false, so logging is disabled by default.
Before you continue, run your app and check that it runs without errors. Optionally, set the debugLogging flag to
YES while you test:
Track Player Events
104
The following example shows a simple playback scenario:
trackVideoLoad(); // when a video is loaded
trackSessionStart(); // when the user clicks the 'Play' button
trackPlay(); // when playback begins (frames are being rendered)
trackComplete(); // when the playback reaches the end of the content
trackVideoUnload(); // after calling trackComplete()
Note that different players provide different ways to listen to events. Use the documentation provided by the player
2. Test your implementation thoroughly to make sure you haven't missed any events. For example, if your player
and complete when the video completes.
Debug Logging
Example: [16:01:48 GMT+0200.848] [INFO]
105
[17:47:48
[17:47:48
[17:47:48
[17:47:48
[17:47:49
[17:47:49
[17:48:10
[17:48:10
GMT+0200 (EET).942] [INFO] [plugin::player] #trackVideoLoad()
GMT+0200 (EET).945] [INFO] [plugin::player] #trackPlay()
GMT+0200 (EET).945] [INFO] [plugin::player] #trackPlay() > Tracking session auto-start.
GMT+0200 (EET).945] [INFO] [plugin::player] #trackSessionStart()
GMT+0200 (EET).446] [INFO] [plugin::player] #trackChapterStart()
GMT+0200 (EET).446] [INFO] [plugin::player] #trackChapterComplete()
GMT+0200 (EET).771] [INFO] [plugin::player] #trackComplete()
GMT+0200 (EET).774] [INFO] [plugin::player] #trackVideoUnload()
ActionScript Players
This section 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 measurement requires that your video player provides an ActionScript API with the
following:
Requirements
Integrating the video heartbeat library 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)
2. Extract the zip, and copy VideoHeartbeat.swc to a location accessible to your project.
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, VisitorAPI.swc, and VideoHeartbeat.swc libraries to your project.
4. In the Timeline pane, select a frame that is available to the entire Flash application and open Actions.
106
107
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.core.plugin.IPlugin;
import com.adobe.primetime.va.plugins.aa.AdobeAnalyticsPlugin;
import com.adobe.primetime.va.plugins.aa.AdobeAnalyticsPluginConfig;
import com.adobe.primetime.va.plugins.ah.AdobeHeartbeatPlugin;
import com.adobe.primetime.va.plugins.ah.AdobeHeartbeatPluginConfig;
import com.adobe.primetime.va.plugins.videoplayer.VideoPlayerPlugin;
import com.adobe.primetime.va.plugins.videoplayer.VideoPlayerPluginConfig;
As you use these libraries in your project, auto complete should appear. This indicates that the library is being
found successfully.
If you don't see auto complete, verify that the libraries are added to your project.
Next step: Configure AppMeasurement.
Configure AppMeasurement
Information to help you 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; // from Step 1
At a minimum, configure the following three variables:
• s.account
• s.trackingServer
• s.visitor
These values can be copied directly from your s_code.js or AppMeasurement.js file.
Next step: Implement VideoPlayerPluginDelegate.
108
and chapter.
To get started creating your own VideoPlayerPluginDelegate class, create a new class (File > New, ActionScript
3.0 Class) that uses com.adobe.primetime.va.VideoPlayerPluginDelegate as the object prototype:
package {
import com.adobe.primetime.va.VideoPlayerPluginDelegate;
import com.adobe.primetime.va.plugins.videoplayer.AdBreakInfo;
import com.adobe.primetime.va.plugins.videoplayer.AdInfo;
import com.adobe.primetime.va.plugins.videoplayer.ChapterInfo;
import com.adobe.primetime.va.plugins.videoplayer.ErrorInfo;
import com.adobe.primetime.va.plugins.videoplayer.QoSInfo;
import com.adobe.primetime.va.plugins.videoplayer.VideoInfo;
import com.adobe.primetime.va.plugins.videoplayer.AssetType;
import fl.video.FLVPlayback;
public class MyDelegate extends VideoPlayerPluginDelegate {
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;
return ai;
}
override public function get chapterInfo():ChapterInfo {
var ci:ChapterInfo = new ChapterInfo();
ci.name = "";
ci.length = -1;
ci.position = 1;
ci.startTime = -1;
return ci;
}
override public function get qosInfo():QoSInfo {
}
109
110
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.
your player:
• Ad Information
Video Information
The get VideoInfo method returns a VideoInfo object that contains details about the video player and the currently
to find out how video information is retrieved. Video information is usually a property of the player object, or retrieved
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
Required?
Description
playerName
Yes
id
Yes
name
No
length
Yes
playhead
Yes
streamType
Yes
The type of the video asset. Can be one of the following constants defined by
the video heartbeat library, but you can pass any string value:
AssetType.ASSET_TYPE_LIVE, AssetType.ASSET_TYPE_LINEAR,
AssetType.ASSET_TYPE_VOD
111
Parameter
Required?
Description
playerName
Yes
name
No
position
Yes
startTime
No
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
Required?
Description
id
Yes
length
Yes
position
Yes
name
No
Chapter Information
Parameter
Required
Description
name
No
length
Yes
position
Yes
startTime
Yes
112
public function set videoMetadata(data:Object):void {}
public function set adMetadata(data:Object):void {}
public function set chapterMetadata(data:Object):void {}
the ad and/or the chapter. Note that the metadata for the video will automatically be associated with the ads and
chapters as well.
follows:
track...() call.
adobeAnalyticsPlugin.videoMetadata = {
isUserLoggedIn: "false",
tvStation: "Sample TV station",
programmer: "Sample programmer"
};
// [...]
adobeAnalyticsPlugin.adMetadata = {
affiliate: "Sample affiliate",
campaign: "Sample ad campaign"
};
// [...]
adobeAnalyticsPlugin.chapterMetadata = {
segmentType: "Sample segment type"
};
It is not reset automatically by the video heartbeat library. To clear the custom metadata, you can pass NULL
113
After you Implement VideoPlayerPluginDelegate, 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.
• Your Adobe ID or 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.
var vpPluginDelegate:VideoPlayerPluginDelegate = new
CustomVideoPlayerPluginDelegate(<my-player>);
var vpPlugin:VideoPlayerPlugin = new VideoPlayerPlugin(vpPluginDelegate);
var vpPluginConfig:VideoPlayerPluginConfig = new VideoPlayerPluginConfig();
var aaPluginDelegate:AdobeAnalyticsPluginDelegate = new CustomAdobeAnalyticsPluginDelegate();
var aaPlugin:AdobeAnalyticsPlugin = new AdobeAnalyticsPlugin(appMeasurement, aaPluginDelegate);
var aaPluginConfig:AdobeAnalyticsPluginConfig = new AdobeAnalyticsPluginConfig();
var ahPluginDelegate:AdobeHeartbeatPluginDelegate = new CustomAdobeHeartbeatPluginDelegate();
var ahPlugin:AdobeHeartbeatPlugin = new AdobeHeartbeatPlugin(ahPluginDelegate);
var ahPluginConfig:AdobeHeartbeatPluginConfig = new AdobeHeartbeatPluginConfig(<tracking-server>,
<publisher>);
// Heartbeat
var plugins:Vector<IPlugin> = new <IPlugin>[vpPlugin, aaPlugin, ahPlugin];
var heartbeatDelegate:HeartbeatDelegate = new CustomHeartbeatDelegate();
var heartbeat:Heartbeat = new Heartbeat(heartbeatDelegate, plugins);
var heartbeatConfig:HeartbeatConfig = new HeartbeatConfig();
Adobe consultant.
114
• ssl: Indicates whether the heartbeat calls should be made over HTTPS. Optional. Default value: false
"unknown"
• quietMode: activates the "quiet" mode of operation, in which all output HTTP calls are suppressed. Default value:
false
• Heartbeat
development and debugging, you should set all debugLogging flags to false for the production version of your
player app. Note that the debugLogging flags default to false, so logging is disabled by default.
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:
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 the Video Heartbeat tracking server.
Track Player Events
Flash media players are typically tracked by attaching callback functions to the video player event handlers.
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);
115
function onPlay(e:fl.video.VideoEvent):void {
if (player.playheadTime == 0) {
}
else vpPlugin.trackPlay();
}
function onComplete(e:fl.video.VideoEvent):void {
}
function onPause(e:fl.video.VideoEvent):void {
}
function onSeekStart(e:fl.video.VideoEvent):void {
vpPlugin.trackSeekStart();
}
function onSeekFinish(e:fl.video.VideoEvent):void {
vpPlugin.trackSeekComplete();
}
Note that each player provides a different way to listen to events. Use the documentation provided by the player
116
2. Test your implementation throughly to make sure you haven't missed any events. For example, if your player
sent as expected. For example, you should see an s:event:type of start when the video begins, and complete
when the video completes.
Debug Logging
Example: [16:01:48 GMT+0200.848] [INFO]
[16:01:48 GMT+0200.342] [INFO] [com.adobe.primetime.va.plugins.videoplayer::VideoPlayerPlugin]
#trackVideoLoad()
#trackPlay()
#trackPlay() > Tracking session auto-start.
#trackSessionStart()
#trackChapterStart()
#trackAdStart()
#trackAdComplete()
#trackChapterStart()
#trackComplete()
#trackVideoUnload()
117
OTT (Over-the-Top) Analytics
Adobe Video Analytics provides standardized measurement of both video and apps for OTT (Over-the-Top) devices.
OTT devices are sometimes called IP-connected devices.
With OTT analytics, a broadcaster can create an app that is available on Roku or AppleTV and then measure video
and app metrics across those OTT devices the same way for desktop and mobile devices.
On-demand content viewing is continuing to explode. The growth of broadband content delivery to TV screens via
Over-the-Top (OTT) devices such as Apple TV, Chromecast and Roku is quickly outpacing all other channels–showing
that TV is still the preferred screen for viewing long-form programming.
By measuring these OTT devices, Adobe Analytics customers will get a more complete view of content engagement
and how this industry trend is driving viewer behavior. Ultimately, accurate measurement across all devices increases
opportunities for ad monetization.
OTT SDKs currently support the following devices:
• Roku (BrightScript apps only)
• AppleTV
Coming soon: Chromecast & Xbox One
Note: The Visitor ID service is required by video heartbeat. To learn more, see Visitor ID service. For detailed
instructions, see the Roku or Apple TV developer documentation linked below.
What Does OTT analytics measure?
OTT analytics lets you measure the following:
• Video Measurement: For a list of all variables and events video heartbeat collects, see Video Reports.
• App Measurement: Video heartbeats collect the following for apps:
• App States: States are the different screens or views in your application.
Each time a new state is displayed in your application (for example, when a user navigates from the home page
to the video detail screen), you should send a trackstate call. In Roku and AppleTV, trackstate is typically
called each time a new screen is loaded.
• App Actions: Actions are the events that occur in your app that you want to measure.
Each action has one or more corresponding metrics that are incremented each time the event occurs. For example,
you might send a trackaction call for each new subscription, each time a content is rated, or each time a level
is completed. Actions are not tracked automatically, you must call trackaction when an event you want to
track occurs and then map the action to a custom event.
For more information about app states and app actions, see the "Analytics" section in the Roku or Apple TV
developer documentation linked below.
118
Roku
AppleTV SDK 1.x for Marketing Cloud Solutions lets you measure Roku applications written in BrightScript, leverage
and collect audience data through audience management, and measure video engagement through video heartbeats.
To get started:
1. Download the Roku SDK 1.x for Marketing Cloud Solutions documentation.
2. Contact the Adobe Customer Care Team to obtain the SDK.
AppleTV
AppleTV SDK 1.x for Marketing Cloud Solutions lets you measure AppleTV applications written in JavaScript,
leverage and collect audience data through audience management, and measure video engagement through video
heartbeats.
To get started:
1. Download the AppleTV SDK 1.x for Marketing Cloud Solutions documentation.
2. Contact the Adobe Customer Care Team to obtain the SDK.
Video Heartbeat 2.x Developer Guides
119
Video Heartbeat 2.x Developer Guides
Here are the developer guides for VHL 2.x:
Platform
Documentation
Android
Video Heartbeat 2.0 Developer Guide for Android
iOS
Video Heartbeat 2.0 Developer Guide for iOS
JavaScript
Video Heartbeat 2.0 Developer Guide for JavaScript
Migrating to Video Heartbeat
120
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
Enable video reports
Marketing reports
and analytics UI
Description
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.
See 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.
See 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.
See 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.
See 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.
See the Video Heartbeat 1.5 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;
121
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
What's New in Version 1.5
Information to help you understand the changes introduced in version 1.5 of the video heartbeat library.
Video heartbeat library version 1.5 includes the following changes:
Packaging
The previous version (v1.4) of the video heartbeat delivery package contains two separate binary components:
• VideoHeartbeat
In version 1.5, while these component are still separated at the public API level, they are bundled inside a single
library called VideoHeartbeat.
VideoHeartbeat Components
In version 1.4 there were two components that had to be instantiated and configured:
• VideoHeartbeat
In version 1.5, the VideoHeartbeat core has been split into several components:
• Heartbeat (the core) - This was called VideoHeartbeat in version 1.4
122
• AdobeHeartbeatPlugin - This used to be located inside the VideoHeartbeat component. It is responsible for
processing the tracking data and sending heartbeat calls.
• VideoPlayerPlugin - This used to be located inside the VideoHeartbeat component. It is responsible for collecting
tracking data from the video player.
• AdobeAnalyticsPlugin - This was also a separate plugin in version 1.4. It is responsible for sending calls to Analytics.
Collecting Video Player Data
In version 1.4, data from the VideoPlayer was gathered via the PlayerDelegate.You extended the PlayerDelegate
abstract class and provided it as a parameter to the VideoHeartbeat instance.
The track...() methods were exposed by the VideoHeartbeat class.
With the new component structure, things have changed slightly, as follows:
• The PlayerDelegate is now called VideoPlayerPluginDelegate. It must now be provided as a parameter to the
constructor method of the VideoPlayer plugin class.
• The track...* methods are now exposed by the VideoPlayerPlugin.
New Features and API Changes
New features and APIs that are available in version 1.5:
• Support for sending custom metadata.
• Support for specifying the startupTime QoS metric.
• New track...() method: trackSessionStart()
• This is the method called by the integration code to signal the intention to start playback. It is used to compute
the startupTime in case it is not provided explicitly on the QoSInfo.
• The trackComplete() method now takes a callback parameter. This callback will be called once the 'complete'
heartbeat call has been sent over the wire.
• New delegates (one for each of the VideoHeartbeat components). This change arose naturally due to the split of
the VideoHeartbeat component into multiple sub-components. The new delegates are:
• HeartbeatDelegate (for the core component)
• AdobeAnalyticsPluginDelegate (for the AdobeAnalyticsPlugin)
• AdobeHeartbeatPluginDelegate (for the AdobeHeartbeatPlugin)
• Ability to enable/disable logging per VideoHeartbeat component.
• The jobId heartbeat configuration parameter is no longer required.
Below is the list of the APIs that have been removed:
• onVideoUnloaded() callback on the PlayerDelegate. This method has been removed. We recommend using the
callback on the trackComplete() method instead.
• onError() callback on the PlayerDelegate. The VideoPlayerPlugin cannot have errors so this method has been
removed. The other VideoHeartbeat components may still have errors. There is an onError() callback defined in
each of the other VideoHeartbeat components' delegate.
Measuring Video FAQ
123
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?
Yes. 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 ten seconds for both content in ads. In a future release, we do expect to lower
heartbeat frequency for ads down to five 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. All 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 three 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 representative to update their contract and include new
stream-based pricing. Benefit to the customer is that new pricing should stabilize the 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). The actual heartbeat
includes: QoS data (related to Primetime), user metadata, asset metadata, event timestamps, and Analytics metadata.
How big are the heartbeats and will it impact performance?
Average heartbeat is 1Kb and should not impact performance.
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 throw 404 errors in debug mode, however, the video will still be tracked and heartbeats sent.
Measuring Video FAQ
124
Note: Existing customers using the Publisher ID can continue using it, but we recommend that you start using
your Marketing Cloud Org ID instead. Contact Adobe Customer Care to obtain a Marketing Cloud Org ID.
Can I use players provided by other vendors, such as Brightcove, thePlatform, etc?
Yes, 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.
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?
Yes. 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 representative 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 hours
30 hours
Unknown/Non-Documented
40 hours
50 hours
All projects include the following tasks:
• Creation of player mapping
Measuring Video FAQ
125
• Code integration with client sites/apps
• Set-up of reporting
• Basic analysis
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
Will video data be available in Data Warehouse, Report Builder, Ad Hoc Analysis, and Data Workplace?
Yes, all video data will be available in these solutions provided customer has existing access to them.
Implementation validations
Implementation validations
This topic will describe how to gain access and how to use Adobe Debug.
126
127
All updates (additions, deletions, and corrections) to the Measuring Video in Adobe Analytics using Video Heartbeat
Users Guide, by date.
This section contains detailed information about updates to this guide that might not be included in the Release
Notes. Consult the Release Notes for information about new features and bug fixes.
Date
November 5, 2015
Location
Description
Content (Core) Variables and Events Added the following Video Core parameters:
Important: To take advantage of and access
these new events, you must perform the
following steps:
1. Update to our latest video heartbeat tracking
server.
The new tracking server is hb-fa-1.omtrdc.net
(the previous version was
heartbeats.omtrdc.net).
The tracking server must be updated across all
platforms that you’ve enabled with heartbeats.
2. In the Admin console, re-enable Video Core within
the report suite video settings.
November 5, 2015
Added the following Content (Core) events:
Important: To take advantage of and access
these new events, you must perform the
following steps:
1. Update to our latest video heartbeat tracking
server.
Date
128
Location
Description
The new tracking server is hb-fa-1.omtrdc.net
(the previous version was
heartbeats.omtrdc.net).
The tracking server must be updated across all
platforms that you’ve enabled with heartbeats.
2. In the Admin console, re-enable Video Core within
the report suite video settings.
September 24, 2015
Revised "Data to Be Shared" tables by adding the
appropriate label above each context data variable.
September 24, 2015 Content (Core) Variables and Events Added more information to the Description column in
each table.
Ad Variables and Events
Chapter Variables and Events
September 17, 2015
September 17, 2015 OTT (Over-the-Top) Analytics
New topic.
New topics.
Roku
AppleTV
September 17, 2015
September 17, 2015
Federated Analytics
New topic.
New topic.
September 17, 2015 Configure the Video Heartbeat Library Added information that you can now use your Adobe
ID or publisher ID.
July 28, 2015
Added "Clickstream/API Variable Name" column to
all tables.
July 20, 2015
Getting Started
Edited Step 2.
June 18, 2015
Configure Analytics Video Reporting Added note explaining that existing Video Analytics
customers should re-enable video tracking for their
RSIDs to take advantage of new features.
Date
129
Location
Description
Added information about enabling the Video Quality
option.
June 18, 2015
Enable Video Pathing
Removed topic.
Video pathing is now enabled by default (for new
RSIDs). Existing RSIDs are enabled when you
re-enable video tracking.
June 18, 2015
Video Dashboards
Changed path to the Video section (Analytics >
Reports & Analytics > Video) and edited text in
table.
Specific changes include the following:
Video Overview Report:
From:
Total video and ad views for specific videos filtered
To:
Total content and ad starts for videos filtered by device
type or country.
Video Detail Report:
From:
Totals for top video metrics including video starts, ad
impressions, average ads per video.
To:
Totals for top video metrics including video initiates,
content and ad starts, average ads per video.
Video Daypart:
From:
Displays unique visitors and video views by time of
day to let you quickly view when your audience is
engaged.
To:
Displays content starts by time of day to let you quickly
view when your audience is engaged.
June 18, 2015
Video Overview
Updated the image and edited the following line:
From:
Date
130
Location
Description
A graph displays video starts next to ad impressions
to let you quickly view these metrics for each video.
To:
A graph displays content starts next to ad starts to let
you quickly view these metrics for each video.
June 18, 2015
Video Detail
From:
The Video Detail Report displays detailed metrics
for all videos including starts, completion rate, play
percentage, and ad impressions.
To:
The Video Detail Report displays detailed metrics
for all videos including content starts, completion rate,
time spent, and ad starts.
June 18, 2015
Video Daypart
From:
Displays unique visitors and video views by time of
day to let you quickly view when your audience is
engaged.
To:
The Video Daypart report displays content starts by
time of day to let you quickly view when your audience
is engaged.
June 18, 2015
Video Measurement Timeline
New content in all topics in this section:
• Video Measurement Timeline
• Scenario and Timeline Illustrations
• Tracking Explained
• Non-Linear Tracking Scenarios
June 18, 2015
Replaced contents of the Video Core Parameters,
Video Ad Parameters, and Video Chapter
Parameters tables.
Added Video Quality Parameters and Other
Parameters tables.
131
Date
Location
Description
June 18, 2015
Video Reports
Changed title of topic from "Video Metrics and
Dimensions" to "Video Variables and Events."
Content of entire topic is new.
June 18, 2015
New topic.
April 6, 2015
What's New in Version 1.5
New topic.
132
Historical release notes, listed by release date in descending order.
September 17, 2015
The September 17, 2015 release of video heartbeat includes the following changes:
New Features
Feature
Description
Federated Analytics
Federated Analytics is an Adobe Video Analytics feature allowing standardized
cross-platform sharing of video data between partners, governed by rules/logic.
The Customer can control the data that will be shared during each video playback,
down to an individual video level. The Partner can specify where the data should
be sent, within Adobe, based on defined triggers.
For more information, see Federated Analytics.
OTT (Over-the-Top) Analytics Adobe Video Analytics provides standardized measurement of both video and apps
for OTT devices. New OTT SDKs include:
• Roku (BrightScript apps only)
• AppleTV
• Coming soon: Chromecast & Xbox One
For more information, see OTT (Over-the-Top) Analytics.
Quality of Experience (QoE)
Metrics
The Adobe Video Analytics SDK collects more than 20 Quality of Experience
metrics, including buffering, bitrates, and errors to track how video quality impacts
key engagement metrics like time spent, videos per visit, ads per video, and so
forth.
For more information, see Quality Variables and Events.
June 18, 2015
The June 18, 2015 release of video heartbeat includes the following changes:
New Features
Feature
Description
Video Core metrics
New video core metrics are available if you re-enable video tracking from the Admin
console:
• Content Starts
• For implementations using video heartbeat library v1.5, this metric marks the
display of the first frame of the content.
• For implementations using video heartbeat library v1.4 and lower, this metric has
the same values as Video Initiates (formerly named Video Views).
Feature
133
Description
• Video Time Spent
• The sum of Content Time Spent and Ads Time Spent. You must enable the
Video Ads module to have this metric available.
• Video Path
• This is a Solution Variable.
• The maximum depth of the path is three.
See Video Reports.
Video Quality
The Video Quality module is now available. To enable it, go to the Video
Management Console. The following metrics are computed:
• Quality Variables: Time to Start, Buffer Events, Total Buffer Duration, Bitrate
Switches, Avg Bitrate, Errors, and Dropped Frames.
• Quality Events: Time to Start, Drops before Start, Buffer Impacted Streams,
Buffer Events, Total Buffer Duration, Bitrate Change Impacted Streams, Bitrate
Changes, Avg Bitrate, Error Impacted Streams, Error Events, Dropped Frame
Impacted Streams, and Dropped Frames.
See Video Reports.
Enhancements
• Changed variables and events names to better reflect the components' purposes (video, content, ads). Video now
includes both the main content and the ads.
• Updated the Video Engagement reports to include new video core metrics.
• Updated the Video Menu section to reflect the video module structure. Note that custom menus might be affected.
Fixes
• Fixed cosmetic issues in Video Engagement reports.
• Fixed the metrics in Video DayPart report by excluding future days from the calculation of the average.
April 6, 2015
The April 6, 2015 release of video heartbeat includes the following changes:
Feature
Description
Video Heartbeat Library 1.5
The video heartbeat library version 1.5 lets you attach arbitrary metadata to your
video streams.
See What's New in Version 1.5.
Contact and Legal Information
134
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
©
2015 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.

Video Heartbeat - Adobe Marketing Cloud

Transcription

Similar documents

ExamView Player

Is your player Tour Series ready?

2013 Issue 2

Land Before Time Make A Match Rules

Step by step instructions for players registering for Pelada FA

TEXT ANALYTICS

Four ways of hearing video game music

Golf Outing - Big Brothers Big Sisters of the Mississippi Valley

THE GAME OF OSSELETS [oss-LAY]

- Virginia Beach City Public Schools