Out-of-band ads

AdvertisingOut-of-bandBroadpeak.ioAd gateway

This guide explains how to work with out-of-band ads, which are ads that are not signalled in the stream as opposed to in-band ads.

Out-of-band ads are retrieved by Broadpeak.io, which must be configured to support this feature.

SmartLib lets you request Broadpeak.io to get these ads anytime after playback started, and lets you automatically or manually control their playback using specific APIs.

note

Out-of-band ads can be combined with in-band ads.
Starting an out-of-band ad is known as a cue-out, and returning to the main content is known as a cue-in.

At this point, you should have activated advertising on the session.

In order to be notified of ads returned, add the onOutOfBandAdData listener before calling getURL. This is required if you want to manually control ads playback.

Then, after getURL, use requestOutOfBandAds to get ads from Broadpeak.io.

From here on, according to the use case, you can

Begin ad playback manually with beginOutOfBandAdBreak
End ad playback manually with endOutOfBandAdBreak

Example

Android
iOS & tvOS
Web

// Init SmartLib
SmartLib.getInstance().init(getApplicationContext(), ..., ..., ...);

// Create a new session
StreamingSession session = SmartLib.getInstance().createStreamingSession();

// Attach the player
session.attachPlayer(player);

// Activate advertising
session.activateAdvertising();

// Set listener to be notified when out-of-band ads are requested
session.setAdDataListener(new AdManager.AdDataListener() {
    /**
     * Triggered when requestOutOfBandAds completes
     *
     * @param outOfBandAdList The list of current out-of-band ad breaks
     *                        The list contains all non-finished ad breaks kept in memory
     *                        An ad break is removed from the list when it ends
     *                        The list is empty if a request error occurs (e.g. 404, 503)
     */
    @Override
    public void onOutOfBandAdData(ArrayList<AdBreakData> outOfBandAdList) {
        // Keep a list of current out-of-band ads ids
        this@MyActivity.outOfBandAdList = new ArrayList<>();
        for (AdBreakData adBreak : outOfBandAdList) {
            this@MyActivity.outOfBandAdList.add(adBreak.getId());
        }
    }
});
...

// Get URL (not in the main thread)
StreamingSessionResult result = session.getURL(CONTENT_URL);

// Give redirected to the player and start playback (depends on your player)
...

// Anytime after playback started, call requestOutOfBandAds()
HashMap<String, String> additionalQueryParams = new HashMap<>();
additionalQueryParams.put("scene", "jewels");
session.requestOutOfBandAds("pause", null, false, additionalQueryParams);

...
// Anytime after onOutOfBandAdData() responded, begin an out-of-band ad
session.beginOutOfBandAdBreak(this.outOfBandAdList[0]); // Begin first ad for example

// Anytime after the ad was started, end it
session.endOutOfBandAdBreak(this.outOfBandAdList[0]); // End first ad for example

...

// Init SmartLib
[SmartLib initSmartLib:... nanoCDNHost:... broadpeakDomainNames:...];

// Create a session
StreamingSession *session = [SmartLib createStreamingSession];

// Attach the player
[session attachPlayer:player];

// Activate advertising
[session activateAdvertising];

// Set listener to be notified when out-of-band ads are requested
[session setAdDataListener:self];
/**
 * Triggered when requestOutOfBandAds completes
 *
 * @param outOfBandAdList The list of current out-of-band ad breaks
 *                        The list contains all non-finished ad breaks kept in memory
 *                        An ad break is removed from the list when it ends
 *                        The list is empty if a request error occurs (e.g. 404, 503)
 */
- (void)onOutOfBandAdData:(nonnull NSArray<AdBreakData *> *)outOfBandAdList {
    // Keep a list of current out-of-band ads ids
    self.outOfBandAdList = [NSMutableArray new];
    for (AdBreakData *adBreak in outOfBandAdList) {
        [self.outOfBandAdList addObject:adBreak.adBreakId];
    }
}
...

// Get URL (not on the main thread)
StreamingSessionResult *result = [session getURL:CONTENT_URL];

// Give redirected to the player and start playback (depends on your player)
...

// Anytime after playback started, call requestOutOfBandAds()
NSDictionary<NSString *, NSString *> *additionalQueryParams = @{@"scene": @"jewels"};
[session requestOutOfBandAds:@"pause" duration:nil autoBegin:false additionalQueryParams:additionalQueryParams];

...
// Anytime after onOutOfBandAdData() responded, begin an out-of-band ad
[session beginOutOfBandAdBreak:self.outOfBandAdList[0]]; // Begin first ad for example

// Anytime after the ad was started, end it
[session endOutOfBandAdBreak:self.outOfBandAdList[0]]; // End first ad for example

...

// Init SmartLib
SmartLib.getInstance().init(...);

// Create a session
const session = SmartLib.getInstance().createStreamingSession();

// Attach the player
session.attachPlayer(player);

// Activate advertising
session.activateAdvertising();

// Set listener to be notified when out-of-band ads are requested
session.setAdDataListener({
    /**
     * Triggered when requestOutOfBandAds completes
     *
     * @param outOfBandAdList The list of current out-of-band ad breaks
     *                        The list contains all non-finished ad breaks kept in memory
     *                        An ad break is removed from the list when it ends
     *                        The list is empty if a request error occurs (e.g. 404, 503)
     */
    onOutOfBandAdData(outOfBandAdList) {
        this.outOfBandAdList = outOfBandAdList.map(item => item.adId);
    }
});
...

// Start the session
session.getURL(CONTENT_URL)
    .then(result => {
        ...
    });

// Give redirected to the player and start playback (depends on your player)
...

// Anytime after playback started, call requestOutOfBandAds()
session.requestOutOfBandAds('pause', null, false, {'scene':'jewels'});

...
// Anytime after onOutOfBandAdData() responded, begin an out-of-band ad
session.beginOutOfBandAdBreak(this.outOfBandAdList[0]); // Begin first ad for example

// Anytime after the ad was started, end it
session.endOutOfBandAdBreak(this.outOfBandAdList[0]); // End first ad for example
...

Example​

Example