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 Android (Kotlin) Media sample app to help familiarize yourself with the Tealium library, tracking methods, and best practice implementation.

Install

Install the Media module using Maven (recommended) or manually.

Maven

To install the module using Maven:

In your project’s top-level build.gradle file, add the following Maven repository:
```
maven {
      url "https://maven.tealiumiq.com/android/releases/"
}
```

In your project module’s build.gradle file, add the Maven dependencies for the Tealium library and Crash Reporter:

dependencies {
    implementation 'com.tealium:kotlin-core:1.5.5'
    implementation 'com.tealium:kotlin-media:1.1.1'
}

Manual

To install the module manually:

Download the Tealium Media module.
Copy the file tealium-kotlin.media-1.1.1.aar into your project’s <PROJECT_ROOT>/<MODULE>/libs directory.

Add the Tealium library dependency to your project module’s build.gradle file:

dependencies {
    implementation(name:'tealium-kotlin.media-1.1.1', ext:'aar')
}

Initialize

To initialize the Media module, create a MediaContent object.

For example:

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
)

Learn more about implementing the Media module.

Metadata

To add optional metadata to the 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

After installing the Media module, track your media events.

Media Session

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

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

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:

tealium?.media?.play()

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

tealium?.media?.pause()

Learn more about tracking player events.

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.

For example:

val chapter1 = Chapter(name = "Chapter 1", duration = 120)
tealium?.media?.startChapter(chapter1)
// ...
tealium?.media?.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.

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

Learn more about tracking ads.

Examples

Chapters and Ads

The following example tracks media content with chapters and ads:

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

tealium?.media?.startSession(mediaContent)
tealium?.media?.startAdBreak(AdBreak("Ad Break 1"))
tealium?.media?.startAd(Ad("Ad  1"))
// ...
tealium?.media?.endAd()
tealium?.media?.startAd(Ad("Ad  2"))
tealium?.media?.endAd()
tealium?.media?.endAdBreak()
tealium?.media?.startChapter(Chapter("Chapter 1"))
tealium?.media?.endChapter()
tealium?.media?.startAdBreak(AdBreak("Ad Break 2"))
tealium?.media?.startAd(Ad("Ad  3"))
// ...
tealium?.media?.endAd()
tealium?.media?.endAdBreak()
tealium?.media?.startChapter(Chapter("Chapter 2"))
tealium?.media?.endChapter()
tealium?.media?.startChapter(Chapter("Chapter 3"))
tealium?.media?.startBuffer()
tealium?.media?.endBuffer()
tealium?.media?.endChapter()
tealium?.media?.endContent()
tealium?.media?.endSession()

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.

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