Skip to end of metadata
Go to start of metadata

Show Instream Video Ads

This page describes how to use the SDK to fetch and display instream video ads.

On This Page


Step 1. Include the SDK in your project

As of the version 3.0 release, the SDK has instream video support. For instructions on how to integrate the SDK, see Integrate the SDK.

Step 2. Initialize the Video Ad Object

A video ad can be fetched and displayed with as few as three methods initWithPlacementId:, loadAdWithDelegate: and playAdWithContainer:withDelegate:. Defining the delegates for loading and playback will provide granular feedback for the video ad lifecycle.

First, initialize ANInstreamVideoAd with the placement ID.

Step 3. Load the Video Ad

Second, load the video ad and (optionally) define the ANInstreamVideoAdLoadDelegate.

Using the ANInstreamVideoAdLoadDelegate is highly recommended it indicates when the load is complete or, alternatively, whether an error occurred during load.

The delegates return the instance of ANInstreamVideoAd, expressed as a reference to its superclass ANAdProtocol which is shared with other Mobile SDK ad formats. The video ad object retains state that may be useful to reference during the lifecycle of the video ad.

Video ad state includes the placement ID, whether the video ad was clicked or skipped, and error feedback in the case of failure. (For complete details, see ANInstreamVideoAd.h .)

Step 4. Show the Video Ad

Third and finally, display the video ad over your content container UIView and define the ANInstreamVideoAdPlayDelegate.

The delegate methods return the instance of ANInstreamVideoAd, expressed as a reference to its superclass ANAdProtocol which is shared with other Mobile SDK ad formats. In addition to returning video ad state, the required method adDidComplete:withState: indicates when the video ad has completed.

ANInstreamVideoAdPlayDelegate contains many useful optional methods that further define video ad playback state and lifecycle for both the video ad and the landing page. (See ANInstreamVideoAd.h for complete details.)

Choose Which Browser Opens the Landing Page

When the video ad is clicked, video ad playback is paused and the click tracker is fired. Then, the click-through URL is opened in the in-app browser OR in the native browser according to the setting of the opensInNativeBrower property:

  • In-app Browser: Click-through content loads within the app in a pop-up UIView.
  • Native Browser: The app is suspended so the click-through content may load in the native browser.

The following properties are exposed by ANInstreamVideoAd to manage the target browser and whether the landing page loads before or after the landing page is displayed.

When the user returns from the browser, the video ad will resume playback.

Load More Than One Video Ad per Session

Any number of video ads may be loaded in a single session. Accomplish this by calling initWithPlacementId: and loadAdWtihDelegate: once for each video ad object.

Fetch the Attributes of a Loaded Video Creative

Once the video is loaded, you may retrieve various attributes of the creative:

Determine Ad Play Progress

You can determine how far the adPlay has progressed.

Video Ad Fullscreen Display

The Xandr Mobile SDK provides no functionality for displaying video ads or developer designated content in full screen mode. The video ad container automatically appears over the frame of the content container view using the same dimensions and positioning of the content container view. (See above playWithAdContainer:withDelegate:.)

This means you have control over whether the video ad displays in full screen mode by managing the frame of the content container view. By extension, if you want to give control over full screen mode to the user, you must provide appropriate interface options to the user.

Video Playback Controls

In iOS, it is idiomatic to use the transport controls provided by AVPlayerViewController with property showsPlaybackControls. This method is incompatible with Xandr's Mobile SDK because, in this case, the full screen option creates a modal view which displays over all current views, obscuring the video ad container which displays over the content container. Full screen functionality for the video ad must be handled some means other than creating a modal view.


Known Issues

Mute Button Doesn't work on iOS 9 and below

The mute/unmute button on the video ad player doesn't work for iOS 9 and below. This is a known limitation with this version of the operating system. The user can still turn sound on and off using the volume buttons on the device.


Maintain references to VideoAd objects

It is your responsibility to keep a reference to the VideoAd object. It is not cached by the SDK.

Step 1. Include the SDK in your project

If you use Maven, use the following Gradle config to install the version of the SDK with instream video support:

If you prefer to download the source code, you can can get the latest release from Github.

Step 2: Cache the Video Ad

To cache a video ad, set up a request object and supply it with either:

  • A placement ID (as shown in the example below), or
  • A combination of your Xandr member ID and an inventory code

Then register a VideoAdLoadListener which will signal whether the ad load succeeded or failed. This is optional but strongly recommended. If you don't set the VideoAdLoadListener, you can use the VideoAd.isReady() method to check whether the ad is available.

After that, call VideoAd.loadAd() to start caching the ad.

Step 3: Set up the Video Playback Listener

Before showing the video ad, you'll need to set up the mandatory VideoPlaybackListener. The onAdCompleted() notification is required to show your content video after the ad finishes playing.


Step 4: Pass Activity Lifecycle Events to the Ad

Pass on the Activity Lifecycle callback events to VideoAd as shown below:

Step 5: Show the Video Ad

You are now all set to show the Video Ad by calling playAd() as shown below. Remember to pause your content video player before calling VideoAd.playAd():

Fetch the Attributes of a Loaded Video Creative

Once the video is loaded, you may retrieve various creative attributes:

Determine Ad Play Progress

You can determine how far the adPlay has progressed by retrieving the amount of time that has elapsed since the ad began playing:

A Complete Example

See below for a complete working example of showing an instream video ad using the Android SDK.

 Click to expand

Related Topics