Tag Archives: ima_html5

Changes to pause behavior in the Interactive Media Ads (IMA) SDK

The IMA SDK is preparing to release changes to pause behavior when user clicks cause navigation away from the page or app. When this happens, the ad will be paused automatically by the SDK. These changes are targeted for October 13th, 2020.

The IMA client-side SDKs already pause ad playback for ad click-throughs, but these changes add automatic pausing to many other user actions. The IMA DAI SDKs currently do not pause for any click events. For either implementation, if your code does not already provide a way for users to resume ad playback when ads are paused, we recommend adding a way to resume ad playback following ad pause events.

When the SDK automatically pauses the ad, the PAUSED event will be fired. We recommend that publishers listen for this event, and update the UI to allow the viewer to resume the ad. If this UI is not shown, the player may be permanently paused on the ad without a way for the user to resume ad or content playback.

Client-side changes

  • On Desktop web, the SDK will automatically pause when the user clicks on an ad which results in navigation away from the page.
    • This behavior already exists for mobile web and mobile apps.
  • On all platforms, the SDK will attempt to automatically pause if the user clicks on the:
    • Learn more button
    • Ad click (desktop)
    • Non-linear ad
    • Icon click
    • AdChoices icon

Dynamic Ad Insertion (DAI) changes

  • On all platforms for DAI, the SDK will attempt to automatically pause if the user clicks on the:
    • Learn more button
    • Ad click (desktop)
    • Icon click
    • AdChoices icon

Pause events

The table below shows which API is called when a pause event occurs:

IMA platform SDK version Pause event for client-side SDK Pause event for DAI SDK
HTML5 The current evergreen version. google.ima.AdEvent.Type.PAUSED The video player’s pause event.
Android V3.20.0 and later. videoAdPlayer.pauseAd() videoStreamPlayer.pause()
iOS/tvOS All versions kIMAAdEvent_PAUSE kIMAAdEvent_PAUSE

Note: For Android, the onPause event is only available on v3.20.0 and later. For previous versions the IMA SDK will not automatically pause ads, and developers will not have to implement these changes.

Please see the following code snippet as an example of setting up a listener for the PAUSED event for a client-side HTML5 IMA SDK implementation:

adsManager.addEventListener(google.ima.AdEvent.Type.PAUSED, function() {
showAdResumeUI();
});

function showAdResumeUI() {
// TODO: Add a play button that resumes playback.
}

Please review your IMA SDK integrations and make any necessary adjustments to handle the pause event so that you’re prepared for when the changes go live on October 13th. Please look for announcements about pause behavior changes in the IMA HTML5 SDK release notes. If you have questions about making these changes for your own IMA SDK integrations, feel free to reach out to us on the IMA SDK forum.

SIMID support in the Interactive Media Ads SDK

The Secure Interactive Media Interface Definition (SIMID) is a new ad format for interactive video ads. It was designed to be the successor of the Video Player Ad-Serving Interface Definition (VPAID) according to the Interactive Advertising Bureau. SIMID addresses many of the issues with VPAID, including slow loading times, security limitations, and being difficult to debug with only a single error code (901).

SIMID support is available in the HTML5, Android, and iOS IMA SDKs for client-side ads starting with the following releases:

Improvements in the SIMID API Model over VPAID

Unlike VPAID, the code for SIMID ad creatives runs in a secure sandbox so that it cannot access other resources on the page. With SIMID, the player maintains control while the creative sends messages to the player about which actions are needed to perform its functions. This is demonstrated in the diagram below:

As a result, SIMID offers the following advantages over VPAID:

  • Improved security by sandboxing the ad from the publishers page
  • Improved asset transparency by including the media file in the VAST response
  • Support for pre-caching
  • Faster load times
  • Improved error reporting from more granular error codes

Using SIMID with the IMA SDK

SIMID creatives are ready to be used within VAST ad-tags. To get started, see the IAB’s example on GitHub or test it yourself using this SIMID ad tag. If you have questions about the IMA SDK, see the SDK documentation or reach out to us on the IMA SDK forum.

Sunsetting Flash in the IMA SDKs

On May 15, 2018, Google will be sunsetting Flash in the IMA SDKs. This change will affect all users of the Flash IMA SDK, and a very small number of users of the HTML5 IMA SDK.

Changes to the Flash SDK

As of May 15, 2018, attempts to load the Flash IMA SDK will fire an AdErrorEvent.AD_ERROR from the AdsLoader. This is a change to the portion of the Flash SDK that is loaded at run time, and therefore will affect all Flash SDK implementations in production. If you've followed our implementation best practices, your handler for this error will play your content video:


private function initAdsLoader():void {
  ...
  adsLoader.addEventListener(AdErrorEvent.AD_ERROR, adsLoadErrorHandler);
}

private function adsLoadErrorHandler(event:AdErrorEvent):void {
  trace("warning", "Ads load error: " + event.error.errorMessage);
  videoPlayer.play();
}
We strongly encourage all publishers still using the Flash SDK to migrate to the HTML5 SDK. As part of this sunset, we will also be removing the Flash SDK documentation from developers.google.com and removing the Flash samples from GitHub.

Changes to the HTML5 SDK

As of May 15, 2018, the HTML5 IMA SDK will stop supporting all Flash ads. This includes linear, non-linear, and companion ads. If your VAST response includes only Flash media files, the IMA SDK will throw error 403 - VAST_LINEAR_ASSET_MISMATCH for linear ads, and error 503 - VAST_NONLINEAR_ASSET_MISMATCH for non-linear ads. Flash companion ads will fail silently. The HTML5 SDK stopped supporting Flash VPAID ads with the deprecation of the Flash IMA SDK last June.


As always, if you have any questions, feel free to contact us via the support forum.


Sunsetting Flash in the IMA SDKs

On May 15, 2018, Google will be sunsetting Flash in the IMA SDKs. This change will affect all users of the Flash IMA SDK, and a very small number of users of the HTML5 IMA SDK.

Changes to the Flash SDK

As of May 15, 2018, attempts to load the Flash IMA SDK will fire an AdErrorEvent.AD_ERROR from the AdsLoader. This is a change to the portion of the Flash SDK that is loaded at run time, and therefore will affect all Flash SDK implementations in production. If you've followed our implementation best practices, your handler for this error will play your content video:


private function initAdsLoader():void {
  ...
  adsLoader.addEventListener(AdErrorEvent.AD_ERROR, adsLoadErrorHandler);
}

private function adsLoadErrorHandler(event:AdErrorEvent):void {
  trace("warning", "Ads load error: " + event.error.errorMessage);
  videoPlayer.play();
}
We strongly encourage all publishers still using the Flash SDK to migrate to the HTML5 SDK. As part of this sunset, we will also be removing the Flash SDK documentation from developers.google.com and removing the Flash samples from GitHub.

Changes to the HTML5 SDK

As of May 15, 2018, the HTML5 IMA SDK will stop supporting all Flash ads. This includes linear, non-linear, and companion ads. If your VAST response includes only Flash media files, the IMA SDK will throw error 403 - VAST_LINEAR_ASSET_MISMATCH for linear ads, and error 503 - VAST_NONLINEAR_ASSET_MISMATCH for non-linear ads. Flash companion ads will fail silently. The HTML5 SDK stopped supporting Flash VPAID ads with the deprecation of the Flash IMA SDK last June.


As always, if you have any questions, feel free to contact us via the support forum.


Announcing the IMA SDK AMP Extension

We’re excited to announce that we’ve teamed up with the Accelerated Mobile Pages team to bring you amp-ima-video, an IMA-SDK-enabled video player extension for AMP pages. This extension has been an AMP experiment for the past few months, but today we’re moving from experiment to public release.

amp-ima-video provides an AMP-enabled video player with the IMA SDK pre-integrated, so you can easily play and monetize content on your AMP pages. Simply provide your content URL and an ad tag, and we’ll handle playing back the video and ad(s). The extension currently supports linear in-stream single ads and VMAP playlists. To see it in action, check out the AMP by Example page for the extension.

If you have any questions or issues with the extension, please file them via the AMP issue tracker on GitHub.

Changes to autoplay in Safari 11 for desktop

MacOS High Sierraincludes a new version of Safari, Safari 11. This new version by default will remove support for auto-playing videos unless they are muted. If your desktop site currently autoplays unmuted video with the IMA SDK, your users will see the first frame of the ad, but the ad will not play. To resolve this, you can either change your implementation to click-to-play, or attempt to autoplay and revert to click-to-play if that fails. We've also added a new error that will fire if the SDK is asked to autoplay an ad but is prevented from doing so by the browser. Continue reading for more info on these solutions.

Click-to-play

The simple, advanced, and playlist IMA SDK samples use this click-to-play functionality. In short, you add a play button to your UI, and render that play button on page load. Your code should then delay calls to adDisplayContainer.initialize(), adsManager.init()and adsManager.start()until the user clicks that play button.

Attempt to autoplay

We've added a new sample to our GitHub repo, Attempt to Autoplay. This sample will autoplay ads if allowed, and if not, will follow the above click-to-play workflow. The sample starts by attempting to autoplay the content video. If autoplay succeeds, it pauses the content to play a pre-roll. This happens in an instant, so the users will not see any content actually play before the ads. If this autoplay attempt fails, the sample renders a play button and waits for the user to click that button to initialize the ad display container and play ads.

New error for failed autoplay

We've added AdError.ErrorCode.AUTOPLAY_DISALLOWED which the SDK will fire if it is asked to autoplay an ad but is prevented from doing so by the browser. You should not see this error if you've properly implemented one of the solutions above. This error is wrapped in a VIDEO_PLAY_ERROR; you can look for it as follows:

onAdError(adErrorEvent) {
if (adErrorEvent.getError().getInnerError().getErrorCode() ==
google.ima.AdError.ErrorCode.AUTOPLAY_DISALLOWED) {
// The browser prevented the SDK from autoplaying an ad.
}
}

If you have any questions, feel free to reach out to us on our support forum.

New Custom Playback APIs for IMA HTML5 and Mobile Safari

Starting with iOS 10, Safari on iPhone and iPod supports inline video playback. This opens up some new rendering options for your video player and the IMA SDK, but also introduces some caveats.

So what changed?

Previously, Safari on iPhone played all video in a fullscreen player. With iOS 10, Safari now supports the playsinline parameter on a video element to play that content inline.

Fullscreen playback on iPhone Mobile Safari. The default with iOS 10+ and the only option for iOS <= 10

Inline playback on iPhone Mobile Safari. A new option in iOS 10+

How will the IMA SDK work with inline video playback on mobile Safari?

On iPhone Safari, the IMA SDK re-uses your content player to play ads. We call this "custom playback." So if you add the playsinline parameter to your content video tag, IMA ads will also play inline - it's as easy as that.

Inline video playback also opens the door for the IMA SDK to play skippable ads on iPhone Mobile Safari. Previously these ads were dropped by the SDK because we could not render a skip button on top of the fullscreen player. If your player is inline, however, we can render that skip button, but there's a catch.

So what's the catch?

IMA SDK skippable ads are not supported with the "custom playback" method. To use skippable ads, you'll need to use our new API, ImaSdkSettings.setDisableCustomPlaybackForIOS10Plus(). This will cause the IMA SDK to render the ad in its own inline player on top of your content player. That player does support skippable ads. Disabling "custom playback", however, will break your fullscreen implementation for iPhone web.

Why do I need custom playback on iOS?

The need for "custom playback" on iOS boils down to one thing - fullscreen support. Mobile Safari only supports fullscreen via videoPlayer.webkitEnterFullscreen(). In this mode, the SDK cannot render anything on top of your content player. Therefore, to support fullscreen ad playback we must use "custom playback".

What if I want skippable ads and fullscreen support?

Unfortunately, this is not possible on mobile Safari today - you must choose between support for skippable ads and support for fullscreen.

What's the deal with iOS <10?

Prior versions of iOS (<10) do not have support for playsinline, so pages in those environments will always use "custom playback" mode, with support for fullscreen but no support for skippable ads.

I'm still confused.

That's OK! This is a complicated change with a lot of moving parts. Below is a support matrix outlining what is and is not supported based on your content player's playsinline mode and the "custom playback" mode you've set for the IMA SDK. Remember, this matrix only applies to iOS 10 and above - anything running version iOS 9 or below falls into the top left quadrant of the matrix, as this is the only option.

New VPAID Sample for the IMA HTML5 SDK

To help developers integrate with the IMA SDK, we're always looking for ways to provide both basic and advanced examples of features supported by the SDK. Toward this end, we're pleased to release a sample JavaScript VPAID creative and sample ad tag to aid in troubleshooting JavaScript VPAID 2.0 creatives. You can check out the new sample on GitHub, and find the new ad tag in our list of IMA sample tags as 'Sample VPAID 2.0 Linear'.

The VPAID sample plays a linear video ad and demonstrates the use of the video player proxy element required to run a VPAID ad in a secure iframe.

If you have any questions, feel free to contact us via the IMA SDK developer forum.

Latency best practices in the IMA SDKs

One of the most important factors in keeping users on your page or in your app is latency - the lower your latency, the more likely your users are to stick around. With this in mind, we'd like to remind you about our best practices for reducing latency with the IMA SDKs. In general, you can reduce latency by doing as much IMA set-up work as possible on page or app load, before your user tries to play a video. The following can be done in all of the SDKs before the user attempts to play a video:

  • Creating your ads loader.
  • Creating your ads request.
  • Requesting ads.
  • Obtaining the ads manager.
  • Registering ads manager event handlers.

You can find more information on optimizing latency in each of our SDKs at the links below:

As always, if you have any questions, feel free to contact us via the support forum.

Deprecating Flash in the IMA SDKs

On June 1, 2017, Google will cease development of Flash in the IMA SDKs. This will end support for the IMA SDK for Flash, as well as support for Flash VPAID ads in the HTML5 SDK. We strongly encourage all publishers still using the Flash SDK to migrate to the HTML5 SDK. We also strongly encourage advertisers still trafficking Flash VPAID ads to migrate those ads to JavaScript VPAID.

What does this mean for the Flash SDK?

We will not actively prevent ad serving to the Flash SDK. However, new releases will stop after June 1st and we will no longer fix bugs or answer support questions. If ad serving or playback stops working after this date for the Flash SDK, it will not be fixed. We strongly encourage you to migrate to the HTML5 SDK.

What does this mean for the HTML5 SDK?

We will no longer support Flash VPAID ads in the HTML5 SDK. Flash VPAID ads served to the HTML5 SDK will not be rendered and the SDK will fire an error. We strongly encourage you to migrate your Flash VPAID ads to JavaScript VPAID.

As always, if you have any questions, feel free to contact us via the support forum.