support Contact Support | system status System Status
Page Contents

    Android Ad UI Customization with Server-Side Ad Insertion (SSAI)

    In this topic, you will learn how to manage and customize the UI elements displayed during server-side ad playback, using the SSAI plugin for the Brightcove Native SDK for Android.

    Overview

    When working with server-side ad insertion (SSAI), the Brightcove Native SDK for Android allows you to customize the ad UI elements. For more details about SSAI, see the following:

    The advertisement UI is composed of two main components:

    • Ad overlay (A)
    • Ad media controller (B)
    Ad UI components
    Ad UI components

    Ad overlay

    The Ad Overlay is composed of these components:

    • Ad Pod total duration countdown (A)
    • Learn More view (B)
    • Skip Ad view (C)
    Ad overlay
    Ad overlay

    Ad media controller

    The Ad media controller is composed of these components, from left to right:

    • Play button (A)
    • Ad number countdown (B)
    • Single Ad duration countdown (C)
    • Full screen button (D)
    Ad media controller
    Ad media controller

    Managing ad UI components

    To enable or disable ad UI components from the view, see the following:

    Modifying the VAST document

    The Learn More and Skip Ad views can be displayed or hidden based on the ad definition in the VAST document.

    The Learn More view will appear only when the Linear Creative contains a ClickThrough URL, as shown here:

     <VAST xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <Ad id="blue-01-5s">
        <InLine>
          ...
          <Creatives>
            <Creative id="creative-01-5s">
              <Linear>
                ...
                <VideoClicks>
                  <ClickThrough id="clickthrough">https://www.brightcove.com/en/</ClickThrough>
                  <ClickTracking id="...”>...</ClickTracking>
                </VideoClicks>
              </Linear>
            </Creative>
          </Creatives>
        </InLine>
      </Ad>
    </VAST>
    

    The Skip Ad view will appear only when there is a valid skipoffset value in the Linear Creative:

     <VAST xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <Ad id="blue-01-5s">
        <InLine>
          ...
          <Creatives>
            <Creative id="creative-01-5s">
              <Linear skipoffset="00:00:03">
                ...
              </Linear>
            </Creative>
          </Creatives>
        </InLine>
      </Ad>
    </VAST>
    

    Specifying the ad configuration

    When using Player Enhancements for Live SSAI, you can enable or disable components within the application_ad_configuration of your ad configuration. The client_options object allows you to turn ad UI components on or off.

    {
      "application_ad_configuration": {
    	"ad_configuration_description": "$YOUR_DESCRIPTION",
    	"ad_configuration_expected_response_type": "Vast",
    	"ad_configuration_headers_for_impressions": false,
    	"ad_configuration_strategy": "SingleAdResponse",
    	"ad_configuration_transforms": [],
    	"ad_configuration_url_format": "$YOUR_AD_SERVER",
         "ad_configuration_client_sdk_enabled": true,
         "client_options": {
            "show_ad_break_remaining_time": true / false,
            "show_ad_remaining_time": true / false,
            "show_number_of_remaining_ads": true / false,
            "client_only_tracking": true / false
         }
      },
      "application_description": "$YOUR_DESCRIPTION"
    }
    

    Use the client_options object to enable/disable the following components:

    • Show_ad_break_remaining_time: The Ad Pod total duration countdown
      • Example: Your video will resume in 15 seconds
    • Show_ad_remaining_time: The single Ad duration countdown
      • Example: (0:15)
    • Show_number_of_remaining_ads: The Ad number countdown
      • Example: Ad 1 of 3, Ad 2 of 3, etc.

    Customizing the Ad Overlay

    You can customize the views and the default text associated with the Ad Overlay.

    Modifying the View

    To customize the Ad Overlay, you can replace your version of the ssai_ad_overlay.xml layout file in your app’s res folder. This file contains several different independent layouts, as shown here:

    Ad Overlay layouts
    Ad Overlay layouts

    For example, you could override the Ad Pod duration view by updating the ssai_ad_pod_duration_countdown_view.xml file. You could also override the entire Ad Overlay View by replacing the ssai_ad_overlay.xml file.

    This layout structure allows you to override particular components while maintaining backward compatibility with older SSAI plugin versions.

    Explore the Ad Overlay files using Android Studio. As of version 6.9.0 of the Native SDK for Android, the SSAI plugin's ssai_ad_overlay.xml looks like this:

    <?xml version="1.0" encoding="utf-8"?>
    <FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
        xmlns:tools="http://schemas.android.com/tools"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:background="@color/white">
    
       <include layout="@layout/ssai_ad_countdown_and_learn_more_overlay"/>
       <include layout="@layout/ssai_ad_skip_overlay"/>
    </FrameLayout>
    

    When replacing a component xml file, you must use a TextView with the original view Id specified to avoid unintended results. For details, see the following table

    Component Name Component Id Component View
    Ad Pod duration view text_ad_countdown TextView
    Learn More view text_ad_learn_more TextView
    Skip Ad view text_ad_skip TextView

    Modifying the default text

    All of the Ad Overlay components are TextViewss defined in your app's string.xml file. To change the display text, override it by creating a string or plurals item using the same string id used by the Native SDK for Android.

    The Ad Pod duration view uses the following strings:

    <plurals name="ssai_message_ad_break_duration_countdown">
       <item quantity="one">Your video will resume in\n%1$d second</item>
       <item quantity="other">Your video will resume in\n%1$d seconds</item>
    </plurals>
    <string name="ad_info_now_text">Your video will resume now</string>
    <string name="ad_buffering_text">Your ad is buffering …</string>
    

    The Learn More view uses the following string:

    <string name="ssai_message_learn_more">Learn More >> </string>
    

    The Skip Ad view uses the following strings:

    <plurals name="you_can_skip_text">
       <item quantity="one">You can skip this ad in\n%d second</item>
       <item quantity="other">You can skip this ad in\n%d seconds</item>
    </plurals>
    <string name="skip_text">Skip Ad</string>
    

    Customizing the Ad Media Controller

    You can customize the views and the default text associated with the Ad Media Controller.

    Modifying the View

    To customize the Ad Media Controller, you can replace your version of the default_ssai_ad_media_controller.xml layout file in your app’s res folder.

    This overrides the default layout used in the SSAI plugin. Every time an Ad is detected, the SSAI plugin will switch to this layout and then return to the default controller when the Ad is finished.

    When working with your own layout, use the same view type and view ids as originally specified to avoid unintended results. Explore the Ad Media Controller layout using Android Studio. For the SSAI plugin version 6.9.0, the default_ssai_ad_media_controller.xml looks like this:

    <com.brightcove.player.mediacontroller.BrightcoveControlBar
       xmlns:android="http://schemas.android.com/apk/res/android"
       xmlns:tools="http://schemas.android.com/tools"
       android:id="@+id/brightcove_control_bar"
       style="@style/SSAIAdControlBar"
       android:layout_width="match_parent"
       android:layout_height="wrap_content"
       android:layout_gravity="bottom"
       android:background="@color/bmc_background"
       android:orientation="vertical"
       android:padding="8dp">
    
       <LinearLayout
           android:layout_width="match_parent"
           android:layout_height="wrap_content"
           android:gravity="bottom"
           android:orientation="horizontal">
    
           <Button style="@style/BorderlessButton"
               android:id="@id/play"
               android:layout_width="wrap_content"
               android:layout_height="wrap_content"
               android:text="@string/brightcove_controls_play"
               android:visibility="gone"
               tools:visibility="visible"/>
    
           <include layout="@layout/ssai_ad_number_countdown_view"/>
    
           <include layout="@layout/ssai_single_ad_duration_countdown_view"/>
    
           <View
               android:id="@id/two_line_spacer"
               android:layout_width="0dp"
               android:layout_height="0dp"
               android:layout_weight="1"
               android:visibility="gone"
               tools:visibility="visible"/>
    
           <Button style="@style/BorderlessButton"
               android:id="@id/full_screen"
               android:layout_width="wrap_content"
               android:layout_height="wrap_content"
               android:padding="4dp"
               android:text="@string/brightcove_controls_enter_full_screen"
               android:visibility="gone"
               tools:visibility="visible"/>
       </LinearLayout>
    
    </com.brightcove.player.mediacontroller.BrightcoveControlBar>
    

    The SSAI Ad Media Controller component view types and view ids are described here:

    Component Name Component Id Component View
    Play button play Button
    Full Screen button full_screen Button
    Ad number countdown text_ad_number_countdown TextView
    Single Ad duration countdown text_single_ad_duration_countdown TextView

    Check out the Customized Controls Sample App, where the default media controller is customized to add new buttons. You can apply the same approach to customize your SSAI Ad Media Controller.

    Modifying the default text

    All of the Ad Media Controller components are TextViewss defined in your app's string.xml file. To change the display text, override it by creating a string or plurals item using the same string id used by the Native SDK for Android.

    The Ad number countdown view uses the following string:

    <string name="ssai_message_ad_number_countdown">Ad %1$d of %2$d</string>
    

    The Single Ad duration countdown view uses the following string:

    <string name="ssai_message_ad_duration_countdown">(%1$s)</string>
    

    Summary

    You have a few options to customize the SSAI UI elements. The level of complexity will depend on what you want to achieve. From low to high level of complexity, you can:

    • Configure/hide certain components through your VAST configuration
    • Show/hide components using the client_options object in your ad configuration (currently Live SSAI only)
    • Change the string value displayed
    • Override the UI layout

    Please share any ideas or feedback you have in the Brightcove Native Player SDKs forum.


    Page last updated on 12 Jun 2020