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 DAI SDKs, apps make a stream request for ad and content video—either VOD or live content. The SDK then returns a combined video stream, so that you don't have to manage switching between ad and content video within your app.
Select the DAI solution you're interested in
Play live streams registered with Google Cloud Video Stitcher API
This guide demonstrates how to use the IMA DAI SDK for iOS to request and play a livestream for an event registered with the Google Cloud Video Stitcher API, and how to insert an ad break during playback.This guide expands on the basic example from the Get started guide for IMA DAI.
For information on integrating with other platforms or on using the IMA client-side SDKs, see Interactive Media Ads SDKs.
Set up a Google Cloud project
Set up a Google Cloud project and configure service accounts to access the project.
Register a livestream event using your own content livestream or a test live stream. This guide expects an HLS stream.
Enter the following variables for use in the IMA SDK:
- Location
- The Google Cloud region
where your live config was created:
LOCATION
- Project number
- The Google Cloud project number using the Video Stitcher API:
PROJECT_NUMBER
- OAuth token
A service account's short lived OAuth token with the Video Stitcher user role:
OAUTH_TOKEN
Read more about creating short-lived credentials for service accounts. The OAuth token can be reused across multiple requests as long as it has not expired.
- Network code
The Ad Manager network code for requesting ads:
NETWORK_CODE
- Live config ID
- The live config ID you specified when creating your livestream event:
LIVE_CONFIG_ID
- Custom asset key
- The Ad Manager custom asset key generated during the process of registering
a livestream event
with the Video Stitcher API:
ASSET_KEY
- User context
- The user context for tracking requests. Can be
nil
. Defaults tonil
in this guide.
Download and prepare the basic example
Download the IMA DAI examples for iOS and extract the Basic Example into a new folder. This example is an Xcode project that relies on Cocoapods to load the IMA SDK.
To prepare the sample to run, make sure CocoaPods is installed, then open the basic example's folder in the terminal and run the following command:
pod install --repo-update
Once that command completes, you see a file named BasicExample.xcworkspace
in
your project folder. Open this file in Xcode and run the sample to ensure that
the test video and ads play as expected.
Request a livestream
To replace the sample stream with your livestream, you need to use the
IMAVideoStitcherLiveStreamRequest
class that automatically creates an ad
session with Google Ad Manager. You can use the Google Ad Manager UI to locate
the generated DAI sessions for
monitoring and debugging purposes.
In the existing sample, there are examples for requesting a VOD stream or a
livestream from Google's DAI servers. To make the sample work with the Google
Cloud Video Stitcher API, you will need to replace the current requestStream
function with one that uses the IMAVideoStitcherLiveStreamRequest
class:
ViewController.m
#import <GoogleInteractiveMediaAds/GoogleInteractiveMediaAds.h>
/// Fallback URL in case something goes wrong in loading the stream. If all goes well,
/// this will not be used.
static NSString *const kTestAppContentUrl_M3U8 =
@"//devimages.apple.com/iphone/samples/bipbop/bipbopall.m3u8";
static NSString *const kLiveConfigId = @"LIVE_CONFIG_ID";
static NSString *const kLocation = @"LOCATION";
static NSString *const kProjectNumber = @"PROJECT_NUMBER";
static NSString *const kOAuthToken = @"OAUTH_TOKEN";
static NSString *const kNetworkCode = @"NETWORK_CODE";
static NSString *const kCustomAssetKey = @"ASSET_KEY";
@interface ViewController () <IMAAdsLoaderDelegate, IMAStreamManagerDelegate>
...
- (void)requestStream {
// Create an ad display container for ad rendering.
IMAAdDisplayContainer *adDisplayContainer =
[[IMAAdDisplayContainer alloc] initWithAdContainer:self.videoView
viewController:self
companionSlots:nil];
// Create an IMAAVPlayerVideoDisplay to give the SDK access to your video player.
IMAAVPlayerVideoDisplay *imaVideoDisplay =
[[IMAAVPlayerVideoDisplay alloc] initWithAVPlayer:self.contentPlayer];
IMAVideoStitcherLiveStreamRequest *request =
[[IMAVideoStitcherLiveStreamRequest alloc] initWithLiveStreamEventID:kLiveConfigId
region:kLocation
projectNumber:kProjectNumber
OAuthToken:kOAuthToken
networkCode:kNetworkCode
customAssetKey:kCustomAssetKey
adDisplayContainer:adDisplayContainer
videoDisplay:imaVideoDisplay
userContext:nil];
[self.adsLoader requestStreamWithRequest:request];
}
Run the project, then you can request and play your custom livestream.
Insert an ad break
The Google Cloud Video Stitcher API inserts ads retrieved from the ad tag for each ad break. Ad breaks are denoted in the manifest using ad markers. Ad markers are inserted by the live stream encoder.
If you are using your own live stream, you need to insert the ad marker. For more information on the supported HLS and DASH ad markers, see the ad markers documentation.
If you created a live stream using the Google Cloud Livestream API, insert an ad break channel event.
The ad is played immediately after the ad break is inserted.
Clean up
Now that you have successfully hosted a live stream using the Google Cloud Video Stitcher API and requested it using the IMA DAI SDK for iOS, it's important to clean up any serving resources.
Follow the Unregister livestream events guide to end your livestream event.