Media Tracking

Media tracking is the ability to track streaming media events (video or audio) in apps. Streaming media events include sessions, chapters, advertisements (ads), and player events such as play, seek, and pause. Install the Media module to add this tracking capability to your iOS or Android app then implement the media tracking methods.

How It Works

The Media module supports the tracking of a user’s entire streaming media experience. This includes the start and end of the session, the start and end of ad breaks, and every interaction with the media player such as play, pause, and seek.

The Media module structures the tracking in a hierarchy of the following elements:

Media Session
A media session is a container for all of the other elements and it defines the general information about the streaming experience. A media session is a required element for tracking.

Chapter
A chapter is an optional segment that separates the session as breaks occur in the content, such as chapters of an audiobook or scenes of a movie.

Ad Break
An ad break is an optional container for one or more ads. An ad break is commonly positioned at the start, middle, or end of a session.

Ad
An ad is an optional element that occurs within an ad break.

Example structure of a media session:

└── Media Session
    ├── Ad Break 1
    │   ├── Ad 1
    │   └── Ad 2
    ├── Chapter 1
    ├── Ad Break 2
    │   ├── Ad 3
    │   └── Ad 4
    └── Chapter 2

Install

To get started, install the Media module for one of the supported platforms:

• Android (Kotlin)
• iOS (Swift v2.x)

Initialize

After you install the Media module, initialize a MediaContent object:

val mediaContent: MediaContent = MediaContent(
  name = "What is the Tealium Customer Data Hub?",
  trackingType = TrackingType.MILESTONE,
  streamType = StreamType.DVOD,
  mediaType = MediaType.VIDEO,
  qoe = QoE(1500),
  duration = 130
)

let media = MediaContent(
  name: "What is the Tealium Customer Data Hub?",
  trackingType: .milestone,
  streamType: .vod,
  mediaType: .video,
  qoe: QoE(bitrate: 1500),
  duration: 130
)

TrackingType

The tracking type determines which media events to track as Tealium events. (See Tracking Type Overview.)

Use one of the following constants to set TrackingType:

StreamType

Use one of the following constants to set StreamType:

MediaType

The following are the MediaType constants:

State

Player state tracking captures the mode of the video player during playback, such as full screen mode, closed captions, or muted volume. The player state is set to the data layer variable media_player_state.

Example of tracking change in player state:

tealium?.media?.updatePlayerState(STATE_CONSTANT_VALUE)

mediaSession.playerState = STATE_CONSTANT_VALUE

Use one of the following constants to set State:

Quality of Experience

The quality of experience for the media session, which is set to the bitrate in kilobits per second (kbps). If the current bitrate value is available during media playback, provide it as the qoe variable when initializing the MediaContent object. Setting the quality of experience triggers the media_bitrate_change tealium event.

Example of tracking quality of experience:

tealium?.media?.updateQOE(BITRATE_VALUE)

mediaSession.bitrate = BITRATE_VALUE

Metadata

Metadata is a parameter that sets additional information about an object. When you pass metadata to the object, those key-value pairs are also set in the data layer. The following objects accept metadata: MediaContent, Chapter, QoE.

Since metadata can be set in multiple objects, it’s possible to set the same metadata key multiple times. To resolve conflicting metadata keys in the data layer, the metadata from multiple objects are merged into the data layer using the object hierarchy: MediaContent > Chapter > QoE.

For example, if you set feed_type in both MediaContent and Chapter, the value from the Chapter metadata will override the value from the MediaContent metadata in the final data layer.

Example of setting metadata:

val mediaContent: MediaContent = MediaContent(
    // ...
    metadata = mutableMapOf("episode" to "2", "network" to "YouTube")
)

let media = MediaContent(
    // ...
    metadata: ["episode": "2", "network": "YouTube"]
)

Video Metadata Keys

The following are examples of common video metadata keys:

Audio Metadata Keys

The following are examples of common audio metadata keys:

Tracking Type Overview

The tracking type determines which Tealium events are triggered. Choose a tracking type based on the level of events you want to trigger.

For example, if you implement all the tracking methods and use summary tracking, only the media_session_end event is triggered.

Full Playback Events

Use full playback tracking to tracks all media events, excluding interval events.

Tracked events include:

• Session events:
  • media_session_start
  • media_session_resume
  • media_session_end
• Ad break events:
  • media_adbreak_start
  • media_adbreak_end
• Ad events:
  • media_ad_start
  • media_ad_end
  • media_ad_click
  • media_ad_skip
• Chapter events:
  • media_chapter_start
  • media_chapter_skip
  • media_chapter_end
• Buffer events:
  • media_buffer_start
  • media_buffer_end
• Player events:
  • media_play
  • media_pause
  • media_seek_start
  • media_seek_end
• Other events
  • media_bitrate_change

Interval Events

Use interval tracking to track the status of the media player at a recurring interval. When this type is used the ping() method is called every 10 seconds to check if content is playing, which sets tealium_event to media_interval in the data layer.

Tracked events include:

• Session events:
  • media_session_start
  • media_session_resume
  • media_session_end
• Player events:
  • media_play
  • media_pause
• Interval events:
  • media_interval

Milestone Events

Use milestone tracking to track when a percentage of the content has been played. The sendMilestone() method is called automatically when each milestone percentage is reached, which sets tealium_event to media_milestone in the data layer.

The following milestone percentages are tracked:

Tracked events include:

• Milestone events:
  • media_milesetone
• Session events:
  • media_session_start
  • media_session_resume
  • media_session_end
• Player events:
  • media_play
  • media_pause
  • media_seek_start
  • media_seek_end
• Ad break events:
  • media_adbreak_start
  • media_adbreak_end

Interval Milestone Events

Use interval milestone tracking to track both interval and milestone events.

Summary Events

Use summary tracking to send a single summary event when the session ends. The session summery event includes calculations for the duration of played content and ads.

Summary events include:

• Session events:
  • media_session_start
  • media_session_end

See the full list of all media summary variables that are tracked.

Comparison Chart

For a full list of the available media events, see the Track section.

Track

After you initialize the MediaContent object, use the following methods to track media interactions.

Media Sessions

A media session is the entire media content containing chapters, ad breaks, ads, and media player events.

To start tracking a media session call the startSession() method with a MediaContent object. To stop tracking a media session call the endSession() method.

Starting a session does not imply a play() event.

Example:

tealium?.media?.startSession(mediaContentObject)
//...
tealium?.media?.endSession()

let mediaSessionObject = tealium?.media?.createSession(
      from: mediaContentObject)                                
mediaSessionObject.startSession()
// ...
mediaSessionObject.end()

This table lists the values of tealium_event for each session tracking method:

Player Events

Media player events track interactions with the media such as play, seek, and pause.

This table lists the values of tealium_event for each player tracking method:

Chapters

Chapters are optional segments within the media session that represent breaks in the content such as chapters in an audiobook or scenes in a movie.

To track a chapter segment in the media session, create a Chapter object and pass it to the startChapter() method. To stop tracking the chapter, call the endChapter() method.

Example of tracking a chapter:

val chapterObject = Chapter(
  name = "What is the Tealium Customer Data Hub?",
  duration = 114
)
tealium?.media?.startChapter(chapterObject)
// ...
tealium?.media?.endChapter()

let chapterObject = Chapter(
  name: "What is the Tealium Customer Data Hub?",
  duration: 114
)
mediaSession.startChapter(chapterObject)
// ...
mediaSession.endChapter()

This table lists the values of tealium_event for each chapter tracking method:

Ads

An ad break is a sequence of one more ads.

To track the start of an ad break, create an AdBreak object and pass it to the startAdBreak() method. To track the start of an ad within the ad break, create an Ad object and pass it to the startAd() method.

To track the end of an ad, call the endAd() method. To track the end of the ad break, call the endAdBreak() method.

Example of tracking ad breaks and ads:

val adBreak = AdBreak(name = "Ad Break")
tealium?.media?.startAdBreak(adBreak)

val ad1 = Ad("Ad 1")
tealium?.media?.startAd(ad1)
tealium?.media?.endAd()

val ad2 = Ad("Ad 2")
tealium?.media?.startAd(ad2)
tealium?.media?.endAd()

tealium?.media?.endAdBreak()

val adBreak = AdBreak(name: "Ad Break")
session.endAdBreak(adBreak)

let ad1 = Ad("Ad 1")
session.startAd(ad1)
session.endAd()

let ad2 = Ad("Ad 2")
session.adStart(ad2)
session.endAd()

session.endAdBreak()

This table lists the values of tealium_event for each ad tracking method:

Data Layer

The Media module transmits different variables for each type of tracked event. The following sections list the data layer variables associated with each Tealium event.

The optional variables are only sent if they are defined.

Media Session Data

Tealium events: media_session_start, media_session_end

Chapter Data

Tealium events: media_chapter_start, media_chapter_end

Ad Break Data

Tealium events: media_adbreak_start, media_adbreak_end

Ad Data

Tealium events: media_ad_start, media_ad_end

Quality of Experience Data

Tealium events: media_bitrate_change

The quality of experience properties may be updated during the lifetime of the session if the quality changes or frames are dropped. The media_bitrate_change event is triggered every time the bitrate value is set.

Media Summary Data

Tealium events: media_session_end (when TrackingType is set to summary)