Logo

Advanced topics

How to implement the In The Game (ITG) SDK for MediaTailor

This implementation provides a seamless integration between AWS MediaTailor's server-side ad insertion (SSAI), Datazoom's event detection, and In The Game's (ITG) interactive overlay capabilities.

To review complete examples, sample apps, and the full list of available configurations, refer to the ITG Documentation V2.7.

Part 1: Event Detection and Triggering Concept

Overview

The integration uses a two-SDK approach: the Datazoom SDK acts as the event detection layer, and the ITG SDK handles the interactive overlay rendering. The flow works as follows:

  1. Datazoom SDK attaches to the MediaTailor session for tracking and analytics—firing all required tracking beacons independently.

  2. ITG Glue module binds to the same MediaTailor session, managing overlay scheduling internally.

  3. ITG SDK renders the interactive in-content overlay (pause ad, squeezeback, or L-banner) at the precisely correct moment.

  4. Automatic Cleanup occurs when the session ends or the playback screen is dismissed, seamlessly detaching both integrations.

Event Detection Flow

1MediaTailor Session created2       ↓3Datazoom Tracking Setup (datazoomAdapter.setupAdSession) 4ITG Binding (session.attachITG / session.addAdObserver)5       ↓6ITG manages overlay scheduling internally7       ↓8Overlay rendered when ad break is detected9       ↓10Overlay dismissed, video restored

Integration Model by Platform

  • Android: ITG encapsulates ad scheduling entirely. The developer calls session.attachITG(mITGComponent) once. ITG observes the MediaTailor session internally via onNewNonLinearAd and handles all overlay timing.

  • iOS: ITG uses an explicit ad observer pattern. ITGDatazoomPlugin is registered on the session via session.addAdObserver(adObserver: datazoomPlugin). Internally, the plugin observes onNewNonLinearAds and forwards the ad data to the ITG overlay.

Part 2: Code Implementation Examples

Android Integration

3.1 Add the ITG repository In your settings.gradle / settings.gradle.kts, add the ITG Android repository:

1// Groovy / Kotlin DSL2dependencyResolutionManagement {3    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)4    repositories {5        google()6        mavenCentral()7        maven {8            url = uri("[https://androidrepo.internal.inthegame.io/repository/android/](https://androidrepo.internal.inthegame.io/repository/android/)")9        }10    }11}

3.2 Add the Datazoom integration dependency In your app-level build.gradle / build.gradle.kts:

1// Groovy / Kotlin DSL2dependencies {3    // … your existing dependencies4 5    // ITG ⇄ Datazoom glue module6    implementation("io.inthegame.sdk:datazoom:2.7.0.1")7}

  1. Wire Datazoom and ITG in Your MediaTailor Flow

4.1 Import the glue helper

1import io.inthegame.datazoom.ITGDatazoomUtil.attachITG

Note: attachITG is an extension function on the MediaTailor Session object. It binds the session to your already-initialized ITGPlaybackComponent.

4.2 Attach ITG in the MediaTailor session callback In your component that creates the MediaTailor session:

1MediaTailor.createSession(config) { session, contentUrl ->2    session?.let {3        // 1) Connect MediaTailor session to Datazoom4        datazoomAdapter?.setupAdSession(session, surfaceView, contentUrl)5 6        // 2) Apply Glue: bind ITG to the MediaTailor session7        //    mITGComponent must be your already-initialized ITGPlaybackComponent8        session.attachITG(mITGComponent!!)9 10        // 3) Start playback using session.playbackUrl11        //    e.g. exoPlayer.setMediaItem(MediaItem.fromUri(session.playbackUrl))12        //         exoPlayer.prepare()13        //         exoPlayer.play()14    }15}

iOS / tvOS Integration

  1. Add the Datazoom–ITG Glue Package In Xcode, navigate to File → Add Package Dependencies… and add the ITG Apple SDK Swift package:

1[https://github.com/Inthegamesdk/itg-apple-sdk.git](https://github.com/Inthegamesdk/itg-apple-sdk.git)

In the package selection screen, add ITGDatazoom as a product to your playback target.

  1. Wire Datazoom and ITG in Your MediaTailor Flow

4.1 Import the glue module In the playback component that handles your MediaTailor session (e.g., PlayerViewController):

1import ITGDatazoomPlugin

Note: attachITG is an extension function on the MediaTailor Session object. It binds the session to your already-initialized ITGPlaybackComponent.

4.2 Attach ITG in the MediaTailor session callback

1MediaTailor.shared.createSession(config: config, callback: { [weak self] session, error in2    guard let self = self else { return }3 4    if let session = session {5        self.session = session6 7        // 1) Create the Datazoom–ITG glue plugin,8        //    passing your ITG overlay as the flexi delegate9        self.datazoomPlugin = ITGDatazoomPlugin(flexiDelegate: self.overlayView)10 11        // 2) Register the plugin as an ad observer on the MediaTailor session12        self.session?.addAdObserver(adObserver: self.datazoomPlugin)13 14        // 3) Create the Datazoom context and configure the ad session15        self.dzAdapter = Datazoom.shared.createContext(player: self.player)16        self.dzAdapter?.configureAdSession(17            adSession: session,18            videoUrl: dataZoomDataUrl,19            videoPlayerView: self.videoView20        )21    }22 23    // 4) Start playback using session.playbackUrl24    if let url = session?.playbackUrl {25        self.player.startVideo(URL(string: url)!)26    }27})

  1. Stop / Cleanup

Remove the ad observer when leaving the playback screen (e.g., in viewWillDisappear):

1override func viewWillDisappear(_ animated: Bool) {2    super.viewWillDisappear(animated)3    session?.removeAdObserver(adObserver: datazoomPlugin)4}

Key Implementation Notes

  • Initialization Order: The ITG overlay view must be initialized and loaded before the MediaTailor session callback fires. The glue module requires the overlay reference at construction time.

  • Same Player Instance: Both the ITG component and the Datazoom adapter must be bound to the identical player instance (ExoPlayer on Android, AVPlayer on iOS).

  • Tracking Accuracy: Datazoom fires all MediaTailor tracking beacons. ITG independently fires VAST impression/tracking beacons specifically for the overlay creative. Both systems operate in parallel with no event duplication.

  • SSAI & SegmentationTypeId 52: When MediaTailor receives a SCTE-35 signal with SegmentationTypeId 52, it does not stitch a replacement clip. Instead, it signals the client to render a client-side overlay. Datazoom detects this signal, and ITG subsequently renders the appropriate ad format (pause ad, squeezeback, or L-banner based on the VAST response).

  • Cleanup: Always execute cleanup routines (removeAdObserver on iOS or let the ITG component handle session detachment on Android) when tearing down playback to avoid phantom overlay events in future sessions.

Next
Overview