AppleTV SDK Integration Guide
This integration guide explains how to integrate Xandr's AppleTV SDK into your AppleTV application, so you can use Xandr's client-side ad insertion to bid on, track, and measure client-side video advertising within your app. The instructions and examples assume the following:
- You're developing against Apple tvOS 12.0 or higher.
- You have existing instances of AVPlayer and AVPlayerView Controller in your development environment
- You're using the Swift code libraries at https://swift.org/core-libraries/#foundation. The minimum version is SWIFT 4.2.
- You're using Xcode v10.0 or higher.
This application supports the
The following sections explain the steps needed to complete the integration, provide a reference for customization options, suggest best practices, and make recommendations for developers who prefer to use Objective-C.
Setting Up the Integration
1. Set Up and Import CocoaPods
CocoaPods is used to distribute Xandr's SDK and integrate it into your app. Use the following links to install CocoaPods and add it to your project.
- Installing CocoaPods On Your System (cocoapods.org)
- Adding CocoaPods To Your Xcode Project (cocoapods.org)
You can use the following code in your pod spec file:
2. Import Xandr's
AppleTV SDK module into
Use the following commands:
3. Add the
AdControllerProtocol protocol to
Use the following commands:
4. Make your instances of
Use the following commands:
5. Create an instance of AdController
The adController object should be scoped within UIControllerVIew. Use the following command:
6. (Optional) Define the AdSlot object
We provide the
AdSlot object as a parameter for communication between application and SDK.
AdSlot represents an ad break (or "ad pod") that contains multiple VAST objects. As you can see in the example, the
VastData array accommodates multiple ads in a single break.
Initial "setup" method will return `Array<AdSlot>` representing VMAP ad breaks.
7. Implement the required "adPlaybackControllerDidSetup" delegate method
Use this delegate method in UIViewController to account for preroll ads before content playback.
8. Implement the required
adPlaybackControllerShouldStartAd delegate method
This delegate method must be implemented in UIViewController to notify SDK you are ready for video ad playback. When the SDK determines that it is time to show a video ad, it will pause the content video and invoke this method with a single "AdSlot" object. The publisher application can then implement any ad-specific behavior. Note that this function should return
true. If it returns
false, the ad will not be shown.
9. Implement the required
adPlaybackControllerDidNotifyAdSlotEnded delegate method
This delegate method must be implemented in UIViewController so the SDK can notify the program that the video ad slot has finished playing all the ad creatives. When this delegate is called, the SDK will resume playback of the content video.
10. Implement additional delegate methods
Implementing these delegate methods is required. However, they can remain stub functions.
setup() method to initialize the SDK and request an ad. When the SDK is ready, it will invoke the
adPlaybackControllerDidSetup delegate method. Note that passing
contentUIViewController allows the SDK to stop content video playback when it is time to show an ad break, as well as to show ad break marks on the content video timeline.
To initialize the Apple TV SDK, contentVideoPlayer needs to have video assets at the time when setup() is called.
The following examples show how to invoke setup for VMAP, for a Xandr placement set, for a VAST URL, and for Xandr VAST placement.
pauseAd()/resumeAd() to control the video ad.
getPauseStatus() will return the current pause state of the ad.
To render a skip button, Implement the
adPlaybackControllerDidNotifyAnEvent() delegate method. The SDK logic adds a target to handle
UIControlEvents.primaryActionTriggered which will call an API
VideoEvent.timeToShowSkip trusts the VAST
Customizing SDK Behavior
You can use the
setOptions() method to specify how you want the SDK to look, what text you want to display with ads, whether the video ad displays a skip button, and other features. Note that
setOptions() must be invoked before
All these settings are optional. The following example shows how to set them:
setOptions() Parameter Reference
The width of the ad indicator in pixels. The ad indicator is the section of the ad indicating it is advertising, and not requested content.
The width of the left margin of the ad indicator in pixels.
The height of the bottom margin of the ad indicator in pixels.
The background color of the ad indicator.
The height of the ad indicator in pixels.
The font color of the ad indicator.
The alpha channel (transparency) value of the ad indicator. 1.0=non-transparent. 0.5=50% transparent. 0=completely transparent (and therefore invisible).
The width of the ad countdown in pixels. The ad countdown is the area that displays the number of seconds the ad plays for. If the ad is skippable, it displays the number of seconds until the viewer can click the skip button.
The height of the ad countdown in pixels.
The text of the ad indicator (for example
Whether a skip button is displayed, allowing the viewer to skip the ad.
Whether the publisher app, not Xandr, should control the remote trackpad's gesture action. To let Xandr override the normal gesture and enable a skip action, set this parameter to
Sample Code for UIViewController
This example uses Swift.
Tips and Best Practices
Use the following best practices when implementing the SDK in your app.
Updating the DFP Correlator
When you call a DFP tag with ANTVSDK, the correlator ensures the publisher receives a proper response from the DFP server. Make sure you change the
correlator parameter on your tag every time you make this call, as shown in the following example:
Letting the SDK initiate the content video
Your application should not start the content video on its own: it should wait until the SDK has loaded ads, and possibly shown a pre-roll ad. Implementing adPlaybackControllerDidSetup ensures the SDK starts your content video. When you use this method, preroll ads will be properly displayed before the content video in your app begins.
tvOS ARC(Automatic Reference Counting) checks and cleans most of the used objects in ANTVSDK that are not necessary at the time when the publisher application's UIViewController is dismissed. However, to support and ensure the validity of ARC, calling
adController.dismiss() on the block of
deinit block of the publisher applications's UIViewController (as shown in the following example) is required.
Testing in Non-Secure Mode
By default, Xcode does not support non-secure HTTP requests. Certain development-time testing and debugging situations might require using non-secure HTTP tags. To temporarily enable full access to HTTP protocol, check the "Project Info" tab to make sure the project allows arbitrary loads.
Managing x86_64 and ARM64 Binary Versions
A Framework "ANTVSDK.framework" includes x86_64 and ARM64 binary to support both an emulator and an actual Apple TV device. In case you don't want to include the x86_64 binary in your application because of Apple AppStore guidelines, you can simply remove it using
lipo, as shown in the following example:
You can then check to see if the library only contains the ARM64 binary:
Objective-C Project Requirements
As a default, XCode doesn't have a setting to use Swift Standard Libraries for Objective-C projects. For an Objective-C-based publisher application, you'll need to set the "Always Embed Swift Standard Libraries” setting to Yes in the Build Settings for the IDE.