Ima SDK Client Side
GoogleOfficialCreated by Google LLC
- Skill
- Tool integration
- Software development
- Apache-2.0
- No issues found
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
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/google/ima-sdk-client-side/downloadUnzip 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:
Web/HTML5/ReactJs/NodeJs/Angular: Read all these guides ima-sdk-web-guide.md, ima-sdk-web-iframe-mode.md, ima-sdk-web-mobile-safari.md
Android/AndroidTV/ReactNative: Read ima-sdk-android-guide.md
iOS/tvOS/ReactNative: Read all these guides ima-sdk-ios-guide.md, ima-sdk-tvos-guide.md
Quick start (general workflow)
Import the SDK: Prerequisites, dependencies.
Initialization: Early setup, Warmup, Settings Configuration, and Ad UI Setup.
Ad Request: Creating and triggering the request, User gesture compliance.
Ad Load Success/Failure: Handling the load event to get the AdsManager, or handling early fatal errors.
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.
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
- ATTRIBUTION.mdAdded by AutoGineer920 B
- LICENSELicence file added by AutoGineer11.1 KiB
- SKILL.md2.1 KiB
- references/ima-sdk-android-guide.md5.5 KiB
- references/ima-sdk-ios-guide.md8.6 KiB
- references/ima-sdk-tvos-guide.md5.9 KiB
- references/ima-sdk-web-guide.md8.3 KiB
- references/ima-sdk-web-iframe-mode.md2.8 KiB
- references/ima-sdk-web-mobile-safari.md514 B
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.settingsbefore creating theAdDisplayContaineror theAdsLoader. 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.AdDisplayContainerpassing the ad container HTML element and the content video element.Create AdsLoader: Instantiate
google.ima.AdsLoaderpassing yourAdDisplayContainerinstance. 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
LOGevents 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
nullto 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
UI setup: simple/index.html
App logic: simple/ads.js
Optionally, install type definitions for TypeScript projects:
npm install --save-dev @types/google_interactive_media_ads_typesRequirements 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