In-band ads

AdvertisingIn-bandManifest Manipulation Engine

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

In-band ads insertion and signalling is done by Broadpeak Manifest Manipulation Engine (aka MME).

SmartLib lets you request MME to get a stream with ads, which in return sends ad signals back to SmartLib, enabling tracking and exposing callback events you can subscribe to.

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

From here on, the following APIs are optional but can be used to enhance the user experience:

Personalize ad insertion with setAdParameter
Listen to ad events such as onAdBegin or onAdEnd with setAdEventsListener
Listen to ad data before playback starts and update UX/UI with setAdDataListener
Track user interaction such as click or invitationAccept with adUserInteraction

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);

// Listen to ad events
session.setAdEventsListener(new AdManager.AdEventsListener() {
    @Override
    public void onAdBreakBegin(AdBreakData adBreak) {
        // Lock player controls
        mControlsLayout.setClickable(false);
    }

    @Override
    public void onAdBegin(AdData adData, AdBreakData adBreakData) {
        // Show ad link button if needed
        mAdLink.setVisible(View.VISIBLE);

        mAdLink.setClickURL(adData.clickURL); // on click, it will call session.adUserInteraction(AdInteractionType.CLICK);
    }

    @Override
    public void onAdSkippable(AdData adData, AdBreakData adBreakData, long adSkippablePosition, long adEndPosition, long adBreakEndPosition) {
        // Show the skip message/button "skip ad in x seconds"
        mAdSkipMessage.setVisibility(View.VISIBLE);
    }

    @Override
    public void onAdEnd(AdData adData, AdBreakData adBreakData) {
        // Hide ad link and ad skip button
        mAdLink.setVisible(View.GONE);
        mAdSkipMessage.setVisibility(View.GONE);
    }

    @Override
    public void onAdBreakEnd(AdBreakData adBreakData) {
        // Hide ad link and ad skip button
        mAdLink.setVisible(View.GONE);
        mAdSkipMessage.setVisibility(View.GONE);

        // Unlock player controls
        mControlsLayout.setClickable(true);
    }
});

...

// Start the session with/without ads
if (contentContainsAds) { // To be adapted
    session.activateAdvertising();

    // Set ad parameters
    session.setAdParameter("name1", "value1");
    session.setAdParameter("name2", "value2");
}

// You must not call getURL on the main thread !
// Because of generation duration of the nonce and technical requirements, it has to be done on another thread
StreamingSessionResult result = session.getURL(CONTENT_URL);

...

// Notify that the user opened the ad link
session.adUserInteraction(AdInteractionType.CLICK);

// Stop the session
session.stopStreamingSession();

...

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

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

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

// Listen to ad events
[session setAdEventsListener:self];

...

// Start the session with/without ads
if (contentContainsAds) { // To be adapted
   [session activateAdvertising];
   [session setAdView:player.view]

   // Set ad parameters
   [session setAdParameter:@"name1" value:@"value1"];
   [session setAdParameter:@"name2" value:@"value2"];
}

// Start the session
StreamingSessionResult *result = [session getURL:CONTENT_URL];

...

// Notify that the user opened the ad link
[session adUserInteraction:BPAdInteractionTypeClick];

// Stop the session
[session stopStreamingSession];

...

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

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

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

// Listen to ad events
session.setAdEventsListener({
    onAdBreakBegin: (adBreakData) => {
        // Lock player controls
    },

    onAdBegin: (adData, adBreakData) => {
        // Show ad link button if needed
    },

    onAdSkippable: (adData, adBreakData, adSkippablePosition, adEndPosition, adBreakEndPosition) => {
        // Show the skip message/button "skip ad in x seconds"
    },

    onAdEnd: (adData, adBreakData) => {
        // Hide ad link, hide ad skip button
    },

    onAdBreakEnd: (adBreakData) => {
        // Unlock player controls, hide ad link, hide ad skip button
    }
});

...

// Start the session with/without ads
if (contentContainsAds) { // To be adapted
    session.activateAdvertising();

    // Set ad parameters
    session.setAdParameter('name1', 'value1');
    session.setAdParameter('name2', 'value2');
}

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

...

// Notify that the user opened the ad link
session.adUserInteraction('click');

...

// Stop the session
session.stopStreamingSession();

...

Example​

Example