tvOS Framework Integration Guide Server-Side Ad Insertion (SSAI)

The BrightLine tvOS SDK is an Objective-C framework that can be integrated within an Objective-C or Swift application. Apple TV BrightLine ad experiences are rendered using the UIKit framework.

1.1 Linking required libraries in Xcode

From the application's target window, link the frameworks in Xcode in the "Frameworks, Libraries, And Embedded Content" section in the "General" tab.

1.2 Implement BLCoreEventDelegate to receive callbacks

The BLCoreEvents relate to the SDK and BrightLine ad life cycle.

Objective-C

				
@interface ViewController ()>BLCoreEventDelegate<
@end
@implementation ViewController
@end


// ##### REQUIRED FOR DISPLAYING THE AD #####

-(void)BLInitialize:(NSString*)libVersion{
	// An SDK event called when framework receives publisher configuration response successfully and returns the current SDK version
}

-(void)BLInitializeFailed:(NSString*)libVersion: (NSError*)error{
	// An SDK event called when framework failed to get publisher configuration response
}


// ##### OPTIONAL EVENTS #####

-(void)BLMicrositeWillOpen{
	// An SDK event called when the microsite will appear but has not yet appeared
}

-(void)BLOverlayDidClose{
	// An Ad event called when the overlay is closed
}

-(void)BLOverlayDidOpen{
	// An event called when the overlay opens
}

-(void)BLMicrositeDidClose{
	//An Ad event called when microsite closes
}

-(void)BLMicrositeDidOpen{
	// An Ad event called when microsite opens
	// Example: if app is entering foreground and microsite was open on enter background, don’t resume the commercial spot
}

-(void)BLManifestRequested{
	// An SDK event called when publisher configuration is requested
}

-(void)BLManifestLoaded{
	// An SDK event called when publisher configuration is loaded
}

-(void)BLManifestUnavailable{
	//An SDK event called when publisher configuration is unavailable
}

-(void)BLAdRequested{
	// An Ad event called when Ad is requested from Ad server
}

-(void)BLAdUnavailable{
	// An Ad event called when Ad is unavailable
}

-(void)BLAdLoaded{
	// An Ad event called when Ad is loaded and the hosting application should trigger video playback if owning video controller
}

-(void)BLAdDestroyed{
	// An event called when Ad is completely removed from memory and is no longer displayed. Invoked by calling hideAd method externally or internally in the SDK
}

-(void)BLPreferredFocusView:(UIView*)focusView{
	// An event called during the spot ad to request focus to the overlay. The hosting application should implement the UIViewController preferredFocusedView or preferredFocusEnviornments. This is required if the hosting applications owns the video player
}
				
			

Swift

				
@UIApplicationMain
Class AppDelegate: UIResponder, UIApplicationDelegate, TVApplicationControllerDelegate, BLCoreEventDelegate { 
	var window: UIWindow?
	var appController: TVApplicationController?
}


// ##### REQUIRED FOR DISPLAYING THE AD #####

func blInitialize(_libVersion: String!) {
	//event called when framework receives publisher configuration response successfully and returns the current SDK version
}

func blInitializeFailed(_libVersion: String!, _error: Error!) {
	//event called when framework failed to get publisher configuration response
}


// ##### OPTIONAL EVENTS #####

func blMicrositeWillOpen() {
	//event called when the microsite will appear but has not yet appeared
}

func blOverlayDidOpen() {
	//event called when the overlay opens
}

func blOverlayDidClose() {
	//event called when the overlay is closed
}

func blMicrositeDidOpen() {
	//event called when microsite opens
	//example: if app is entering foreground and microsite was open on enter background, don’t resume the commercial spot
}

func blMicrositeDidClose() {
	//event called when microsite closes
}

func blManifestRequested(){
	//event called when publisher configuration is requested
}

func blManifestLoaded(){
	//event called when publisher configuration is loaded
}

func blManifestUnavailable(){
	//event called when publisher configuration is unavailable
}

func blAdRequested(){
	//event called when Ad is requested
}

func blAdUnavailable (){
	//event called when Ad is unavailable
}

func blAdLoaded (){
	//event called when Ad is loaded and showAd can be called
}

func blAdDestroyed (){
	//event called when Ad is completely removed from memory and is no longer displayed
}

func blPreferredFocus(_ focusView: UIView!){
	// An event called during the spot ad to request focus to the overlay. The hosting application should implement the UIViewController preferredFocusedView or preferredFocusEnviornments. This is required if the hosting applications owns the video player
}
				
			

1.5 Compiling your application

Compile your application to ensure no errors occurred. If successful, the SDK is correctly integrated and ready for usage.

1.6 App Transport Security (ATS)

The BrightLine SDK framework is initialized with the configuration and analytics URL provided by BrightLine during the onboarding process. If you haven't received your configuration URL yet, use the example configuration URL below.

Example configuration URL

https://services.brightline.tv/api/v3/config/1018

Analytics root URL

https://events.brightline.tv/track

Objective-C

				
[[BLCore sharedManager]initFramework: @"put the configuration URL here" withAnalytics: @"put the analytics URL here", withDelegate:self];
				
			

Swift

				
BLCore.sharedManager().initFramework("put the configuration URL here", withAnalytics: "put the analytics URL here", withDelegate: self)
				
			

BrightLine ads are displayed by calling the showAd method.

3.1 VAST trackingEvents ownership

The hosting application will be responsible for displaying the promotional ad, sending playback tracking events (start, firstQuartile, midPoint, thirdQuartile and complete).

The BrightLine SDK is responsible for sending companion ad tracking events (impression, acceptInvitation).

When integrating with a SSAI vendor (mDialog/Google DAI, Uplynk, FreeWheel, etc.), the hosting application will trigger the BrightLine SDK in the appropriate ad break event callback method with a data object that contains the CompanionAds node from the BrightLine VAST tag. Below are the typical steps when integrating.

1. Identify the appropriate ad break event callback method from the SSAI vendor during promotional ad playback
2. Once the ad break even callback is invoked, use the data object from the callback method to get access to the VAST CompanionAds node data.
3. Use the data object property that relates to the companion ad information and inspect the apiFramework attribute for value brightline.

From the vendor ad break callback, construct a JSON schema (ad definition) indicated below from the vendor ad data object.

Construct JSON ad definition from SSAI vendor ad data object

				
{
	"apiFramework": "brightline",
	"companion": {
		"url": "",
		"trackingEvents": {
			"impression": [],
			"acceptInvitation": []
		}
	}
}
				
			

Ad definiton attributes

• apiFramework - this attribute should be populated from the vendor ad data object.
• companion.url - this attribute should be populated with the URLs from the StaticResource element.
• companion.trackingEvents.impression - this attribute should be populated with all the URLs for when the overlay is displayed.
• companion.trackingEvents.acceptInvitation - this attribute should be populated with all the URLs for when the overlay is clicked.

3.2 Call the showAd method

Objective-C

				
// the variable "adResponse" is the constructed ad definition object from the SSAI vendor ad data object 
NSString * adResponse;
[[BLCore sharedManager]showAd:@"pass in the view (UIView) that will display the ad" withDefinition:adResponse];
				
			

Swift

				
(BLCore.sharedManager() as AnyObject).showAd("pass in the view (UIView) that will display the ad", withDefinition:adResponse)
				
			

The hideAd method should be called when the promotional ad ends. The hideAd method will remove the ad from memory and display. As a result, the BLAdDestroyed event callback is invoked.

Objective-C

				
[[BLCore sharedManager]hideAd];
				
			

Swift

				
(BLCore.sharedManager() as AnyObject).hideAd();
				
			

TVML/TVJS application

Add this event listener to the player object to prevent the actions from occurring if the microsite is not open. See the TVML sample application for the full source code.

				
player.addEventListener("shouldHandleStateChange", function(event) {
	//console.log('shouldHandleStateChange='+event.state);
	if (event.state == "scanning" || (event.state == "paused" && !isMicrositeOpen)) return false;
	return true;
});
				
			

Objective-C (native) application