google · copybara-service · Jul 13, 2026
diff --git a/README.md b/README.md
@@ -20,6 +20,7 @@ repo to install.
 ## Available Skills
 
 <!-- BEGIN SKILLS -->
+
 - **Getting started with Google Cloud**
   -   [**Authenticating to Google Cloud**](./skills/cloud/google-cloud-recipe-auth)
   -   [**Google Cloud Recipe: Foundation Builder**](./skills/cloud/google-cloud-recipe-foundation-builder)
@@ -89,18 +90,19 @@ repo to install.
 - **Web and app hosting**
   -   [**Cloud Run Basics**](./skills/cloud/cloud-run-basics)
   -   [**Firebase Basics**](./skills/cloud/firebase-basics)
-- **Advertising**
-  -   [**AI Migration Agent Instructions for the Google Mobile Ads SDK**](./skills/ads/google-mobile-ads/google-mobile-ads-android-migrate-to-next-gen)
-  -   [**Data Manager API Audience Ingestion**](./skills/ads/data-manager-api/data-manager-api-audience-ingestion)
-  -   [**Data Manager API Event Ingestion**](./skills/ads/data-manager-api/data-manager-api-event-ingestion)
-  -   [**Data Manager API Setup**](./skills/ads/data-manager-api/data-manager-api-setup)
-  -   [**Google Ads API MCP Server Installation**](./skills/ads/google-ads-api/google-ads-api-mcp-setup)
-  -   [**Google Ads API Quickstart**](./skills/ads/google-ads-api/google-ads-api-quickstart)
-  -   [**Google Mobile Ads SDK - Banner Ads**](./skills/ads/google-mobile-ads/google-mobile-ads-banner)
-  -   [**Google Mobile Ads SDK - Install**](./skills/ads/google-mobile-ads/google-mobile-ads-get-started)
-  -   [**Google Mobile Ads SDK - Interstitial Ads**](./skills/ads/google-mobile-ads/google-mobile-ads-interstitial)
-  -   [**Google Mobile Ads SDK - Rewarded Ads**](./skills/ads/google-mobile-ads/google-mobile-ads-rewarded)
-  -   [**IMA SDK basics**](./skills/ads/interactive-media-ads/ima-sdk-basics)
+-   **Advertising**
+    -   [**AI Migration Agent Instructions for the Google Mobile Ads SDK**](./skills/ads/google-mobile-ads/google-mobile-ads-android-migrate-to-next-gen)
+    -   [**Data Manager API Audience Ingestion**](./skills/ads/data-manager-api/data-manager-api-audience-ingestion)
+    -   [**Data Manager API Event Ingestion**](./skills/ads/data-manager-api/data-manager-api-event-ingestion)
+    -   [**Data Manager API Setup**](./skills/ads/data-manager-api/data-manager-api-setup)
+    -   [**Google Ads API MCP Server Installation**](./skills/ads/google-ads-api/google-ads-api-mcp-setup)
+    -   [**Google Ads API Quickstart**](./skills/ads/google-ads-api/google-ads-api-quickstart)
+    -   [**Google Mobile Ads SDK - Banner Ads**](./skills/ads/google-mobile-ads/google-mobile-ads-banner)
+    -   [**Google Mobile Ads SDK - Install**](./skills/ads/google-mobile-ads/google-mobile-ads-get-started)
+    -   [**Google Mobile Ads SDK - Interstitial Ads**](./skills/ads/google-mobile-ads/google-mobile-ads-interstitial)
+    -   [**Google Mobile Ads SDK - Rewarded Ads**](./skills/ads/google-mobile-ads/google-mobile-ads-rewarded)
+    -   [**IMA SDK client-side**](./skills/ads/ima-sdk-client-side)
+    -   [**IMA SDK DAI Basics**](./skills/ads/ima-dai-sdk)
 - **Others**
   -   [**Getting Started with Google Analytics Admin API**](./skills/analytics/google-analytics-admin-api-basics)
   -   [**Getting Started with Google Analytics Data API**](./skills/analytics/google-analytics-data-api-basics)

diff --git a/skills/ads/ima-dai-sdk/SKILL.md b/skills/ads/ima-dai-sdk/SKILL.md
@@ -0,0 +1,89 @@
+---
+name: ima-dai-sdk
+description: >-
+  Integrates the Google Interactive Media Ads (IMA) DAI SDK into websites, web apps,
+  mobile apps, or TV apps for Google Dynamic Ad Insertion (DAI) with HLS or DASH streams.
+
+  Use when:
+  - Integrating the IMA DAI SDK for Google Dynamic Ad Insertion (DAI), Server-Side Ad Insertion (SSAI), Full Service DAI, or DAI Pod Serving redirect.
+  - Requesting HLS (.m3u8) or MPEG-DASH (.mpd) DAI streams on Web, Android, iOS/tvOS, or Roku platforms.
+
+  Don't use for:
+  - Client-side ad insertion (CSAI) with VAST and VMAP requests (use the `ima-sdk-client-side` skill instead).
+
+license: Apache-2.0
+metadata:
+  author: Google LLC
+  version: "1.0.0"
+---
+
+# IMA SDK DAI Basics
+
+The Google IMA DAI SDK lets you load a single stream containing both content and
+ads into websites, apps, TVs and other digital platforms. Use an IMA SDK to
+request an HLS or MPEG DASH stream from a video stitcher or stream origin.
+
+## Mandatory Prerequisites
+
+Correct integration requires identifying the streaming protocol, DAI type, and target platform up front. Review the relevant reference guides below to ensure proper setup:
+
+1.  **Identify the Streaming Protocol:**
+
+    *   **HLS (HTTP Live Streaming):** Stream URLs end in `.m3u8`. Read the [HLS Guide](references/hls.md).
+    *   **MPEG DASH:** Stream URLs end in `.mpd`. Read the [DASH Guide](references/dash.md).
+
+2.  **Identify the DAI Type:**
+
+    *   **Full Service DAI:** Request a Google DAI stream URL using an `assetKey` (Live) or `cmsId`/`videoId` (VOD). Read the [Full Service Guide](references/full-service.md).
+    *   **Pod Serving DAI:** Request a Google DAI `streamId` using an `assetKey`/`customAssetKey` (linear stream, livestream) or `cmsId`/`videoId` (VOD). Construct a playback stream URL with the `streamId`. Read the [Pod Serving Guide](references/pod-serving.md).
+
+3.  **Identify the Target Platform:**
+
+    *   **Web/NodeJs/ReactJs:** Native JavaScript/TypeScript environments (browsers, Smart TVs). Read the [Web Guide](references/web.md).
+    *   **Android/AndroidTV:** Native Java/Kotlin environments. Read the [Android Guide](references/android-ima-extension.md).
+    *   **iOS/tvOS:** Native Swift/Objective-C environments. Read the [iOS/tvOS Guide](references/ios-tvos.md).
+    *   **Roku:** Native BrightScript/SceneGraph environments. Read the [Roku Guide](references/roku.md).
+
+--------------------------------------------------------------------------------
+
+## Quick Start (General Workflow)
+
+For all apps, the integration follows this general logical flow:
+
+1.  Import the SDK: Set up prerequisites and dependencies.
+2.  Initialization: Early setup, Warmup, Settings Configuration, and Ad UI Setup.
+3.  Ad Stream request: Create the livestream or VOD stream request.
+4.  Ad Stream Load Success/Failure: Handle the stream load event to obtain the `StreamManager` or handle early fatal errors.
+5.  Stream Playback Events: Listen to timed metadata events for forwarding ID3/emsg tags to the IMA DAI SDK, and handle non-fatal LOG events or fatal stream errors.
+6.  Cleanup: Properly destroy the `StreamManager` to release resources and prevent memory leaks.
+
+### Basic Web Live Stream Integration Example
+
+```typescript
+import { LiveStreamRequest, StreamManager, StreamEvent } from '@google/ima-dai-sdk';
+
+const videoElement = document.getElementById('video-player') as HTMLVideoElement;
+const adUiElement = document.getElementById('ad-ui') as HTMLElement;
+
+// 1. Initialize StreamManager
+const streamManager = new StreamManager(videoElement, adUiElement);
+
+// 2. Listen for stream loaded event
+streamManager.addEventListener(
+  StreamEvent.Type.LOADED,
+  (event: StreamEvent) => {
+    const streamUrl = event.getStreamData().url;
+    videoElement.src = streamUrl;
+    videoElement.play();
+  }
+);
+
+// 3. Request live stream
+const streamRequest = new LiveStreamRequest();
+streamRequest.assetKey = 'YOUR_ASSET_KEY';
+streamRequest.networkCode = 'YOUR_NETWORK_CODE';
+streamManager.requestStream(streamRequest);
+```
+
+For detailed, platform-specific implementation details, refer to the guides in the **Mandatory Prerequisites** section.
+
diff --git a/skills/ads/ima-dai-sdk/references/android-ima-extension.md b/skills/ads/ima-dai-sdk/references/android-ima-extension.md
@@ -0,0 +1,162 @@
+# Google IMA SDK DAI - Media3 IMA Extension Integration Guide
+
+This guide covers integrating the Google IMA SDK for Android DAI using the
+**Media3 IMA Extension** (`androidx.media3:media3-exoplayer-ima`) and
+`ImaServerSideAdInsertionMediaSource`.
+
+Using the extension is the recommended approach for Media3 ExoPlayer
+integrations as it handles stream wrapping, ad UI overlays, and ad event
+synchronization automatically without requiring a custom `VideoStreamPlayer`
+implementation.
+
+--------------------------------------------------------------------------------
+
+## 1. Dependencies and Configuration
+
+Add the Media3 IMA extension dependency to your app's `build.gradle.kts` file.
+
+Use latest version of the IMA SDK, which is published at
+https://developers.google.com/interactive-media-ads/docs/sdks/android/client-side/download.md.txt.
+Use the latest version of the ExoPlayer and IMA extension at
+https://developer.android.com/jetpack/androidx/releases/media3.md.txt.
+
+```kotlin
+android {
+    defaultConfig {
+        minSdk = 23
+    }
+}
+
+dependencies {
+    implementation("androidx.media3:media3-ui:$latestVersion")
+    implementation("androidx.media3:media3-exoplayer:$latestVersion")
+
+    // CRITICAL: Add the Media3 IMA Extension
+    implementation("androidx.media3:media3-exoplayer-ima:$latestVersion")
+}
+```
+
+--------------------------------------------------------------------------------
+
+### 2. Initialization
+
+Configure the SDK early to minimize latency, and reuse the SDK settings.
+
+*   **Early Warmup & Settings Reuse (Best Practice):** Call
+    `ImaSdkFactory.initialize()` in your `Application.onCreate()` to preload SDK
+    resources.
+*   Reuse the same `ImaSdkSettings` instance when creating the
+    `ImaServerSideAdInsertionMediaSource.AdsLoader.Builder.setImaSdkSettings` to
+    avoid cache misses that cause latency spikes.
+
+```kotlin
+// 1. Application class for early warmup
+class MyApplication : Application() {
+    companion object {
+        lateinit var sdkFactory: ImaSdkFactory
+        lateinit var imaSettings: ImaSdkSettings
+    }
+
+    override fun onCreate() {
+        super.onCreate()
+        sdkFactory = ImaSdkFactory.getInstance()
+
+        // Configure settings early
+        imaSettings = sdkFactory.createImaSdkSettings().apply {
+            language = YOUR_LANGUAGE_CODE // Use 2 lowercase letters to identify
+                                          //   the language of your app UI.
+            isDebugMode = true
+        }
+
+        sdkFactory.initialize(this, imaSettings)
+    }
+}
+...
+
+private ImaServerSideAdInsertionMediaSource.AdsLoader createAdsLoader() {
+  val adsLoaderBuilder = new ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(this, playerView);
+
+  return adsLoaderBuilder
+      .setImaSdkSettings(getImaSdkSettings())
+      .build();
+}
+```
+
+### 3. Build DAI Request UIRs
+
+Create an `ImaServerSideAdInsertionUriBuilder` to build an SSAI livestream URL.
+
+Make sure to use an `assetKey`, which is a string of alphanumeric characters as
+a URL-safe base64 encoded value. For example, here are the assetKeys of DAI
+sample streams: `c-rArva4ShKVIAkNfy6HUQ`,
+`XYrjlG09QTa8pxAo5Fzjww`,`PSzZMzAkSXCmlJOWDmRj8Q`.
+
+```kotlin
+import android.net.Uri
+import androidx.media3.common.C
+import androidx.media3.exoplayer.ima.ImaServerSideAdInsertionUriBuilder
+
+// Example 1: HLS Live Stream
+val hlsLiveUri: Uri = ImaServerSideAdInsertionUriBuilder()
+    .setAssetKey("YOUR_LIVE_ASSET_KEY")
+    .setFormat(C.CONTENT_TYPE_DASH)
+    .build()
+
+// Example 2: HLS VOD Stream
+val hlsVodUri: Uri = ImaServerSideAdInsertionUriBuilder()
+    .setContentSourceId("YOUR_CMS_ID")
+    .setVideoId("YOUR_VIDEO_ID")
+    .setFormat(C.CONTENT_TYPE_DASH)
+    .build()
+```
+
+### 4. Create an ads-aware `MediaSourceFactory`
+
+When using the ExoPlayer IMA extension, you must use the
+`ImaServerSideAdInsertionMediaSource.AdsLoader` class instead of the
+`ImaAdsLoader` class.
+
+When creating the `ImaServerSideAdInsertionMediaSource.AdsLoader`, you must
+provide the `PlayerView` object for rendering ad UI elements.
+
+You must create a `DefaultMediaSourceFactory` object for your content and call
+the `DefaultMediaSourceFactory.setServerSideAdInsertionMediaSourceFactory()`
+method with the `ImaServerSideAdInsertionMediaSource.AdsLoader` object.
+
+```kotlin
+// Construct the AdsLoader instance
+val adsLoader = ImaServerSideAdInsertionMediaSource.AdsLoader.Builder(context, playerView)
+    .build()
+
+// Instantiate the factory and bind the AdsLoader for SSAI handling
+val mediaSourceFactory = DefaultMediaSourceFactory(context)
+    .setServerSideAdInsertionMediaSourceFactory(adsLoader)
+```
+
+### 5. Set Up ExoPlayer
+
+Create the ExoPlayer instance with your ad-aware media source factory and
+provide the ExoPlayer instance to the `AdsLoader` for monitoring ad events.
+
+```kotlin
+// Construct the player using the configured factory
+val player = ExoPlayer.Builder(context)
+    .setMediaSourceFactory(mediaSourceFactory)
+    .build()
+
+// Bind the player to the AdsLoader immediately
+adsLoader.setPlayer(player)
+```
+
+### 6. Load the media item
+
+### 6. Load Media and Manage the Lifecycle
+
+Pass your constructed SSAI URI directly into the player as a `MediaItem`.
+
+When destroying the player activity or handling background events, you must
+execute a strict teardown sequence to preserve the user's session. Call
+`release()` on the `AdsLoader` before releasing the ExoPlayer instance. Capture
+the returned `AdsLoader.State` object and store it securely (e.g., in a
+`ViewModel`). Provide this saved state back to the `AdsLoader.Builder` during
+reinitialization to ensure ad playback resumes exactly where it left off.
diff --git a/skills/ads/ima-dai-sdk/references/dash.md b/skills/ads/ima-dai-sdk/references/dash.md
@@ -0,0 +1,31 @@
+# Google IMA SDK DAI - DASH Integration Guide
+
+This guide covers DASH stream request configuration with IMA DAI SDK.
+
+When requesting a DASH stream, you set the stream format as follows.
+
+*   **Web (TypeScript):**
+
+    ```typescript
+    const streamRequest = new google.ima.dai.api.LiveStreamRequest();
+    streamRequest.format = 'dash'; // the format property is also available for
+                                  // VODStreamRequest,
+                                  // PodStreamRequest, PodVodStreamRequest.
+    ```
+
+*   **Android (Kotlin):**
+
+    ```kotlin
+    val request = sdkFactory.createLiveStreamRequest(...)
+    request.format = StreamFormat.DASH
+    ```
+
+    Or if using Media3 SSAI Uri Builder:
+
+    ```kotlin
+    val ssaiUri = ImaServerSideAdInsertionUriBuilder()
+        .setAssetKey(assetKey)
+        .setFormat(androidx.media3.common.C.CONTENT_TYPE_DASH)
+        // ...
+        .build()
+    ```