SDK 4.x Integration

Upcoming: not released yet

TruexAdRenderer-tvOS 4.x is not released yet. This page describes the planned integration, and details such as the final version number and minimum tvOS version will be confirmed with the release. For the current release, see SDK 3.x Integration.

SDK 4.x fully supports both TrueX and IDVx ads. Your app code is the same for both.

Adding the SDK

TruexAdRenderer-tvOS 4.x will be distributed through Swift Package Manager and CocoaPods, like 3.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 the 4.x version, and add the TruexAdRenderer product to your app target.

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', '~> 4.0'
end

Importing

Swift

import TruexAdRendererFramework

Objective-C

@import TruexAdRendererFramework;

It provides TruexAdRenderer, which renders the ad and is controlled by your app, and the TruexAdRendererDelegate protocol, which your app implements to receive events.

Quick Example

A complete start of an Infillion ad, where adParameters is the dictionary resolved from the VAST response. It works for TrueX and IDVx ads:

Swift

import TruexAdRendererFramework

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

    func startInfillionAd(adParameters: [String: Any]) {
        truexAdCreditReceived = false
        guard let renderer = TruexAdRenderer(adParameters: adParameters as NSDictionary, 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 onAdFreePod() {
        // Remember the reward, act on it in onAdCompleted
        truexAdCreditReceived = true
    }

    func onAdCompleted(_ timeSpent: TimeInterval) {
        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 TruexAdRendererFramework;

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

@implementation PlayerViewController

- (void)startInfillionAd:(NSDictionary *)adParameters {
    self.truexAdCreditReceived = NO;
    self.truexAdRenderer = [[TruexAdRenderer alloc] initWithAdParameters:adParameters 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)onAdFreePod {
    // Remember the reward, act on it in onAdCompleted:
    self.truexAdCreditReceived = YES;
}

- (void)onAdCompleted:(NSTimeInterval)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

The renderer is controlled with the same methods as in SDK 3.x:

Method	Description
initWithAdParameters:delegate:	Creates the renderer with the adParameters dictionary and starts the ad request.
start:	Shows the ad on the view controller you pass. It should cover the entire screen. After it, wait for a terminal event.
stop	Stops the renderer and releases its resources. Call it after a terminal event or when your app must end the ad. A stopped renderer cannot be reused.
pause	Pauses the ad's videos, audio, and timers.
resume	Resumes a paused renderer.

Swift

init?(adParameters: NSDictionary, delegate: TruexAdRendererDelegate)
func start(_ baseViewController: UIViewController)
func stop()
func pause()
func resume()

Objective-C

- (instancetype)initWithAdParameters:(NSDictionary *)adParameters
                            delegate:(id<TruexAdRendererDelegate>)delegate;
- (void)start:(UIViewController *)baseViewController;
- (void)stop;
- (void)pause;
- (void)resume;

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];
}