SDK Integration

Adding the SDK

TruexAdRenderer-iOS is distributed through Swift Package Manager (recommended) and CocoaPods. The current version is 4.1.0, and it requires iOS 15.6 or later.

Swift Package Manager

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

Or, in a Package.swift manifest:

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

CocoaPods

Add the TrueX spec repository 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'

target 'MyApp' do
  use_frameworks!
  pod 'TruexAdRenderer-iOS', '4.1.0'
end

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 shows the ad in a UIView that you provide. It should cover the entire screen and sit above your video player - for example, the root view of your player view controller.

Hide as much other UI as possible while the ad is showing, including player controls, the status bar, and the home indicator:

Swift

override var prefersStatusBarHidden: Bool {
    return truexAdRenderer != nil
}

override var prefersHomeIndicatorAutoHidden: Bool {
    return truexAdRenderer != nil
}

Objective-C

- (BOOL)prefersStatusBarHidden {
    return self.truexAdRenderer != nil;
}

- (BOOL)prefersHomeIndicatorAutoHidden {
    return self.truexAdRenderer != nil;
}

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
        truexAdRenderer = TruexRendererFactory.renderer(withAdParameters: adParameters, delegate: self)
        truexAdRenderer?.start(view)
    }

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

    // MARK: - TruexAdRendererDelegate

    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()
    }

    func onPopupWebsite(_ url: String) {
        // See the onPopupWebsite event
    }
}

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];
    [self.truexAdRenderer start:self.view];
}

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

- (void)onPopupWebsite:(NSString *)url {
    // See the onPopupWebsite: event
}

@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 only 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 onAdFetchCompleted 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

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

start

Swift

func start(_ baseView: UIView)

Objective-C

- (void)start:(UIView *)baseView;

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 adds its view to baseView and calls onAdStarted.

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

• baseView: the view the renderer adds its view to. 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 onAdFetchCompleted 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 when your app moves to the background, and when your app shows a web page for onPopupWebsite.

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. Set it to YES for both TrueX and IDVx ads.
appId	nil	Used for internal tracking. If not set, the renderer uses the app's bundle identifier.
enableWebViewDebugging	NO	If YES, the ad's web view can be inspected with Safari Web Inspector. Enable it in debug builds only.

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. The Swift app in the examples uses the same helper:

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;
#if DEBUG
    options.enableWebViewDebugging = YES;
#endif
    return [[TruexAdRenderer alloc] initWithAdParameters:adParameters
                                                 options:options
                                                delegate:delegate];
}

@end

Bridging header

#import "TruexRendererFactory.h"

Swift

truexAdRenderer = TruexRendererFactory.renderer(withAdParameters: adParameters, delegate: self)
truexAdRenderer?.start(view)

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