`) 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
```
```typescript
// 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.
```typescript
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.
```typescript
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).
```typescript
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.
```typescript
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.
```typescript
// 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](https://raw.githubusercontent.com/googleads/googleads-ima-html5/main/simple/index.html)
* App logic: [simple/ads.js](https://raw.githubusercontent.com/googleads/googleads-ima-html5/main/simple/ads.js)
* Optionally, install type definitions for TypeScript projects:
```bash
npm install --save-dev @types/google_interactive_media_ads_types
````
### `references/ima-sdk-web-iframe-mode.md`
````markdown
# IMA SDK HTML5 iframe mode
This guide covers best practices when you can only use the Google IMA SDK for
HTML5 within iframes.
## Prioritize top page level over iframe
You should try to add the IMA SDK script at the top page level. The page level
is preferred over the use of IMA SDK inside an iframe.
### Same-origin iframe fallback
If you detect that the IMA SDK script is inside an iframe, ensure that the
iframe containing the IMA SDK script, the container page, and the video player
all reside on the same domain.
For example: check inside the iframe for access of the top window location.
```typescript
function hasAccessToTopWindow(): boolean {
try {
// 1. Check if the current context is already the top window.
if (window === window.top) {
return true;
}
// 2. Attempt a same-origin read on the top window location.
// If cross-origin limits apply, this read will throw a DOMException.
const topUrl = window.top.location.href;
return true;
} catch (error) {
// 3. A SecurityError DOMException was thrown.
// When this error happens, the SDK is isolated in a cross-origin iframe
// and does not have direct access to the top-level window.
const errorMessage = error instanceof Error ? error.message : String(error);
console.error("Access to top-level window is blocked: ", errorMessage);
return false;
}
}
if (hasAccessToTopWindow()) {
console.log("IMA SDK has access to the top-level window.");
} else {
console.log("IMA SDK is isolated in a cross-origin iframe sandbox.");
}
```
This same-origin setup is required for the SDK to directly access the
`window.top` level, the video player element.
### Cross-origin iframe workaround
If you detect that the IMA SDK is loaded inside an iframe from a domain
different from the domain of the main page containing the video player, you must
provide the main page's URL to the SDK by setting the `adsRequest.pageUrl`
property.
Example code:
```typescript
const adsRequest: google.ima.AdsRequest = new google.ima.AdsRequest();
adsRequest.adTagUrl = 'YOUR_AD_TAG_URL';
// Manually set the page URL to the parent page's URL
adsRequest.pageUrl = 'https://
/';
```
Check the `sandbox` attribute of the iframe loading the IMA SDK to grant these
required capabilities:
* Adding `allow-scripts` for executing the SDK JavaScript. Without this, the
IMA SDK fails to load and initializes.
* Adding `allow-same-origin` to let the loaded page read its own cookies.
* Adding `allow-popups`, `allow-popups-to-escape-sandbox`,
`allow-top-navigation-by-user-activation` to let the SDK open the
advertiser's landing page.
```
```
````
### `references/ima-sdk-web-mobile-safari.md`
````markdown
# Google IMA HTML5 SDK on Mobile Safari (iOS) guide
This guide covers best practices for the Google Interactive Media Ads (IMA)
HTML5 SDK to support mobile Safari (iOS).
## Essential setup
You must do the following steps:
* Check and make sure that the `playsinline` attribute is added for the HTML
`