support Contact Support | system status System Status
Page Contents

    Client-Side Pre-roll Ads with Live SSAI and the Native SDKs

    In this topic, you will learn how to use the Brightcove Native SDKs to play client-side pre-roll ads with live streams enabled for server-side ad insertion (SSAI).

    Overview

    When delivering live streams with server-side ad insertion (SSAI), you can request mid-roll ad breaks using the Live module. For details, see the Using Live SSAI with the Native SDKs document.

    You may also want to include a pre-roll ad before the live stream begins. This is when viewers are engaged and willing to sit through a short ad. With this feature, you can insert client-side, IMA pre-roll ads.

    Requirements

    The following requirements are needed for this feature:

    Brightcove Native SDK version

    • Native SDK for Android 6.10.0 or higher
    • Native SDK for iOS/tvOS 6.7.7 or higher

    Platform

    • Account enabled for Dynamic Delivery

    Implementing IMA pre-roll ads with Live SSAI

    To play an IMA pre-roll ad with a live SSAI stream, follow these steps:

    1. Create a live event enabled for server-side ad insertion (SSAI). For details, see the following:

    2. Use the IMA plugin to enable client-side pre-roll ads. For details, see the Implementing Client-Side Ads with the Native SDKs document.

    3. Begin streaming.

    Android implementation

    For this feature, you will use both the IMA and SSAI plugins:

    Code samples

    To implement this feature, review the following examples:

    Example

    Here is a code example that combines Live, SSAI and IMA preroll ads:

    /**
     * We start by adding some variables that are focused on the CSAI integration:
     * Also make the EventEmitter a global variable, it will be needed in the setupGoogleIMA method below
     */
    private EventEmitter eventEmitter;
    private GoogleIMAComponent googleIMAComponent;
    private String adRulesURL = "YOUR_AD_RULES_URL";
    
    private final String AD_CONFIG_ID_QUERY_PARAM_KEY = "ad_config_id";
    
    // Note that for live SSAI streams, the adConfigId will start with the string "live."
    // Ads will be injected into a live SSAI stream using the cue point API
    private final String AD_CONFIG_ID_QUERY_PARAM_VALUE = "YOUR_AD_CONFIG_ID";
    
    private SSAIComponent plugin;
    
    /**
     * The BasicSSAISampleApp's onCreateMethod, with the setupGoogleIMA method from the AdRulesImaSampleApp added
     */
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        setContentView(R.layout.ssai_activity_main);
        brightcoveVideoView = (BrightcoveExoPlayerVideoView) findViewById(R.id.brightcove_video_view);
        super.onCreate(savedInstanceState);
    
        eventEmitter = brightcoveVideoView.getEventEmitter();
    
        // Here we use the same setupGoogleIMA method as found in the AdRulesImaSampleApp:
        setupGoogleIMA();
    
        final EventEmitter eventEmitter = brightcoveVideoView.getEventEmitter();
        Catalog catalog = new Catalog(eventEmitter, YOUR_ACCOUNT_ID, YOUR_POLICY_KEY);
    
        // Setup the error event handler for the SSAI plugin.
        registerErrorEventHandler();
        plugin = new SSAIComponent(this, brightcoveVideoView);
    
        View view = findViewById(R.id.ad_frame);
        if (view instanceof ViewGroup) {
            // Set the companion ad container,
            plugin.addCompanionContainer((ViewGroup) view);
        }
    
        // Set the HttpRequestConfig with the Ad Config Id configured in
        // your https://studio.brightcove.com account.
        HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
                .addQueryParameter(AD_CONFIG_ID_QUERY_PARAM_KEY, AD_CONFIG_ID_QUERY_PARAM_VALUE)
                .build();
    
        catalog.findVideoByID("YOUR_VIDEO_ID", httpRequestConfig, new VideoListener() {
            @Override
            public void onVideo(Video video) {
                // The Video Sources will have a VMAP url which will be processed by the SSAI plugin,
                // If there is not a VMAP url, or if there are any requesting or parsing error,
                // an EventType.ERROR event will be emitted.
                plugin.processVideo(video);
            }
        });
    }
    
    // The setupGoogleIMA method, for reference:
    
    /**
     * Setup the Brightcove IMA Plugin.
     */
    private void setupGoogleIMA() {
        // Establish the Google IMA SDK factory instance.
        final ImaSdkFactory sdkFactory = ImaSdkFactory.getInstance();
    
        // Enable logging up ad start.
        eventEmitter.on(EventType.AD_STARTED, new EventListener() {
            @Override
            public void processEvent(Event event) {
                Log.v(TAG, event.getType());
            }
        });
    
        // Enable logging any failed attempts to play an ad.
        eventEmitter.on(GoogleIMAEventType.DID_FAIL_TO_PLAY_AD, new EventListener() {
            @Override
            public void processEvent(Event event) {
                Log.v(TAG, event.getType());
            }
        });
    
        // Enable Logging upon ad completion.
        eventEmitter.on(EventType.AD_COMPLETED, new EventListener() {
            @Override
            public void processEvent(Event event) {
                Log.v(TAG, event.getType());
            }
        });
    
        // Set up a listener for initializing AdsRequests. The Google
        // IMA plugin emits an ad request event as a result of
        // initializeAdsRequests() being called.
        eventEmitter.on(GoogleIMAEventType.ADS_REQUEST_FOR_VIDEO, new EventListener() {
            @Override
            public void processEvent(Event event) {
                // Create a container object for the ads to be presented.
                AdDisplayContainer container = sdkFactory.createAdDisplayContainer();
                container.setPlayer(googleIMAComponent.getVideoAdPlayer());
                container.setAdContainer(brightcoveVideoView);
    
                // Build an ads request object and point it to the ad
                // display container created above.
                AdsRequest adsRequest = sdkFactory.createAdsRequest();
                adsRequest.setAdTagUrl(adRulesURL);
                adsRequest.setAdDisplayContainer(container);
    
                ArrayList<AdsRequest> adsRequests = new ArrayList<AdsRequest>(1);
                adsRequests.add(adsRequest);
    
                // Respond to the event with the new ad requests.
                event.properties.put(GoogleIMAComponent.ADS_REQUESTS, adsRequests);
                eventEmitter.respond(event);
            }
        });
    
        // Create the Brightcove IMA Plugin and pass in the event
        // emitter so that the plugin can integrate with the SDK.
        googleIMAComponent = new GoogleIMAComponent(brightcoveVideoView, eventEmitter, true);
    }
    

    iOS implementation

    For this feature, you will use both the IMA and SSAI plugins:

    Code samples

    To implement this feature, review the following examples:


    Page last updated on 28 Sep 2020