Adobe Heartbeat Tag Setup Guide for Tealium iQ

Adobe Heartbeat Tag Setup Guide for Tealium iQ

by on ‎11-15-2016 05:11 PM - edited on ‎09-12-2018 05:40 PM by (1,568 Views)

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 Enterprise 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 Enterprise 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 Enterprise Cloud Service bundled by default.

    In the Tags tab, ensure that the bundled Enterprise Cloud ID tag is placed above the bundled Appmeasurement tag. This ensures the Enterprise 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.

Tag Marketplace_Adobe Heartbeat.jpg

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.

mapping toolbox.png

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.
    map event_load js to destiniations.jpg
  3. The event will trigger when this value is found on the page.
    map event_load UDO variable to video_load.jpg
  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.

completedmappings.png

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 asset
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.

mainstart.pngThe 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 eight (8) seconds into the video.

adstart.png

Vendor Documentation