SDK 3.x Integration

Adding the SDK

TruexAdRenderer-tvOS 3.x is distributed through Swift Package Manager and CocoaPods. The current version is 3.15.3, and it requires tvOS 13.0 or later. SDK 3.x renders TrueX ads. For IDVx, see SDK 4.x.

Swift Package Manager

1. In Xcode, go to File > Add Package Dependencies...
2. Enter the repository URL: https://github.com/socialvibe/TruexAdRenderer-tvOS-Swift-Package
3. Select version 3.15.3 or later, and add the TruexAdRenderer product to your app target.

Or, in a Package.swift manifest:

dependencies: [
    .package(url: "https://github.com/socialvibe/TruexAdRenderer-tvOS-Swift-Package", from: "3.15.3"),
],
targets: [
    .target(
        name: "MyApp",
        dependencies: [
            .product(name: "TruexAdRenderer", package: "TruexAdRenderer-tvOS-Swift-Package"),
        ]
    ),
]

CocoaPods

Add the TrueX spec repository (socialvibe/cocoapod-specs) and the spec repository of the renderer's dependency next to the default one, then add the pod to your target:

source 'https://cdn.cocoapods.org/'
source 'https://github.com/socialvibe/cocoapod-specs.git'
source 'https://github.com/Innovid/cocoapods-spec.git'

target 'MyApp' do
  use_frameworks!
  pod 'TruexAdRenderer', '3.15.3'
end

The second extra source is required: CocoaPods looks up a pod's dependencies only in the sources listed in your Podfile, and the dependency is not in the public CocoaPods specs. TruexAdRenderer is delivered as a framework, not as a static library, so keep the use_frameworks! line in your target.

Importing

The SDK module is TruexAdRenderer:

Swift

import TruexAdRenderer

Objective-C

#import <TruexAdRenderer/TruexAdRenderer.h>

It provides:

• TruexAdRenderer - renders the ad and is controlled by your app
• TruexAdOptions - configuration options for the renderer, created with DefaultOptions(). Available from Objective-C only - see Using TruexAdOptions from Swift
• TruexAdRendererDelegate - the protocol your app implements to receive events, see Events

Renderer Container

The renderer presents the ad in its own view controller on top of the view controller you pass to start. That view controller should cover the entire screen - for example, the view controller that shows your player. Hide your player controls and any other extra UI while the ad is showing.

Quick Example

A complete start of an Infillion ad, where adParameters is the dictionary resolved from the VAST response. The Swift version creates the renderer through TruexRendererFactory, a small Objective-C helper described in Using TruexAdOptions from Swift:

Swift

import TruexAdRenderer

class PlayerViewController: UIViewController, TruexAdRendererDelegate {
    private var truexAdRenderer: TruexAdRenderer?
    private var truexAdCreditReceived = false

    func startInfillionAd(adParameters: [AnyHashable: Any]) {
        truexAdCreditReceived = false
        // Objective-C helper that sets supportsUserCancelStream, see below
        guard let renderer = TruexRendererFactory.renderer(withAdParameters: adParameters, delegate: self) else {
            // No renderer means no delegate events: continue the pod
            finishInfillionAd(skipRemainingAds: false)
            return
        }
        truexAdRenderer = renderer
        renderer.start(self)
    }

    private func disposeRenderer() {
        truexAdRenderer?.stop()
        truexAdRenderer = nil
    }

    // MARK: - TruexAdRendererDelegate

    func onAdStarted(_ campaignName: String) {
    }

    func onAdFreePod() {
        // Remember the reward, act on it in onAdCompleted
        truexAdCreditReceived = true
    }

    func onAdCompleted(_ timeSpent: Int) {
        disposeRenderer()
        finishInfillionAd(skipRemainingAds: truexAdCreditReceived)
    }

    func onAdError(_ errorMessage: String) {
        disposeRenderer()
        finishInfillionAd(skipRemainingAds: false)
    }

    func onNoAdsAvailable() {
        disposeRenderer()
        finishInfillionAd(skipRemainingAds: false)
    }

    func onUserCancelStream() {
        disposeRenderer()
        exitPlayback()
    }
}

Objective-C

#import <TruexAdRenderer/TruexAdRenderer.h>

@interface PlayerViewController () <TruexAdRendererDelegate>
@property (nonatomic, strong) TruexAdRenderer *truexAdRenderer;
@property (nonatomic, assign) BOOL truexAdCreditReceived;
@end

@implementation PlayerViewController

- (void)startInfillionAd:(NSDictionary *)adParameters {
    self.truexAdCreditReceived = NO;
    TruexAdOptions options = DefaultOptions();
    options.supportsUserCancelStream = YES;

    self.truexAdRenderer = [[TruexAdRenderer alloc] initWithAdParameters:adParameters
                                                                 options:options
                                                                delegate:self];
    if (!self.truexAdRenderer) {
        // No renderer means no delegate events: continue the pod
        [self finishInfillionAd:NO];
        return;
    }
    [self.truexAdRenderer start:self];
}

- (void)disposeRenderer {
    [self.truexAdRenderer stop];
    self.truexAdRenderer = nil;
}

#pragma mark - TruexAdRendererDelegate

- (void)onAdStarted:(NSString *)campaignName {
}

- (void)onAdFreePod {
    // Remember the reward, act on it in onAdCompleted:
    self.truexAdCreditReceived = YES;
}

- (void)onAdCompleted:(NSInteger)timeSpent {
    [self disposeRenderer];
    [self finishInfillionAd:self.truexAdCreditReceived];
}

- (void)onAdError:(NSString *)errorMessage {
    [self disposeRenderer];
    [self finishInfillionAd:NO];
}

- (void)onNoAdsAvailable {
    [self disposeRenderer];
    [self finishInfillionAd:NO];
}

- (void)onUserCancelStream {
    [self disposeRenderer];
    [self exitPlayback];
}

@end

finishInfillionAd and exitPlayback are your app's code - what they have to do is described in Handling Terminal Events. The renderer holds its delegate weakly, so keep a strong reference to the renderer while the ad is showing. If the renderer can't be created (nil), it will never call the delegate: continue the pod.

TruexAdRenderer Methods

initWithAdParameters

Swift

// Without options - the variant Swift can call directly
init!(adParameters: [AnyHashable: Any]!, delegate: TruexAdRendererDelegate!)

Objective-C

- (id)initWithAdParameters:(NSDictionary *)adParameters
                   options:(TruexAdOptions)options
                  delegate:(id<TruexAdRendererDelegate>)delegate;

Creates the renderer with the adParameters dictionary and starts the ad request to the Infillion ad server. The renderer calls onFetchAdComplete when the request is done.

You can create the renderer early, a few seconds before the ad break starts, to give it more time for the request, and call start once the player reaches the ad.

The parameters are:

• adParameters: the JSON payload from the VAST response, see Resolving adParameters
• options: a TruexAdOptions value, created with DefaultOptions()
• delegate: the object that receives the events

An optional slotType (preroll or midroll) can also be passed with the initWithAdParameters:slotType:options:delegate: variant.

In Swift the initializer returns an optional (init!), and the options: variant is not available - see Using TruexAdOptions from Swift.

start

Swift

func start(_ baseViewController: UIViewController)

Objective-C

- (void)start:(UIViewController *)baseViewController;

Shows the ad to the user. Call it when your app is ready to display the ad; it can be called any time after the renderer is created. If the ad request is not finished yet, the renderer waits for it, then presents its view controller on baseViewController and calls onAdStarted.

After calling start, wait for a terminal event and keep track of whether onAdFreePod has been called.

• baseViewController: the view controller the renderer presents its view controller on. It should cover the entire screen.

stop

Swift

func stop()

Objective-C

- (void)stop;

Stops the renderer immediately and releases its resources. Call it after a terminal event, and also when:

• the user leaves the playback screen while the ad is showing
• an unrelated error requires your app to stop the ad
• your own timeout for onFetchAdComplete or onAdStarted is reached

A stopped renderer cannot be resumed or reused - remove all references to it.

pause

Swift

func pause()

Objective-C

- (void)pause;

Pauses the ad's videos, audio, and timers. Call it whenever your app needs to pause the ad, for example when it moves to the background.

resume

Swift

func resume()

Objective-C

- (void)resume;

Resumes a paused renderer.

TruexAdOptions

Create the options with DefaultOptions(), then change the fields you need:

Option	Default	Description
supportsUserCancelStream	NO	If YES, closing the ad because the user wants to leave calls onUserCancelStream, so your app can exit the stream. If NO, back actions call onOptOut and onAdCompleted instead.
userAdvertisingId	nil	The id used for user ad tracking. If not set, the renderer keeps a random id for the installed app.
appId	nil	Used for internal tracking. If not set, the renderer uses the app's bundle identifier.

Using TruexAdOptions from Swift

TruexAdOptions is a C struct that holds Objective-C objects, and Swift cannot import that kind of struct. As a result, DefaultOptions() and the options: initializer are not visible from Swift: a Swift app can only call TruexAdRenderer(adParameters:delegate:), which uses the default options - so onUserCancelStream is never called.

To set the options from a Swift app, add a small Objective-C helper and expose it through your bridging header:

TruexRendererFactory.h

#import <TruexAdRenderer/TruexAdRenderer.h>

NS_ASSUME_NONNULL_BEGIN

@interface TruexRendererFactory : NSObject

+ (nullable TruexAdRenderer *)rendererWithAdParameters:(NSDictionary *)adParameters
                                              delegate:(id<TruexAdRendererDelegate>)delegate;

@end

NS_ASSUME_NONNULL_END

TruexRendererFactory.m

#import "TruexRendererFactory.h"

@implementation TruexRendererFactory

+ (TruexAdRenderer *)rendererWithAdParameters:(NSDictionary *)adParameters
                                     delegate:(id<TruexAdRendererDelegate>)delegate {
    TruexAdOptions options = DefaultOptions();
    options.supportsUserCancelStream = YES;
    return [[TruexAdRenderer alloc] initWithAdParameters:adParameters
                                                 options:options
                                                delegate:delegate];
}

@end

Bridging header

#import "TruexRendererFactory.h"

Swift

guard let renderer = TruexRendererFactory.renderer(withAdParameters: adParameters, delegate: self) else {
    finishInfillionAd(skipRemainingAds: false)
    return
}
truexAdRenderer = renderer
renderer.start(self)

App Lifecycle

Pause the renderer when your app moves to the background, and resume it when the app becomes active again:

Swift

override func viewDidLoad() {
    super.viewDidLoad()
    NotificationCenter.default.addObserver(self, selector: #selector(appWillResignActive),
                                           name: UIApplication.willResignActiveNotification, object: nil)
    NotificationCenter.default.addObserver(self, selector: #selector(appDidBecomeActive),
                                           name: UIApplication.didBecomeActiveNotification, object: nil)
}

@objc private func appWillResignActive() {
    truexAdRenderer?.pause()
}

@objc private func appDidBecomeActive() {
    truexAdRenderer?.resume()
}

override func viewDidDisappear(_ animated: Bool) {
    super.viewDidDisappear(animated)
    disposeRenderer()
}

Objective-C

- (void)viewDidLoad {
    [super viewDidLoad];
    [NSNotificationCenter.defaultCenter addObserver:self
                                           selector:@selector(appWillResignActive)
                                               name:UIApplicationWillResignActiveNotification
                                             object:nil];
    [NSNotificationCenter.defaultCenter addObserver:self
                                           selector:@selector(appDidBecomeActive)
                                               name:UIApplicationDidBecomeActiveNotification
                                             object:nil];
}

- (void)appWillResignActive {
    [self.truexAdRenderer pause];
}

- (void)appDidBecomeActive {
    [self.truexAdRenderer resume];
}

- (void)viewDidDisappear:(BOOL)animated {
    [super viewDidDisappear:animated];
    [self disposeRenderer];
}