SpringServe Ad Macros with the Native SDKs

In this topic, you will learn how to take advantage of ad monetization when using client-side ad insertion (CSAI) with the Brightcove Native SDKs.

Introduction

Brightcove Ad Monetization is an end-to-end monetization service that supports live and VOD content with cutting-edge yield optimization tools. If you are new to this feature, review the Brightcove Ad Monetization document.

Ad monetization supports client-side ad insertion (CSAI) when using the Brightcove IMA plugins with the Brightcove Native SDKs. This feature uses the SpringServe ad serving platform. To learn more, see the following:

The Brightcove IMA plugin detects SpringServe URLs and attempts to replace/populate supported macros.

Requirements

SpringServe ad macro support requires the following:

  • Brightcove Native SDK for Android v8.1.0 or newer
  • Brightcove Native SDK for iOS v6.12.1 or newer
  • Setting up your account for Brightcove Ad Monetization

Android implementation

The Brightcove Native SDK for Android's IMA plugin supports SpringServe macro replacement.

The GoogleIMAComponent class has a new method to set up replaceable macros.

setSpringServeMacrosMap(HashMap<String, Object> springServeMacros)

Supported automatic replacement macro list

The following ad macros will be automatically replaced with values as specified.

Supported ad macros
SpringServe macro URL parameter Description
{{WIDTH}} w= Player width
{{HEIGHT}} h= Player height
{{APP_BUNDLE}} app_bundle= App package name
{{APP_NAME}} app_name= App name
{{CACHEBUSTER}} cb= Random value
{{DESCRIPTION}} Video Description
{{DURATION}} dur= Video duration
{{AUTOPLAY}} ap= Values:
  • 0 - If player is NOT set to autoplay
  • 1 - If player is set to autoplay

Since this is managed at the app level, if this value isn't provided then it will be automatically set to 0
{{MUTE}} mute= Values:
  • 0 - If player is NOT muted
  • 1 - If player is muted
{{KEYWORDS}} kwds= If the video is obtained from videoCloud, it will use the tags as keywords. If not, adding tags to the video object is not currently supported, but they could be added manually by sending them on the map as a string.
{{MEDIA_ID}} mid= Video ID
{{ENCODED_VIDEO_TITLE}} vt= Video title
{{VIDEO_ID}} vid= Video ID
{{CONTENT_ID}} content_id= Video ID
{{CONTENT_TITLE}} content_title= Video title
{{CONTENT_LIVESTREAM}} content_livestream= Values:
  • 0 - If content is NOT a live stream
  • 1 - If content is a live stream
{{LANGUAGE}} language= Language from the locale

iOS implementation

The Brightcove Native SDK for iOS's IMA plugin supports SpringServe macro replacement. The SDK provides a new delegate method to allow you to provide values that are not auto-filled, or to override an auto-filled value.

- (NSDictionary *)valuesForSpringServeMacroReplacement;

The list of auto-filled macros are found in the BCOVSpringServeKeys.h file.

//
// BCOVSpringServeKeys.h
// BrightcoveIMA
//
// Copyright (c) 2023 Brightcove, Inc. All rights reserved.
// License: https://accounts.brightcove.com/en/terms-and-conditions
//

#import <Foundation/Foundation.h>

extern NSString * _Nonnull const kBCOVSpringServeMacroWidth;
extern NSString * _Nonnull const kBCOVSpringServeMacroHeight;
extern NSString * _Nonnull const kBCOVSpringServeMacroAppBundle;
extern NSString * _Nonnull const kBCOVSpringServeMacroAppName;
extern NSString * _Nonnull const kBCOVSpringServeMacroCacheBuster;
extern NSString * _Nonnull const kBCOVSpringServeMacroDescription;
extern NSString * _Nonnull const kBCOVSpringServeMacroDuration;
extern NSString * _Nonnull const kBCOVSpringServeMacroAutoPlay;
extern NSString * _Nonnull const kBCOVSpringServeMacroMute;
extern NSString * _Nonnull const kBCOVSpringServeMacroKeywords;
extern NSString * _Nonnull const kBCOVSpringServeMacroMediaID;
extern NSString * _Nonnull const kBCOVSpringServeMacroEncodedVideoTitle;
extern NSString * _Nonnull const kBCOVSpringServeMacroVideoID;
extern NSString * _Nonnull const kBCOVSpringServeMacroContentID;
extern NSString * _Nonnull const kBCOVSpringServeMacroContentTitle;
extern NSString * _Nonnull const kBCOVSpringServeMacroContentLivestream;
extern NSString * _Nonnull const kBCOVSpringServeMacroLanguage;