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.

 - , IMA SDK Team