IMA SDKs make it easy to integrate multimedia ads into your websites and apps. IMA SDKs can request ads from any VAST-compliant ad server and manage ad playback in your apps. With IMA client-side SDKs, you maintain control of content video playback, while the SDK handles ad playback. Ads play in a separate video player positioned on top of the app's content video player.
This guide demonstrates how to integrate the IMA SDK into a simple video player app. If you would like to view or follow along with a completed sample integration, download the simple example from GitHub. If you're interested in an HTML5 player with the SDK pre-integrated, check out the IMA SDK Plugin for Video.js.
IMA client-side overview
Implementing IMA client-side involves four main SDK components, which are demonstrated in this guide:
AdDisplayContainer
: A container object that specifies where IMA renders ad UI elements and measures viewability, including Active View and Open Measurement.AdsLoader
: An object that requests ads and handles events from ads request responses. You should only instantiate one ads loader, which can be reused throughout the life of the application.AdsRequest
: An object that defines an ads request. Ads requests specify the URL for the VAST ad tag, as well as additional parameters, such as ad dimensions.AdsManager
: An object that contains the response to the ads request, controls ad playback, and listens for ad events fired by the SDK.
Prerequisites
Before you begin, you'll need the following:
- Three empty files:
- index.html
- style.css
- ads.js
- Python installed on your computer, or a web server to use for testing
1. Start a development server
Since the IMA SDK loads dependencies using the same protocol as the page from which it's loaded, you need to use a web server to test your app. The simplest way to start a local development server is to use Python's built-in server.
- Using a command line, from the directory that contains
your index.html file run:
python -m http.server 8000
- In a web browser, go to
http://localhost:8000/
You can also use any other web server, such as the Apache HTTP Server.
2. Create a simple video player
First, modify index.html to create a simple HTML5 video element, contained in a wrapping
element, and a button to trigger playback. The following example imports the IMA SDK and sets up
the AdDisplayContainer
container element. For more details, see the
Import the IMA SDK
and
Create the ad container
steps respectively.
Add the necessary tags to load the style.css and ads.js files. Then, modify styles.css to make the video player responsive for mobile devices. Finally, in ads.js, declare your variables and trigger video playback when you click the play button.
Note that the ads.js code snippet contains a call to setUpIMA()
, which is
defined in the
Initialize the AdsLoader and make an ads request
section.
3. Import the IMA SDK
Next, add the IMA framework using a script tag in index.html, before the tag for
ads.js
.
4. Create the ad container
In most browsers, the IMA SDK uses a dedicated ad container element for displaying both ads and
ad-related UI elements. This container must be sized to overlay the video element from the
top-left corner. The height and width of the ads placed in this container are set by the
adsManager
object, so you don't need to set these values manually.
To implement this ad container element, first create a new div
within the
video-container
element. Then, update the CSS to position the element at the top-left
corner of the video-element
. Finally, add the createAdDisplayContainer()
function to create the
AdDisplayContainer
object using the new ad container
div
.
5. Initialize the AdsLoader and make an ads request
In order to request ads, create an
AdsLoader
instance. The AdsLoader
constructor takes an
AdDisplayContainer
object as an input and can be used to process
AdsRequest
objects associated with a specified ad tag URL. The ad tag used in this example contains a
10-second pre-roll ad. You can test this, or any, ad tag URL using the
IMA Video Suite Inspector.
As a best practice, only maintain one instance of AdsLoader
for the entire
lifecycle of a page. To make additional ad requests, create a new AdsRequest
object, but re-use the same AdsLoader
. For more information, see the
IMA SDK FAQ.
Listen and respond to ads loaded and error events using AdsLoader.addEventListener
.
Listen to the following events:
ADS_MANAGER_LOADED
AD_ERROR
To create the onAdsManagerLoaded()
and onAdError()
listeners, see the
following example:
6. Respond to AdsLoader events
When the AdsLoader
successfully loads ads, it emits an
ADS_MANAGER_LOADED
event. Parse the event passed to the callback to initialize the
AdsManager
object. The AdsManager
loads the individual ads as defined by
the response to the ad tag URL.
Ensure you handle any errors that occur during the loading process. If ads don't load, make sure that media playback continues without ads to avoid interfering with the user viewing the content.
For more details about the listeners set in the onAdsManagerLoaded()
function, see
the following sub-sections:
Handle AdsManager
errors
The error handler created for the AdsLoader
can also serve as the error handler for
the AdsManager
. See the event handler reusing the onAdError()
function.
Handle play and pause events
When the AdsManager
is ready to insert an ad for display, it fires the
CONTENT_PAUSE_REQUESTED
event. Handle this event by triggering a pause on the
underlying video player. Similarly, when an ad completes, the AdsManager
fires the
CONTENT_RESUME_REQUESTED
event. Handle this event by restarting playback on the
underlying content video.
For definitions of the onContentPauseRequested()
and
onContentResumeRequested()
functions, see the following example:
Handle content playback during non-linear ads
The AdsManager
pauses the content video when an ad is ready to play, but this
behavior doesn't account for non-linear ads, where the content continues to play while the ad is
displayed.
To support non-linear ads, listen for the AdsManager
to emit the
LOADED
event. Check if the ad is linear, and if not, resume playback on the
video element.
For the definition of the onAdLoaded()
function, see the following example.
7. Trigger click-to-pause on mobile devices
Since the AdContainer
overlays the video element, users cannot interact directly with
the underlying player. This can confuse users on mobile devices, who expect to be able to tap a
video player to pause playback. To address this issue, the IMA SDK passes any clicks that are not
handled by IMA from the ad overlay to the AdContainer
element, where they can be
handled. This does not apply to linear ads on non-mobile browsers, as clicking the ad opens the
clickthrough link.
To implement click-to-pause, add the adContainerClick()
click handler function called
in the on window load listener.
8. Start the AdsManager
To start ad playback, initiate and start the AdsManager
. To fully support mobile
browsers, where you cannot automatically play ads, trigger ad playback from user interactions
with the page, like clicking the play button.
9. Support player resizing
For ads to dynamically resize and match a video player's size, or to match changes to the screen
orientation, call adsManager.resize()
in response to window resize events.
That's it! You're now requesting and displaying ads with the IMA SDK. To learn about more advanced SDK features, see the other guides or the samples on GitHub.