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.

Use GoogleIMAComponent.setSpringServeMacrosMap to supply or override values. The map keys are URL parameter names, such as ap and w, not macro names such as AUTOPLAY and WIDTH.

setSpringServeMacrosMap(HashMap<String, Object> springServeMacros)

Supported automatic replacement macro list

The IMA plugin replaces the macros below when they appear in the ad tag URL. A value you pass in the map takes precedence; values that the SDK can derive from the video or player are filled automatically.

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= Current Unix time in seconds
{{DESCRIPTION}} desc= Video Description
{{DURATION}} dur= Video duration in milliseconds
{{AUTOPLAY}} ap= Values:
  • 0 - If player is NOT set to autoplay
  • 1 - If player is set to autoplay

The SDK has no autoplay state to read. If you do not supply a value, the macro is left empty rather than reported as 0, so supply it from your own app state.
{{MUTE}} mute= Values:
  • 0 - If player is NOT muted
  • 1 - If player is muted
{{KEYWORDS}} kwds= Uses the tags stored in the Video object. You can override this by supplying a string in the map under kwds.
{{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 BCOVIMAPlaybackSessionDelegate provides a method to allow you to provide values that are not auto-filled, or to override an auto-filled value.

- (NSDictionary *)valuesForSpringServeMacroReplacement;

The supported keys mirror the table above and are also exposed as the kBCOVSpringServeMacro* constants:

//
// 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;