Generated banner for Ima SDK Client Side
Generated logo for Ima SDK Client Side

Ima SDK Client Side

GoogleOfficialCreated by Google LLC

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • No issues found

From the author

Supports Interactive Media Ads (IMA) SDK. Use this skill for client-side ad insertion when you are requesting video ads for websites, apps, TVs or other platforms using VAST or VMAP. Do not use for Dynamic Ad Insertion (DAI), SSAI, or SGAI.
— the description by Google LLC

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The Google IMA SDK client-side skill provides the necessary framework to load and manage in-stream video and audio ads within websites, mobile apps, and TV platforms. It supports VAST and VMAP ad standards, enabling developers to request ads from compliant servers and coordinate playback between ad content and primary media. The skill emphasizes platform-specific implementation patterns for Android, iOS, and web environments, focusing on efficient resource management, proper ad container setup, and lifecycle handling to ensure a seamless user experience.

What it does

  • Facilitates client-side ad insertion for video and audio content.
  • Supports VAST and VMAP ad standards for ad server communication.
  • Provides platform-specific integration guides for Android, iOS, and web.
  • Manages ad playback events and content synchronization.
  • Includes lifecycle management for SDK initialization, ad requests, and resource cleanup.

When to use it

  • When you need to display in-stream video or audio ads on websites, mobile apps, or TV platforms.
  • When your ad server provides VAST or VMAP compliant ad tags.
  • When you require client-side control over ad playback and ad-to-content transitions.
  • When building applications on Android, iOS, or web platforms that require standard ad integration.

Advantages

  • Standardized approach to ad insertion across multiple digital platforms.
  • Supports industry-standard VAST and VMAP protocols.
  • Provides clear lifecycle management to prevent memory leaks and resource issues.
  • Enables granular control over ad playback and user experience coordination.

Usage examples

“How do I initialize the IMA SDK on Android to minimize latency?”
The SDK recommends calling ImaSdkFactory.initialize() in your Application.onCreate() to preload resources and reusing the same ImaSdkSettings instance across your AdsLoader.
“What is the correct way to clean up the IMA SDK on iOS?”
You must call destroy() on the AdsManager when ads complete or errors occur, and release the AdsLoader when the component is permanently destroyed to prevent memory leaks.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/google/ima-sdk-client-side/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip ima-sdk-client-side.zip -d .agents/skills

Documentation by Google LLC

IMA SDK client-side

The Google IMA SDK (Interactive Media Ads) lets you load in-stream video and audio ads into websites, apps, TVs and other digital platforms. Use an IMA SDK to request ads from any VAST-compliant ad server and manage ad playback.

Prerequisites

Before integrating the IMA SDK, you must read the platform-specific guide below to support all platforms that your app can support:


Quick start (general workflow)

  1. Import the SDK: Prerequisites, dependencies.

  2. Initialization: Early setup, Warmup, Settings Configuration, and Ad UI Setup.

  3. Ad Request: Creating and triggering the request, User gesture compliance.

  4. Ad Load Success/Failure: Handling the load event to get the AdsManager, or handling early fatal errors.

  5. Ad Playback Events: Listening to playback events via AdsManager to coordinate content play/pause, and handling non-fatal LOG events and fatal active playback errors.

  6. Cleanup: Properly destroying the AdsManager to release resources and prevent memory leaks.

For detailed, platform-specific implementation details, always refer to the guides in the Prerequisites section.

Files

references/ima-sdk-web-guide.md

Google IMA SDK HTML5 (Web) integration guide

This guide covers the integration of the Google IMA SDK for HTML5 (client-side) following the natural lifecycle of ad playback.

Integration flow

1. Import the SDK

Load the SDK script at the page level. Ensure the SDK can access window.top.location.href.

<script src="https://imasdk.googleapis.com/js/sdkloader/ima3.js"></script>
2. Initialization

Configure the SDK settings early, set up the Ad UI, and initialize the AdDisplayContainer and AdsLoader.

  • Configure Settings Early (Best Practice): You must set your configurations on the global singleton google.ima.settings before creating the AdDisplayContainer or the AdsLoader. Late changes will not propagate.

  • Ad UI Setup: Always use a dedicated HTML element (e.g., <div id="adContainer">) solely for the IMA SDK, layered directly on top of the video player. Hide custom player controls when ads play.

  • Create AdDisplayContainer: Instantiate google.ima.AdDisplayContainer passing the ad container HTML element and the content video element.

  • Create AdsLoader: Instantiate google.ima.AdsLoader passing your AdDisplayContainer instance. This object handles the lifecycle of ad requests.

<!-- HTML Structure -->
<div id="playerContainer" style="position:relative; width:640px; height:360px;">
  <video id="contentVideo" style="width:100%; height:100%;"></video>
  <div id="adContainer" style="position:absolute; top:0; left:0; width:100%; height:100%; z-index:10;"></div>
</div>
// TypeScript Initialization
let adsLoader: google.ima.AdsLoader;
let adDisplayContainer: google.ima.AdDisplayContainer;

function initializeIMA(): void {
    // 1. Configure global settings early
    google.ima.settings.setLocale('en');
    google.ima.settings.setVpaidMode(google.ima.ImaSdkSettings.VpaidMode.ENABLED);

    // 2. Set up Ad UI Container
    const adContainerElement = document.getElementById('adContainer') as HTMLElement;
    const videoElement = document.getElementById('contentVideo') as HTMLVideoElement;

    adDisplayContainer = new google.ima.AdDisplayContainer(adContainerElement, videoElement);

    // 3. Initialize AdsLoader
    adsLoader = new google.ima.AdsLoader(adDisplayContainer);

    // Setup listeners for Ad Load Success/Failure
    setupAdsLoaderListeners();
}
3. Set up app UI

You must suggest the best practice to use a user action, such as button click, to start content and ad playback.

If your app needs autoplay ads, you must write the code to check whether the browser supports autoplay. If unmuted autoplay fails, fallback to muted autoplay. If that fails, fallback to using a user action, such as button click, to start content and ad playback.

Crucially, you must inform the IMA SDK of the final state using setAdWillAutoPlay() and setAdWillPlayMuted(). This guarantees the ad server returns an ad formatted for your specific playback environment.

const request = new google.ima.AdsRequest();
request.adTagUrl = 'YOUR_AD_TAG_URL';

// Inform the SDK of the current playback capabilities
request.setAdWillAutoPlay(isAutoPlay);
request.setAdWillPlayMuted(isMuted);

adsLoader.requestAds(request);
4. Ad request

Create an AdsRequest and use AdsLoader to load it.

function requestAds() {
    adDisplayContainer.initialize();

    const adsRequest = new google.ima.AdsRequest();
    adsRequest.adTagUrl = `YOUR_AD_TAG_URL`;

    adsLoader.requestAds(adsRequest);
}
5. Ad load success/failure

Listen for the AdsLoader to successfully load the ads (providing the AdsManager) or fail early (fatal loading errors).

let adsManager: google.ima.AdsManager | null = null;

function setupAdsLoaderListeners(): void {
    // Handle Ad Load Success
    adsLoader.addEventListener(
        google.ima.AdsManagerLoadedEvent.Type.ADS_MANAGER_LOADED,
        onAdsManagerLoaded
    );

    // Handle Ad Load Failure (Fatal Error)
    adsLoader.addEventListener(
        google.ima.AdErrorEvent.Type.AD_ERROR,
        onAdError
    );
}

function onAdsManagerLoaded(adsManagerLoadedEvent: google.ima.AdsManagerLoadedEvent): void {
    // Get the AdsManager
    const adsRenderingSettings = new google.ima.AdsRenderingSettings();
    adsManager = adsManagerLoadedEvent.getAdsManager(videoElement, adsRenderingSettings);

    setupAdsManagerListeners(adsManager);

    try {
        // Initialize the manager
        adsManager.init(width, height, google.ima.ViewMode.NORMAL);
        // Start ad playback
        adsManager.start();
    } catch (adError) {
        // Handle initialization errors
        resumeContent();
    }
}

function onAdError(adErrorEvent: google.ima.AdErrorEvent): void {
    console.error("IMA SDK Fatal Error:", adErrorEvent.getError().toString());
    cleanupAds();
    resumeContent(); // Fallback to content
}
6. Ad playback events

Use the AdsManager to listen for playback events, coordinate content pausing/resumption, and monitor non-fatal logs.

  • Pause Content: On CONTENT_PAUSE_REQUESTED, pause the content video player and hide custom controls.

  • Resume Content: On CONTENT_RESUME_REQUESTED, hide the ad container, restore player controls, and play the content video.

  • Non-Fatal Logs: Listen for LOG events to detect silent failures (e.g., failed tracking pings) without interrupting the user.

function setupAdsManagerListeners(manager: google.ima.AdsManager): void {
    // Playback Events
    manager.addEventListener(
        google.ima.AdEvent.Type.CONTENT_PAUSE_REQUESTED,
        () => { pauseContent(); }, // Pause player, hide custom controls
        false
    );

    manager.addEventListener(
        google.ima.AdEvent.Type.CONTENT_RESUME_REQUESTED,
        () => { resumeContent(); }, // Resume player, restore controls
        false
    );

    // Non-Fatal Logs
    manager.addEventListener(
        google.ima.AdEvent.Type.LOG,
        (adEvent: google.ima.AdEvent) => {
            const logData = adEvent.getAdData();
            if (logData && logData['errorMessage']) {
                console.warn("IMA SDK Non-fatal Log:", logData['errorMessage']);
            }
        },
        false
    );

    // Playback Errors (Fatal errors during active playback)
    manager.addEventListener(
        google.ima.AdErrorEvent.Type.AD_ERROR,
        onAdError,
        false
    );
}
7. Cleanup

Proper cleanup is critical in HTML5 to prevent memory leaks, redundant event callbacks, and leftover DOM elements (like SDK iframes).

  • adsManager.destroy(): This is crucial. Always call it when ads finish, on fatal error, or when the player is unmounted/navigated away.

  • adsLoader.contentComplete(): Call this to signal to the SDK that content has finished. This is required for the SDK to play post-roll ads.

  • adDisplayContainer.destroy(): Call this when disposing of the player. It removes the internal DOM elements (including iframes) created by the SDK.

  • Nullify References: Set all references to null to allow garbage collection.

// Call this when the player is being destroyed/unmounted (e.g., ngOnDestroy, componentWillUnmount)
function tearDownPlayer(): void {
    cleanupAds();

    // 1. Signal content completion (important for post-rolls)
    if (adsLoader) {
        adsLoader.contentComplete();
    }

    // 2. Destroy the display container to clean up DOM/iframes
    if (adDisplayContainer) {
        adDisplayContainer.destroy();
        adDisplayContainer = null;
    }

    // 3. Nullify the loader if tearing down the page
    adsLoader = null;
}

function cleanupAds(): void {
    // 4. Destroy the AdsManager to release active ad resources
    if (adsManager) {
        adsManager.destroy();
        adsManager = null;
    }
}

Reference implementation

    npm install --save-dev @types/google_interactive_media_ads_types

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Security

No issues found by our static scan· No issues found

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
Google LLC
Publisher
Google (Official)
Source
google/skills · skills/ads/ima-sdk-client-side · commit 2194d3b
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by Google LLC or Google.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download ima-sdk-client-side.zip