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-ios-guide.md
Google IMA SDK iOS integration guide
This guide covers the integration of the Google IMA SDK for iOS (client-side) following the lifecycle of ad playback.
Integration flow
1. Import the SDK
By default, use Swift Package Manager to add the main branch of https://github.com/googleads/swift-package-manager-google-interactive-media-ads-ios.
If the app must use CocoaPods, install the GoogleAds-IMA-iOS-SDK pod.
2. Initialization
Configure the SDK settings and initialize the IMAAdsLoader early in the
application lifecycle to minimize latency, and set up the Ad UI.
Early Initialization: Creating an
IMAAdsLoaderinstance is expensive as it spins up an underlying WebView (1-2 seconds overhead). Instantiate the loader early (e.g., at app launch) and reuse the single instance.Settings Immutability: Configure
IMASettingsbefore passing them to the loader. Once the loader is initialized, settings become read-only.Create the IMAAdsLoader: Instantiate
IMAAdsLoaderpassing your configuredIMASettingsinstance. This object handles the lifecycle of ad requests and must be persisted and reused.Ad UI Setup: Create a dedicated
UIViewfor ads and layer it directly on top of your video player view using Auto Layout. Hide custom player controls when ads play.
import UIKit
import GoogleInteractiveMediaAds
// 1. Shared AdsManager to handle early initialization and reuse
class AdsManager: NSObject {
static let shared = AdsManager()
var adsLoader: IMAAdsLoader?
var adsManager: IMAAdsManager?
private var settings: IMASettings
private override init() {
// Configure settings early
settings = IMASettings()
settings.language = "en"
settings.enableDebugMode = true
super.init()
// Initialize loader early. Settings are now locked.
adsLoader = IMAAdsLoader(settings: settings)
}
// 2. Ad UI Setup helper
func setupAdContainer(in viewController: UIViewController, overlaying videoView: UIView) -> UIView {
let adContainerView = UIView()
adContainerView.translatesAutoresizingMaskIntoConstraints = false
viewController.view.addSubview(adContainerView)
// Align perfectly with the video view
NSLayoutConstraint.activate([
adContainerView.leadingAnchor.constraint(equalTo: videoView.leadingAnchor),
adContainerView.trailingAnchor.constraint(equalTo: videoView.trailingAnchor),
adContainerView.topAnchor.constraint(equalTo: videoView.topAnchor),
adContainerView.bottomAnchor.constraint(equalTo: videoView.bottomAnchor)
])
return adContainerView
}
}3. Ad request
Create an IMAAdDisplayContainer and an IMAAdsRequest, then trigger the
request. It is highly recommended to trigger this on a user gesture (e.g.,
tapping play).
extension AdsManager {
func requestAds(adTagUrl: String, adContainer: UIView, videoDisplay: IMAVideoDisplay, delegate: IMAAdsLoaderDelegate) {
guard let loader = adsLoader else { return }
loader.delegate = delegate
// Create the ad display container
let displayContainer = IMAAdDisplayContainer(adContainerViewController: delegate as? UIViewController, companionViews: nil)
// Create the ads request
let request = IMAAdsRequest(
adTagUrl: adTagUrl,
adDisplayContainer: displayContainer,
contentPlayhead: nil,
userContext: nil)
// Request ads
loader.requestAds(with: request)
}
}4. Ad load success/failure
Implement IMAAdsLoaderDelegate to handle successful ad loads (which returns
the IMAAdsManager) or early failures (fatal loading errors).
class PlayerViewController: UIViewController, IMAAdsLoaderDelegate {
var videoView: UIView! // Your video player view
var adContainerView: UIView?
func startAdFlow() {
// Set up UI and request ads
self.adContainerView = AdsManager.shared.setupAdContainer(in: self, overlaying: videoView)
let videoDisplay = IMAAVPlayerVideoDisplay(avPlayer: self.contentPlayer)
AdsManager.shared.requestAds(
adTagUrl: "YOUR_AD_TAG_URL",
adContainer: self.adContainerView!,
videoDisplay: videoDisplay,
delegate: self)
}
// MARK: - IMAAdsLoaderDelegate (Success)
func adsLoader(_ loader: IMAAdsLoader, admitsCompletedWith adsManagerLoadedData: IMAAdsManagerLoadedData) {
// Ad Load Success: Get the AdsManager
AdsManager.shared.adsManager = adsManagerLoadedData.adsManager
AdsManager.shared.adsManager?.delegate = self
// Initialize the ads manager
AdsManager.shared.adsManager?.initialize(with: nil)
}
// MARK: - IMAAdsLoaderDelegate (Failure / Fatal Load Error)
func adsLoader(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData) {
print("IMA SDK Loading Error: \(adErrorData.adError.message ?? "Unknown error")")
resumeContent() // Fallback to content
}
}5. Ad playback events
Implement IMAAdsManagerDelegate to listen for playback events, coordinate
content pausing/resumption, and handle playback errors.
Pause Content: On
pauseevent, pause your content player and hide custom controls.Resume Content: On
resumeevent oradsManagerDidRequestContentResume, restore controls and play content.Non-Fatal Logs: Monitor
logevents for silent tracking or VPAID issues without interrupting playback.
extension PlayerViewController: IMAAdsManagerDelegate {
// MARK: - IMAAdsManagerDelegate (Playback Events)
func adsManager(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent) {
switch event.type {
case .LOADED:
// Start ad playback
adsManager.start()
case .PAUSE:
pauseContent() // Pause player, hide custom controls
case .RESUME:
resumeContent() // Resume player, restore controls
case .LOG:
if let adData = event.adData {
print("IMA SDK Non-fatal Log: \(adData)")
}
default:
break
}
}
func adsManagerDidRequestContentResume(_ adsManager: IMAAdsManager) {
resumeContent() // Resume content when ad completes
}
// MARK: - IMAAdsManagerDelegate (Playback Failure / Fatal Error)
func adsManager(_ adsManager: IMAAdsManager, failedWith error: IMAAdError) {
print("IMA SDK Manager Error: \(error.message ?? "Unknown error")")
cleanupAds()
resumeContent()
}
}6. Cleanup
Proper cleanup is critical to prevent memory leaks, audio playback bugs, and background resource consumption.
IMAAdsManager.destroy(): This is crucial. Always call it, and set your reference tonil, when:All ads have completed.
A fatal ad error occurs (in
failedWithdelegate).The user dismisses the player or navigates away (e.g., in
viewWillDisappearordeinit).
IMAAdsLoaderCleanup: TheIMAAdsLoaderis designed to be a long-lived object. Do not destroy it between ad requests. However, if you need to completely tear down the ad integration (e.g., when the app is shutting down or a major parent component is deinitialized), set the loader's delegate toniland nullify your reference to allow ARC to deallocate it.
// In your PlayerViewController
deinit {
cleanupAds()
}
override func viewWillDisappear(_ animated: Bool) {
super.viewWillDisappear(animated)
if isMovingFromParent {
cleanupAds()
}
}
func cleanupAds() {
// 1. Destroy the AdsManager and nil its delegate
if let manager = AdsManager.shared.adsManager {
manager.destroy()
manager.delegate = nil
AdsManager.shared.adsManager = nil
}
// 2. Clean up UI
self.adContainerView?.removeFromSuperview()
self.adContainerView = nil
}
// Call this only when permanently tearing down the SDK integration
func tearDownSDK() {
AdsManager.shared.adsLoader?.delegate = nil
AdsManager.shared.adsLoader = nil
}Reference implementation
BasicExample BasicExampleApp.swift
BasicExample PlayerContainerViewController.swift
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