SHAWN BUSOLITS: Welcome to the Quickstart video
for the IMA HTML5 SDK.
The IMA SDK for HTML5 allows you to display inline videos
and overlay ads on web video content.
Its most common use is to show preroll video ads
before a video is played on a website,
but it can also be used to show TV-style commercial ad
breaks in long-form content.
When we're done with this video, you'll
have a simple web page that plays
video ads onto content video.
If you want to follow along, download the sample video
player we've hosted at the link on the screen now.
Once you have that file downloaded and unzipped,
you can host the sample web page by navigating
to the unzipped folder in your terminal or command prompt
and running python -m SimpleHTTPServer.
That will host the sample web page at local host port 8,000.
Let's see what the sample video player looks like.
As you can see, the page currently
just contains a Play button.
When we click that, we see our content video.
Now let's take a look at the files that make this happen.
The sample video player contains three files--
index.html, which is the sample HTML for our sample web page,
style.css, which is the style sheet that lays out the sample
web page, and ads.js, which is where all of our Javascript
will go.
Currently, this is set up to just play the content video
when we click the Play button.
We're going to do all of our work in the JavaScript file,
but let's first walk through the HTML
so we know what we're working with.
The two most important things in this HTML file
are the video player and the ad container div.
The video player will play our content,
and the ad container will be populated by the SDK
to show ads on top of the video player.
In most web browsers, the SDK will use its own video player
to play ads, not your player.
That SDK-owned player, along with any ad
UI, will be created in this div.
We also create a Play button at the bottom of the page
to start the video.
You'll also notice that we're loading our CSS
file in the head of the HTML.
This sets up our component sizes and locations
to ensure our ad container is on top of
and completely covers the video player.
The SDK will automatically show the div
to play ads, and hide it when content is playing.
Lastly, at the bottom of the page,
we load the IMA SDK, followed by the ads.js file in which we'll
be working.
Now that we have a basic idea of the HTML for the page,
let's take a look at the JavaScript.
Currently, it's getting handles to the video player
and the Play button, and playing the video when
a user clicks the button.
Let's modify this to request and show
an ad before our content plays.
First, we're going to create an ad display container.
This SDK object holds a handle to the ad container
div we talked about in the HTML file,
as well as your video player.
Remember earlier that I said the SDK will use its own video
player in most browsers?
We give it a handle to your video player
here for those instances where it can't use its own video
player, like older versions of iPhone and Android,
which only support one video player at a time.
In those cases, the SDK will reuse your video player.
Now that we have an ad display container,
we can create an ads loader.
An ads loader is used by the SDK to request a vast ad
response from an ad server.
This response contains tracking URLs, as well as
links to the media for the ad.
We're going to listen for two events on the ads loader--
ads manager loaded and ad error.
Ads manager loaded will be fired when the SDK has successfully
created an ads manager for us.
We'll talk about what an ads manager is in a minute.
Ad error will be fired if something
goes wrong in the process of requesting ads.
Let's fill in that ad error handler now.
When something goes wrong requesting ads,
we've got no chance of playing ads,
so we'll just log the error and play our content video.
We'll fill in the ads manager loaded handler in a bit.
Next, we'll add a content ended handler
to let the SDK know when to play postrolls.
We'll listen for the video player's ended event,
and call content complete on the ads loader
to let it know it can play postrolls, if it has any.
Now that we've created our ads loader
and assigned event listeners, let's build our ads request.
The ads request object contains all the information
the SDK needs to request ads for your video player.
First, we provide an ad tag URL, which
points to the vast response that the SDK needs in order
to know which ad to play and where to get it from.
Then we provide linear and non-linear ad slot widths
and heights.
These tell the SDK what size ads you want to show.
The linear width and height should
be the same as your video player,
and the non-linear width and height
can be anything that will fit inside your ad container.
The most common type of non-linear ad
is a bottom-third ad, which fills the bottom third
of the video player.
So we'll set the width to the full width of our player,
and the height to one-third the full height of our player.
Now that we've built our ads request,
we can give it to the ads loader to request ads.
We're going to modify the onPlay button click
function to do this when the user clicks the Play button.
We'll also initialize the ad display container here.
This must be done as the result of a user action,
and clicking on the Play button will be that user
action for this sample.
If the ads loader successfully loads ads using your ads
request, it will fire the ads manager loaded
event I mentioned earlier.
This event will give you a handle to an ads
manager, which is your main interface with the SDK.
It provides ad interactions like pause, resume, and volume
control.
Let's write the handler for that event now.
The first thing we'll do is store a local handle to the ads
manager provided in the ads manager loaded event.
I'm going to declare the ads manager
variable on the global scope, so that we'll have access to it
in the functions we write later.
We retrieve the ads manager from the ads manager loaded event
and provide a handle to our video player, which
allows the SDK to track our content position if we
want to play midrolls.
Now we add a handler for an ad error.
This will be fired if something goes wrong in the SDK
during ad playback-- for example,
if the SDK gets a badly encoded media file
and needs to abort playback.
The ad error handler will be the same as the ads loader
error handler, but we'll modify it to also destroy
the ads manager if it exists.
Now we need to add content pause and resume handlers.
Because the SDK plays ads in a separate player,
it needs to tell us to pause our content when ads start.
Otherwise, we'd have our content playing
at the same time as the ads.
That's what this event is for.
The content pause handler will pause your content
so an ad can play.
We also need to remove our content ended handler here.
If we're in a browser that causes the SDK to reuse
our content player, leaving that listener enabled
during ad playback will cause us to call
content complete on the ads loader when the ad finishes.
And we only want that to be called
when our content finishes.
Similarly, we'll declare our contact
resume handler, which will be called
when an ad break finishes.
This readds our content ended handler, and plays our content.
Once we've got our ads manager handler set up,
we can initialize and start playing ads.
The init method takes the size of your video player
and the view mode.
The view mode is the mode you consider your player
to be in when you start ads, either full-screen,
if the video is full-screen, or normal,
if it's embedded in a page.
Since this player is embedded in the page,
we'll pass in Normal for the view mode.
If you're using ad rolls to play an ad playlist,
your preroll will start playing ads immediately on init.
For single ads, preroll playback won't
start until we call Start.
Now let's take a look at what we've got.
Now when I load the page and click the Play button,
we see a preroll ad.
Once the preroll finishes, we see our content video.
If we keep watching, we'll see some midrolls breaking up
our content.
And that's all there is to it.
If you're looking to expand on this sample,
check out our advanced sample on GitHub
and the rest of our documentation
on developers.google.com.
We've also got some more sample tags
so you can play around with different ad formats.
These will all work in your player
without any additional modifications.
If you have any questions, feel free to visit us
on the support forum, and we'll see you around.
[MUSIC PLAYING]