Implementing Server-Side Ads with the Native Player SDKs

Product(s)
Video Cloud
SSAI
Role(s)
Device SDK Developer
Topic(s)
Advertising
SSAI
SDK
Android
iOS
tvOS

In this topic, you will learn how to play Server-Side ads with the Brightcove Native Player SDKs, from videos ingested for Dynamic Delivery.

Overview

Server-Side Ad Insertion (SSAI) allows you to embed ads into your videos so that they can't be blocked by ad blockers in the browser. Dynamic Delivery is the next generation ingest and delivery system which reduces your storage footprint and dynamically packages media. Learn more about using Dynamic Delivery for your videos.

SSAI works with both DRM and non-DRM content.

Server-side ad
Server-side ad

To play server-side ads with your video content stored in Video Cloud, follow these steps:

  1. Create an ad configuration
  2. Build your app:

  3. Play a video with ads

Create an ad configuration

The ad configuration defines various aspects of SSAI playback, including a URL to your Video Multiple Ad Playlist (VMAP) file, beacons, and other configurations. To create an ad configuration, follow these steps:

  1. In Video Cloud Studio, expand the ADMIN menu and select Server-Side Ad Settings.

    Ad configuration admin
    Ad configuration admin
  2. Add information for you ad configuration and select Save.

    Ad settings
    Ad settings

For details, see the Configuring Server-Side Ad Settings document.

To create an ad configuration using the SSAI API, see the Video Cloud SSAI Ad Config API document.

Android implementation

Follow these steps within your app to get your ad configuration and play your video:

  1. In Android Studio, open your MainActivity.java file.
  2. Add the following import statements:
    import com.brightcove.ssai.SSAIComponent;
    import com.brightcove.player.network.HttpRequestConfig;
  3. Define constants for your account id, policy key, video id, and your ad configuration id.
    private String accountId = "your account id";
    private String policyKey = "your policy key";
    private String videoId = "your video id";
    private String adConfigId = "your ad configuration id";
  4. Create an instance of the catalog service, which provides asynchronous methods for retrieving data from the Playback API. Create an instance of the SSAI component.
    Catalog catalog = new Catalog(eventEmitter, myAccountId, myPolicyKey);
    SSAIComponent plugin = new SSAIComponent(appContext, getBrightcoveVideoView());
    
  5. Set the adConfigId as a URL parameter.
    HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
      .addQueryParameter("ad_config_id", myAdConfig)
      .build();
  6. Call the catalog service to retrieve your video along with your ad configuration from the Playback API. Start video playback with your specified ads.
    catalog.findVideoByID(myVideoId, httpRequestConfig, new VideoListener() {
        @Override
        public void onVideo(Video video) {
    
        // Process the Video
        plugin.processVideo(video);
      }
    });

For more details and a complete code sample, see the following:

 

iOS implementation

Follow these steps within your app to get your ad configuration and play your video:

  1. In Xcode, open your ViewController.m file.
  2. Import the SSAI plugin for iOS.
    import BrightcoveSSAI
  3. Define constants for your account id, policy key, video id, and your ad configuration id.
    struct Constants {
      static let AccountID = "your account id"
      static let PlaybackServicePolicyKey = "your policy key"
      static let VideoId = "your video id"
      static let AdConfigId = "your ad configuration id"
    }
  4. Define the BCOVPlaybackService class, which provides asynchronous methods for retrieving data from the Playback API.
    private lazy var playbackService: BCOVPlaybackService = {
      let factory = BCOVPlaybackServiceRequestFactory(accountId: Constants.AccountID, policyKey: Constants.PlaybackServicePolicyKey, baseURLStr: "https://edge.api.brightcove.com/playback/v1")
      return BCOVPlaybackService(requestFactory: factory)
    }()
  5. Set the query parameter value to your ad configuration id.
    let queryParameters = [kBCOVPlaybackServiceParamaterKeyAdConfigId: Constants.AdConfigId]
  6. Call the playbackService to retrieve your video along with your ad configuration from the Playback API. Start video playback with your specified ads.

    playbackService.findVideo(withVideoID: Constants.VideoId, parameters: queryParameters) { [weak self] (video: BCOVVideo?, jsonResponse: [AnyHashable: Any]?, error: Error?) -> Void in
    
      guard let _video = video else {
        print("ViewController Debug - Error retrieving video: \(error?.localizedDescription ?? "unknown error")")
        return
      }
    
      self?.playbackController?.setVideos([_video] as NSFastEnumeration)
    }

For the complete code sample, see the following:

 

tvOS implementation

The code to implement SSAI with the Native SDK for tvOS is similar to the code for iSO above.

For a complete code sample, see the following:

 

Playing a video with ads

Any video that you retrieve from Video Cloud that has been ingested with Dynamic Delivery, will include the ads specified in the VMAP file in your ad configuration.

Additional notes

There are a few technical notes to be aware of when using SSAI with the Native SDKs.

Brightcove Native SDK for iOS/tvOS

  • Post-rolls: The OnceUX plugin translates the timeOffset value of end on the final ad break (post-roll) to a CMTime value of +INFINITY, for speed and efficiency. This translation is done AFTER the VMAP document is received (which occurs after the Playback API response is received) and BEFORE playback begins.