Skip to end of metadata
Go to start of metadata

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  The minimum version is SWIFT 4.2. 
  • You're using Xcode v10.0 or higher. 

This application supports the /ptv and /vmap endpoints. 

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.

Sample Podfile

2. Import Xandr's AppleTV SDK module into UIViewController

Use the following commands:

3. Add the AdControllerProtocol protocol to UIViewController

Use the following commands:

4. Make your instances of AVPlayerViewController and AVPlayer available

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.


Implementation Methods

Call setup()

Invoke the 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 contentVideoPlayerViewControllercontentVideoPlayer, and 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.

Pause/Resume Ad

Invoke pauseAd()/resumeAd() to control the video ad. getPauseStatus() will return the current pause state of the ad.

Skip 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 skip(). This VideoEvent.timeToShowSkip trusts the VAST skipoffset attribute.

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 setup(). 

All these settings are optional. The following example shows how to set them:


setOptions() Parameter Reference

ParameterData TypeDescriptionExample
            ? = nil

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.

            ? = nil        

The width of the left margin of the ad indicator in pixels.  

            ? = nil

The height of the bottom margin of the ad indicator in pixels.

           ? = nil

The background color of the ad indicator.

            ? = nil

The height of the ad indicator in pixels.

            ? = nil

The font color of the ad indicator.

            ? = nil       

The alpha channel (transparency) value of the ad indicator. 1.0=non-transparent. 0.5=50% transparent. 0=completely transparent (and therefore invisible).

            ? = nil

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.

            ? = nil

The height of the ad countdown in pixels.

            ? = nil

The text of the ad indicator (for example Ad)

            ? = nil

Whether a skip button is displayed, allowing the viewer to skip the ad.

            ? = nil

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 false.


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. 

Memory management

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. 







  • No labels