Skip to main content

Ad options

Ad insertionAd trackingBkYouAdvanced features

All methods are defined in the StreamingSession class.

Requirements

Activate advertising​

Activate the advertising workflow (ad session creation, ad tracking and ad analytics). The method setAdParameter automatically calls this method.

/**
 * Activate advertising workflow (including analytics and tracking)
 * The method setAdParameter automatically calls this method
 */
session.activateAdvertising();
note

The method has to be called before starting the session (i.e calling getURL).

Set ad parameter​

Set a parameter used for the ad insertion. They are sent to the BkYou and the ad provider to generate a more personalized ad insertion.

/**
 * This method set a parameter used for the ad insertion
 * @param name  Parameter name
 * @param value Parameter value
 */
session.setAdParameter("name", "value");
note

The method has to be called before starting the session (i.e calling getURL).

Ad user interaction​

Trigger an ad user interaction to report the ad click tracker. It is mandatory for a Google integration through the PAL SDK or for a OM SDK integration.

The method can be called anytime during a running session.

/**
 * Trigger an ad user interaction (OMSDK, PAL SDK)
 * @param interactionType see AdInteractionType class to get types
 */
session.adUserInteraction(AdInteractionType.CLICK);
public class AdInteractionType {
    /**
     * Ad user click interaction type
     */
    public static final String CLICK = "click";

    /**
     * Ad user invitation accept interaction type
     */
    public static final String INVITATION_ACCEPTED = "invitationAccept";
}

Ad data​

The ad data model can be retrieved through listeners (ad events listener or ad data listener) or methods (get ad list, get current ad break or get current ad).

AdBreakData​

This object contains all info about an ad break, including the ad list.

note

In case of live content:

  • The duration is set to -1
  • The ad count is set to -1
/**
 * Ad break data
 * Returned by session.getAdList()
 */
class AdBreakData {
    /**
     * Ad break id
     */
    String getId();

    /**
     * Start position in millis
     */
    long getStartPosition();

    /**
     * Duration in millis
     * Includes all ads
     */
    long getDuration();

    /**
     * Ad list
     */
    ArrayList<AdData> getAds();

    /**
     * Total ad count
     * If live content, adCount will be -1
     */
    int getAdCount();
}

AdData​

This object contains all info about an ad.


class AdData {
    /**
     * Ad index in the ad break
     */
    public int getIndex();

    /**
     * Ad creative id
     */
    String getCreativeId();

    /**
     * Ad id
     * If the same ad is played in the content, the id will be the same
     */
    String getAdId();

    /**
     * Start position in millis
     */
    long getStartPosition();

    /**
     * Skip position in millis
     * 0 if not defined
     */
    long getSkipPosition();

    /**
     * Duration in millis
     */
    long getDuration();

    /**
     * Click URL
     * Empty string if not defined
     */
    String getClickURL();
}

Listen to ad events​

This method allows the app to listen to ad events:

  • when an ad break begins, onAdBreakBegin is triggered
  • when an ad break ends, onAdBreakEnd is triggered
  • when an ad begins, onAdBegin is triggered
  • when an ad ends, onAdEnd is triggered
  • if an ad is skippable, onAdSkippable is triggered after onAdBegin with skip begin position, current ad end position and ad break end position. This allows to skip either the current ad or all ads in ad break.

It can be used to interact with the UI, for instance to lock player controls during an ad or show a skip button.

The placement of the ad break can be computed:

  • pre-roll: the ad break position is equal to 0
  • post-roll: the ad break end position (ad break position + ad break duration) is greater than the content duration - 1 second
  • mid-roll: all other cases

Find more details about AdData and AdBreakData in Ad options.

caution

Since the version 04.06.02, modifications have been made to the arguments of the ad events listener. Please update your code if needed.

Here are the modifications that have been implemented:

  • position ➡ adBreakData.startPosition or adData.startPosition
  • duration ➡ adBreakData.duration or adData.duration
  • clickURL ➡ adData.clickURL
  • sequenceNumber ➡ adData.index
  • totalNumber ➡ adBreakData.adCount
session.setAdEventsListener(new AdManager.AdEventsListener() {
    /**
     * Triggered when ad breaks begin
     * @param adBreak Ad break data
     */
    void onAdBreakBegin(AdBreakData adBreak) {
        // Lock player controls
    }

    /**
     * Triggered when an ad begin
     * @param adData Ad data
     * @param adBreakData Ad break data
     */
    void onAdBegin(AdData adData, AdBreakData adBreakData) {
        // Show ad link button if needed
    }

    /**
     * Triggered when an ad is skippable
     * @param adData Ad data
     * @param adBreakData Ad break data
     * @param adSkippablePosition position in millis where skip becomes allowed
     * @param adEndPosition position in millis of ad end
     * @param adBreakEndPosition position in millis of ad break end
     */
    void onAdSkippable(AdData adData, AdBreakData adBreakData, long adSkippablePosition, long adEndPosition, long adBreakEndPosition) {
        // Show the skip message/button "skip ad in x seconds"
    }

    /**
     * Triggered when the ad is ended, not called if skipped
     * @param adData Ad data
     * @param adBreakData Ad break data
     */
    void onAdEnd(AdData adData, AdBreakData adBreakData) {
        // Hide ad link, hide ad skip button
    }

    /**
     * Triggered when ad breaks ended, even in case of skipping
     * @param adBreakData Ad break data
     */
    void onAdBreakEnd(AdBreakData adBreakData) {
        // Unlock player controls, hide ad link, hide ad skip button
    }
});
note

The method has to be called before starting the session (i.e calling getURL).

Listen to ad data​

This method allows the app to listen to ad data. It returns the ad list and allow the app to perform specifics ad behavior (Restore a bookmark position).

The event is triggered:

  • during getURL with the ad list
  • during the playback everytime the ad list is updated
session.setAdDataListener(new AdManager.AdDataListener() {
    /**
     * Triggered when ad data have been received during getURL
     * @param adList list of ad breaks
     */
    @Override
    public void onAdData(ArrayList<AdBreakData> adList) {
        
    }
});
note

The method has to be called before starting the session (i.e calling getURL).

When registering to this listener, the BkYou will request the ad provider during the getURL processing instead of during the manifest retrieving by the player. It will slightly increase the redirection time (time between the start of getURL and the end). However, the startup time (time between the start of getURL and the first image displayed) will not change.

Get ad list​

This method returns the ad break list. Each ad breaks contain a list of ads.

If the ad break list has not already been received, the method returns an empty array. To ensure that the function will return the correct result, call it once onAdData has been triggered (see Listen to ad data).

After the data has been removed from the BkYou tracking file, it remains in memory until the end of the ad break playback.

/**
 * Return the current ad list
 * It can be called after or inside onAdData event
 * @return list of ad breaks
 */
ArrayList<AdBreakData> list = session.getAdList();

Get current ad break​

This method returns the current ad break. Each ad breaks contain a list of ads.

If the player is not playing an ad break, the method returns null.

/**
 * Return the current ad break
 * @return current ad break or null
 */
AdBreakData adBreakData = session.getCurrentAdBreak();

Get current ad​

This method returns the current ad.

If the player is not playing an ad, the method returns null.

/**
 * Return the current ad
 * @return current ad or null
 */
AdData adData = session.getCurrentAd();

Create a bookmark position​

This method returns a bookmark position to store in the application. It takes into account the current position and ads in the content. It will avoid restoring the position on the same content later at an incorrect position (ads can move into the content or can be deleted).

Check the sample code to see a bookmarking implementation.

/**
 * Return the current position within the content without ads
 * This position can be saved to be restored later through getPositionForPlayback(positionInBookmark, beforeAdBreak)
 * For VOD contents only
 *
 * @return Position in milliseconds in the content without ads
 */
long position = session.getPositionForBookmark();

Restore a bookmark position​

This method returns a playback position based on a bookmarked position. It takes into account current ads in the content.

To ensure that the function will return the correct result, call it once onAdData has been triggered (see Listen to ad data).

Check the sample code to see a bookmarking implementation.

/**
 * Return the position including current ads with the position in the content without ads
 * Can be called after or inside onAdData
 * For VOD contents only
 *
 * @param positionInBookmark position in milliseconds in the content without ad (with the stored value got from the method getPositionForBookmark())
 * @param beforeAdBreak if set to true, return position before ad break (false by default) 
 * @return Position including current ads in milliseconds
 */
long position = session.getPositionForPlayback(positionInBookmark, beforeAdBreak);

Set a user agent for ad tracking events​

This method allows to the app to set the user agent used by the SmartLib during ad tracking event HTTP requests. It overrides the custom user agent if it has been set.

// Per session setting
session.setOption(StreamingSessionOptions.USERAGENT_AD_EVENT, "useragent");
note

The method has to be called before starting the session (i.e calling getURL).
This option has no effect on Web (the browser User-Agent is always used).