Media Module | Modules | Tealium Docs

The Media module tracks streaming media in apps through the use of custom events. Learn more about media tracking.

Sample App

Explore the iOS (Swift) Media sample app to help familiarize yourself with the Tealium library, tracking methods, and best practice implementation.

Install

Install the Media module with Swift Package Manager, CocoaPods or Carthage.

Swift Package Manager (Recommended)

Supported in version 1.9.0+, the Swift Package Manager is the recommended and simplest way to install the Tealium Swift library:

In your Xcode project, select File > Add Package Dependencies.
Enter the repository URL: https://github.com/tealium/tealium-swift
Configure the version rules. Typically, "Up to next major" is recommended. If the current Tealium Swift library version does not appears in the list, then reset your Swift package cache.
Select the Media module from the list of modules to install and add it each of your app targets in your Xcode project, under Frameworks and Libraries

Learn more about the Swift Package Manager installation for iOS.

CocoaPods

To install the Media module with CocoaPods, add the following pod to your Podfile:

pod 'tealium-swift/Media'

Learn more about the CocoaPods installation for iOS.

Carthage

To install the Media module with Carthage, following these steps:

Go to the app target’s General configuration page in Xcode.
Add the following framework to the Embedded Binaries section:

TealiumMedia.framework

Learn more about Carthage installation for iOS.

Initialize

To initialize the Media module, create a MediaContent object.

For example:

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

Learn more about implementing the Media module.

Metadata

To add optional metadata to the media session:

metadata: ["artist": "various", "duration": "45:00"]

To add chapter metadata:

metadata: ["artist": "Aerosmith", "track": "5"]

To add merged metadata:

metadata: ["artist": "Aerosmith", "track": "5", "duration": "45:00"]

Learn more about metadata.

Track

There are many methods and properties available to track media.

Media Session

To start tracking a media session, call the startSession() method. To stop tracking a media session, call the endSession() method:

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

Learn more about tracking sessions.

Player Events

To track media player events such as play and pause, call the appropriate player event methods. Each media player event sends a tealium_event variable to the data layer when called.

To track when the media is played, call the play() method:

session.play()

To track when the media is paused, call the pause() method:

session.pause()

Chapters

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

let chapter1 = Chapter("Chapter 1", 120)
mediaSession.startChapter(chapter1)
// ...
mediaSession.endChapter()

Learn more about tracking chapters.

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.

let adBreak = AdBreak("Ad Break 1")
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()

Learn more about tracking ads.

Examples

Chapters and Ads

The following example tracks media content with chapters and ads:

let qoe = QoE(bitrate: 1500)

let mediaSession = tealium?.media?.createSession(from: MediaContent(
  name: "What is the Tealium Customer Data Hub?",
  trackingType: .fullPlayback
  streamType: .vod,
  mediaType: .video,
  qoe: qoe,
  duration: 114
))

mediaSession.startSession()
let adBreak = AdBreak("Ad Break 1")
mediaSession.startAdBreak(adBreak)
let ad = Ad("Ad 1")
mediaSession.startAd(ad)
// ...
mediaSession.endAd()
let secondAd = Ad("Ad 2")
mediaSession.startAd(secondAd)
mediaSession.endAd()
mediaSession.endAdBreak()
let chapterOne = Chapter("Chapter 1")
mediaSession.startChapter(chapterOne)
mediaSession.endChapter()
let adBreak = AdBreak("Ad Break 2")
mediaSession.startAdBreak(adBreak)
let thirdAd = Ad("Ad 3")
mediaSession.startAd(thirdAd)
// ...
mediaSession.endAd()
mediaSession.endAdBreak()
let chapterTwo = Chapter("Chapter 2")
mediaSession.startChapter(chapterTwo)
mediaSession.endChapter()

let adBreak = AdBreak("Ad Break 3")
mediaSession.startAdBreak(adBreak)
let fourthAd = Ad("Ad 4")
mediaSession.startAd(fourthAd)
mediaSession.endAd()
let fifthAd = Ad("Ad 5")
mediaSession.startAd(fifthAd)
mediaSession.endAd()
mediaSession.endAdBreak()
let chapterThree = Chapter("Chapter 3")
mediaSession.startChapter(chapterThree)
mediaSession.startBuffer()
mediaSession.endBuffer()
mediaSession.endChapter()
mediaSession.endContent()  // end of all content and ads
mediaSession.endSession()  // end of session

Session Abandonment

The following example shows when the user abandons the session, the app is backgrounded and media stops playing. With the Media module enabled, the endSession() method is triggered after 1 minute before the session is terminated. When the user opens the app again, the media session resumes.

let media = MediaContent(
  name: "What is the Tealium Customer Data Hub?",
  trackingType: .fullPlayback
  streamType: .vod,
  mediaType: .video,
  qoe: QoE(bitrate: 1500),
  duration: 114
)
let mediaSession = tealium?.media?.createSession(from: media)                                
mediaSession.startSession()
let adBreak = AdBreak("Ad Break 1")
mediaSession.startAdBreak(adBreak)
let ad = Ad("Ad 1")
mediaSession.startAd(ad)
// ...
mediaSession.endAd()
let secondAd = Ad("Ad 2")
mediaSession.startAd(secondAd)
mediaSession.endAd()
mediaSession.endAdBreak()
mediaSession.play()
// app goes into background and media does not continue playing
mediaSession.pause()
// Tealium's background media tracking is enabled, so the endSession is triggered after 1 minute
// User opens app again, and media continues
mediaSession.resumeSession() // resume event
let adBreak = AdBreak("Ad Break 2")
mediaSession.startAdBreak(adBreak)
// User closes app - session abandoned (no endContent event)
mediaSession.endSession() // end of session