Adobe Heartbeat Tag Setup Guide for Tealium iQ Tag Management

[#1]

The Adobe Heartbeat tag allows you to collect extensive data on how visitors interact with videos on your site. When your video loads on a page, Heartbeat triggers server calls every second through the length of the video, capturing its playhead positions, pause and resume actions, ad views, and several other video performance parameters. Additionally, if your implementation is integrated with the Nielsen DCR plugin, you can configure those parameters together in this tag. In this article, you will learn how to set up the tag in your Tealium iQ profile and send the aggregated data to Adobe destination variables.

Table of Contents Placeholder

Prerequisites

• jQuery
  Ensure that your site has jQuery installed on it. If you are not using jQuery, you can add and configure a new jQuery tag from the Tealium iQ’s tag Marketplace.
• Adobe Marketing Cloud ID Service Tag
  The Adobe Cloud Service generates a unique ID for every visitor on your site and persists the ID across all their Marketing Cloud Solutions, thus preventing duplicate counts. Add and configure the tag in your profile, if you have not already done and enable the bundle flag setting for the tag so that it can be bundled into utag.js on all pages.
• AppMeasurement JavaScript Tag
  Add and configure the tag in the same profile and enable the bundle flag, if you have not done so already. This is required for JavaScript implementations. Bundling is only required for Tag version 1.6.3, as the prior versions already have the Marketing Cloud Service bundled by default.
  

  In the Tags tab, ensure that the bundled Marketing Cloud ID tag is placed above the bundled Appmeasurement tag. This ensures the Marketing Cloud ID tag will load first. 

Supported Vendor Libraries

• Adobe Heartbeat v2.0.2
• Adobe Heartbeat v1.6.7
• Adobe Heartbeat v1.6.7 with Nielsen v5.0 integration 

Adding and Configuring

Step 1. Add the Tag to your Tealium iQ Profile

This tag is available in the Tealium Tag Marketplace. Refer to the Tags Tab article to learn how to add a tag to your Tealium iQ profile.

Step 2. Configure the Tag Settings

You may either hard code the field values or set them dynamically using the Data Mappings toolbox. Set the values as follows:

Field Name	Field Value
Title	Enter a unique name to identify the tag. This is important if you are adding multiple instances of this tag. This is a required field
Tracking Server	Enter the server URL where all heartbeat tracking calls are sent. If you do not have the URL, contact your Adobe representative. This is a required field
Publisher	Enter your publisher name as assigned by your Adobe representative. This is a required field
Use SSL	This flag determines whether or not to send heartbeat calls over HTTPS. The default value is  False, meaning SSL is disabled. You may toggle the value to  True" if you prefer the tracking calls are sent securely.
S-Object Name	Set your own custom s-object variable name. If you are unsure, use the default value of s. This is a required field
Video Platform Name	Enter the name of the online platform that is rendering your video content.
Video Platform Name	Enter the version of the video player app/SDK.
Tag Version	This drop-down list allows you to choose Adobe Heartbeat tracking with or without Nielsen integration. The available options are: Adobe Heartbeat 2.0.2 (default) Adobe Heartbeat 1.6.7  Adobe Heartbeat 1.6.7 with Nielsen 5.0

Configuring Nielsen with Adobe Heartbeat

The fields described in the following table are only required if you set the tag version to Adobe Heartbeat 1.6.7 with Nielsen 5.0.

If you do not have the required Nielsen values, contact your Nielsen or Adobe representative.

Field Name	Field Value
Adobe Nielsen SDK Configuration Key	Enter the Nielsen configuration key
Nielsen Collection Environment	Enter the location of Nielsen's collection environment
Nielsen Player ID	Enter the unique identifier assigned to the video player
Nielsen APN	Enter a description for the player/site
Nielsen Client ID	Enter your Nielsen client identifier
Nielsen VCID	Enter the video channel identifier

Step 3. Apply Load Rules

Load Rules determine when and where to load an instance of this tag on your site. The Load on All Pages rule is the default load rule. To load this tag on a specific page, create relevant rule conditions to apply to the tag.

Best Practice: Create and apply custom rules to load this tag on any pages where the videos are made available.

Step 4. Set up Data Mappings

Mapping is the simple process of sending data from a Variable, in your data layer, to the matching destination variable of the vendor tag. The destination variables for Adobe Heartbeat tag are available in the Data Mapping toolbox and grouped in different categories.

For instructions on how to map a Variable to a tag destination, see Mapping Variables.

Standard

The Standard category corresponds to the configuration fields for the tag. If desired, you can map to these destinations. Dynamically send values for the tag fields that are left blank or override the current values.

Destination Name	Description
Adobe Heartbeat Tracking Server tracking_server	URL of the server where all heartbeat tracking calls are sent
Adobe Heartbeat Publisher publisher	Publisher name as assigned by your Adobe representative
Adobe Heartbeat SSL Flag ssl	Boolean flag that determines whether or not to send heartbeat calls over HTTPS. Ensure the Variable you are mapping is populated with a Boolean value, either "true" or "false". Mapping also overrides the current drop-down selection.
Adobe Heartbeat Channel syndication_channel	Name of the channel syndication
Adobe Heartbeat Video Platform Name  online_video_platform_name	Name of the online platform that is rendering your video content
Adobe Heartbeat Player SDK player_sdk	Version of the video player app/SDK
Adobe Heartbeat Debug Logging Flag debug_logging	Boolean flag to enable/disable logging of each component within the Heartbeat plugin. Adobe recommends disabling this flag for the production version of your player because active logging impacts performance.

Mapping Nielsen Variables

Required only if Adobe Heartbeat 1.6.7 with Nielsen 5.0 is selected in the Tag Version drop-down list.

Destination Name	Description
Adobe Nielsen SDK Configuration Key nielsen_config_key	Nielsen configuration key to integrate with Adobe Heartbeat
Nielsen Client ID nielsen_client_id	Your Nielsen client identifier
Nielsen VCID nielsen_vcid	Video channel identifier
Nielsen Collection Environment nielsen_collection_environment	Location of Nielsen's collection environment
Nielsen Player ID nielsen_player_id	The unique identifier for the video player
Nielsen APN nielsen_apn	Description of the player/site, expressed as a string value
Nielsen Device ID nielsen_device_id	Unique identifier of mobile/tablet where you wish to track the video
Nielsen SDK Debug Flag nielsen_sdk_debug	Boolean flag to enable/disable logging of the Nielsen integration
Nielsen Opt Out Flag nielsen_opt_out	Disable all Nielsen tracking for the current visitor Requires triggering the "opt-out" event

Video Events

Video event destinations are event listeners that trigger when a certain action or change occurs in the video player. To trigger an event, you must map your variable to the desired event in the toolbox and set the value of the variable as the trigger. The mapped event will fire when the supplied trigger value is found in the data layer.

To begin, use the following steps to map an event:

1. Select an event from the drop-down list.
2. In the Trigger field, enter the value of the variable being mapped.
   

   

3. The event will trigger when this value is found on the page.
   

   

4. To map more events, click the + button and repeat Steps 1 and 2.
5. Click Apply.

The following tables lists the available event destinations:

Destination Name	Description
Video Load video_load	Indicates the video is ready to be played
Video Start video_start	Indicates the video has started playing, possibly after one of the following three (3) scenarios: initial loading buffering ad display
Video Playing video_playing	Indicates that the video is currently playing Use to update QoS data Should not be called when ads are playing
Video Pause video_pause	Indicates that video was paused
Video Play video_play	Indicates that the video is playing, possibly after the buffering or seeking has completed
Video Stop video_stop	Indicates that the video has been manually stopped
Video Resume video_resume	Indicates the viewer has unpaused the video to resume playing
Video Complete video_complete	Indicates that the video has ended
Video Seek video_seek	Indicates the viewer has started seeking the video
Video Buffer video_buffer	Indicates the video has started buffering
Video Skip video_skip	Indicates the viewer has skipped the video or ad
Video Error video_error	Indicates the video has encountered an error
Nielsen Opt Out Status Change nielsen_opt_out_status_changed	Indicates the viewer has switched from opt-in to opt-out OR vice versa.

Video

These destinations correspond to the Adobe Video Measurement parameters.

Destination Name	Description
Video Title video.title	Name of the video being tracked
Video Length video.length	The duration (in seconds) of the video asset
Video Current Playhead video.current_playhead	The current position of the player (in seconds) in the video, excluding ad content
Video Stream Type video.stream_type	Type of the video asset
Video Is Full Episode video.is_full_episode	Boolean flag to indicate if the video content is a full episode ("Y") or a partial clip ("N")
Video Original Air Date For Nielsen video.original_air_date_nielsen	The original air date of the episode, format YYYYMMDDHH24:MI:SS
Video Channel Name video.channel_name	Name of the program or feed being sent
Video Series Name video.series_name	Name of the program (series name) being viewed
Video Player Name video.player_name	Name of the video player that is playing the content
Video Is Ad video.is_ad	Boolean value to indicate whether or not the video is an advertisement
Video FPS video.fps	The frame rate of the media, in frames per second
Video Bitrate video.bit_rate	The bits per second attribute of the video content
Video Startup Time video.startup.time	The start time, in seconds, of the video content
Video Dropped Frames video.dropped_frames	The sum of all frames dropped during a playback session
Video Error ID video.error_id	The ID of the error encountered during playback
Video Error Is Fatal video.error_is_fatal	Boolean value to indicate whether or not the error prevents playback from continuing

Chapter

These destinations correspond to Adobe Video Chapter Parameters.

Destination Name	Description
Chapter Name  chapter.name	Name of the individual chapters
Chapter Length chapter.length	Total duration of the chapter in seconds
Chapter Position chapter.position	Position of the chapter inside the video content
Chapter Start Time chapter.start_time	The offset inside the main content where the chapter starts.
Chapter Custom Metadata chapter_meta_data.custom	Additional custom value related to the chapter

Ad

These destinations correspond to Adobe Video Ad Parameters.

Destination Name	Description
Ad Break Name adbreak.name	The name of the individual cad breaks
Ad Break Position adbreak.position	The position (index) of the ad break inside the video content Required when the video.is_ad flag is set to True
Ad Break Start Time dbreak.start_time	The offset inside the main content where the ad break starts
Ad ID ad.id	Unique identifier of the ad being displayed
Ad Title ad.title	Name of the ad
Ad Type ad.type	Type or category of the ad
Ad Length ad.length	Total duration of the ad (in seconds)
Ad Position ad.position	The position (index) of the ad inside the video content Required when the video.is_ad flag is set to True

Video Metadata

These destinations correspond to Adobe Standard Metadata Parameters.

Destination Name	Description
Video Custom Metadata meta_data.custom	Additional custom value related to the video
Video Metadata Show meta_data.show	Name of the show
Video Metadata Season meta_data.season	The season number
Video Metadata Episode meta_data.episode	The episode number
Video Metadata Asset meta_data.asset	The video asset identifier also known as TMS ID (Tribune Media Service)
Video Metadata Genre meta_data.genre	Genre of the video content
Video Metadata Air Date meta_data.airDate	The date on which the asset was first aired on TV
Video Metadata Digital Air Date meta_data.digitalDate	The date on which the asset was first available as digital
Video Metadata Rating meta_data.rating	Ratings available for the video content
Video Metadata Originator meta_data.originator	Name of the video originator
Video Metadata Network meta_data.network	The name of the network associated with the show
Video Metadata Type meta_data.type	Type of the show
Video Metadata Ad Load meta_data.adLoad	Metadata for the ad load
Video Metadata Day Part meta_data.dayPart	The day part for which the ad display is scheduled
Video Metadata Feed meta_data.feed	The type of programming feed
Video Metadata Format meta_data.format	Stream format of the video

Ad Metadata

These destinations correspond to Adobe Standard Ad Metadata Parameters.

Destination Name	Description
Ad Custom Metadata ad_meta_data.custom	Additional custom value related to the ad being displayed
Ad Metadata Advertiser ad_meta_data.advertiser	Name of the company/brand that is displaying the ad
Ad Metadata Campaign ad_meta_data.campaign	Ad campaign Identifier
Ad Metadata Creative ad_meta_data.creative	Creative asset for rendering the ad
Ad Metadata Placement ad_meta_data.placement	Metadata related to the position of the ad inside the video
Ad Metadata Site ad_meta_data.site	Site associated with the ad
Ad Metadata Creative URL ad_meta_data.creativeURL	URL of the ad being displayed

Step 5. Save and Publish

That's it! You have successfully set up the tag in your profile.

Built-in Video Data Layer Variables

If your data layer is already using these values, then mapping is not required, as Tealium typically sends data to the matching tag destinations. If your data layer uses different variables names from those listed in this table, then you will need to manually map.

Built-in Variables	Toolbox Destination Variable	Description
event_name	Video Event destinations	If you use any of the following values in your event_name variable, you do not need to map again in the toolbox. Value Is Sent To load video_load start video_start playing video_playing pause video_pause play video_play stop video_stop resume video_resume complete video_complete seek video_seek buffer video_buffer optstatus Nielsen_opt_out_status_changed
video_id	--	Unique identifier of the video
video_name	Video Title video.title	Name of the video being tracked
video_length	Video Length video.length	The duration (in seconds) of the video asset
video_player_name	Video Player Name video.player_name	Name of the video player that is playing the content
video_current_playhead	Video Current Playhead video.current_playhead	The current position of the player (in seconds) in the video, excluding ad content
video_stream_type	Video Stream Type video.stream_type	Type of the video assest
video_fps	Video FPS video.fps	The frame rate of the media, in frames per second
video_bitrate	Video Bitrate video.bit_rate	The bits per second attribute of the video content
video_dropped_frames	Video Dropped Frames video.dropped_frames	The sum of all frames dropped during a playback session
video_is_ad	Video Is Ad video.is_ad	Boolean value to indicate whether or not the video is an advertisement
video_ad_position - OR - video_ad_pod_position	Ad Position ad.position	The position (index) of the ad inside the video content Required when the video.is_ad flag is set to true
video_chapter_name	Chapter Name chapter.name	Name of the individual chapters
video_chapter_length	Chapter Length chapter.length	Total duration of the chapter in seconds
video_chapter_position	Chapter Position chapter.position	Position of the chapter inside the video content
video_chapter_start_time	Chapter Start Time chapter.start_time	The offset inside the main content where the chapter starts.
video_ad_pod_name	Ad ID ad.id	Unique identifier of the ad being displayed
program	Video Series Name video.series_name	Name of the program (series name) being viewed
is_full_episode	Video Is Full Episode video.is_full_episode	Boolean flag to indicate if the video content is a full episode ("Y") or a partial clip ("N")
original_air_date	Video Original Air Date For Nielsen video.original_air_date_nielsen	The original air date of the episode, in the following format: YYYYMMDDHH24:MI:SS

Validation

The Hearbeat tag is event-based and leverages the utag.track("video", data) call to differentiate itself from other utag calls. For this reason, it is crucial to properly set up the video event triggers in the Data Mapping toolbox.

Once configured, the tag will fire continuously every second in order to keep the video data current. This is accomplished by firing the "playing" event within your video player's "playing" event handler. Other video events should also be fired via their corresponding Adobe heartbeat events. Network calls are aggregated and reported to Adobe every 10 seconds; including those for event changes.

An easy way to set both the Heartbeat and Nielsen debug flags is by adding a querystring parameter to the URL of the video page. For example: adobe_debug=1&Nielsen=1


You can then add the Query parameter variables to your data layer in Tealium iQ and map them accordingly.

Mapping destinations for both the Heartbeat and Nielsen debug flags are available under the Standard category (see "Adobe Heartbeat Debug Logging Flag" and "Nielsen SDK Debug Flag").

When complete, you can run the following Tealium debug command in your browser console. 
document.cookie = "utagdb=true";

Sample Implementation

The following screenshots show  network calls for a sample Heartbeat implementation. Primary parameters to note are s:event:type and s:asset:type. These parameters, respectively, indicate the type of video event and which video component it pertains to. The following screenshot shows the beginning of the main video before the ad display. The l:event:playhead, also shown, refers to the elapsed time on the main video.

The network call looks for the ad display, as follows:

The s:asset:type value equals ad and the l:event:playhead value is  8. This means that the ad started playing at ewight (8) seconds into the video.

Vendor Documentation

• About Adobe Video Heartbeat
• Video Heartbeat Library Configuration
• Nielsen appinfo Parameters
• Video Measurement Parameters
• Metadata Parameters
• Video Player Events