Beacon Apps Ad Targeting

Beacon ad targeting allows your Beacon apps to send important device-level and user-specific information to your ad server or ad provider.

Introduction

The purpose of ad targeting is to increase the value of your ad inventory, therefore increasing ad revenue for your business.

Ad targeting allows you to target ads based on the clients' data. The process of how client-side data is passed from the Beacon apps to SSAI (Server Side Ad Insertion)is implemented as follows:

  • Ad targeting variables are use in a Beacon Classic ad configuration setup. Example: 
    platform={PLATFORM}
  • The Beacon app passes the ad targeting variables to Brightcove playback infrastructure with values gathered from from the particular app platform. The values are substituted for the variables. Example: 
    platform=iOS
  • The playback infrastructure then in turn passes the targeting information to SSAI via {{url.xxx}} ad macros. Example: 
    platform={{url.platform}}
  • SSAI then requests ads from your ad server using a VAST tag using the client side information. Example: 
    platform=iOS

Further details and exact configuration steps follow later in this document.

Benefits

Improved ad targeting

  • User Session ID: Brightcove generates a session ID on each device when a user opens the app. This allows you to frequency-cap ads to that session, exclude competitive ads from being served together, and sequentially rotate ads in that session. These targeting capabilities are both necessary for direct-sold and programmatic ads.
  • More data for programmatic ads: Mobile apps and CTV apps don’t support cookies, which is the dominant method for user/device-based ad targeting on the web. By including parameters like Device ID, you can pass this valuable information to programmatic ad buyers, which then enhances your ad targeting capabilities, leading to greater CPMs.

Support for Ad Inventory split

For apps that run on Amazon, Roku, and Samsung (in the US), you are required to do a 70/30 split of ad inventory/revenue with the platform. This means Brightcove Beacon customers monetize 70% of the ad inventory and the platform gets the remaining 30% of the ad inventory. With this enhanced ad targeting, you can use one ad tag across all of your apps and pass the device parameters to your ad server. Inside your ad server, implement the business logic that splits the ad inventory by device. The platforms also require passing Limited Ad Targeting (LAT) for Ad Inventory Split, which is a parameter Brightcove is now sending to your ad server.

User privacy considerations

  • LAT (Limited Ad Targeting) allows users of Beacon apps to opt out of ad targeting based on user behavior.
  • Users have the ability to reset the unique Device ID that we assign to the device at any time.
  • iOS apps follow Apple's App Tracking Transparency framework.

Overview

Initially setup SSAI (Server Side Ad Insertion) in Video Cloud Studio. This configuration is used by Beacon web apps. Then in Beacon Classic, setup an Advertisement Configuration that links to the Video Cloud SSAI configuration and permits ad targeting. Here are more details:

  • Configure SSAI in Video Cloud Studio
    • The ad tag you provide in this setup will include:
      • The base URL for your ad server.
      • URL parameters needed by your ad server.
      • An example ad tag used in the Video Cloud setup would follow this format: 
        https://ads.brightcove.com/ads?tech=dfpadrules&dur=15
    • If client-side ad macros are used, they are only valid for Beacon web apps. All other app platforms use ad targeting. If ad macros are used, they simply are ignored for all non-web apps.
    • See the Implementing VOD SSAI, Implementing Live SSAI and Implementing Server-Side Ads with Brightcove Player documents for more information on setting up SSAI.
    • When finished with the SSAI configuration, copy the ID for that ad configuration which will be used in the Beacon setup.
  • Create an Advertisement Configuration in Beacon Classic
    • You supply the ID of the SSAI configuration created in Video Cloud Studio when creating the Beacon Ad Configuration. This associates the ad configuration with your ad platform.
    • In the Beacon Ad Configuration you supply only the ad targeting variables query string. This is required here as the particular platform's app must gather the client side data at this point so it can be used later when the playback infrastructure makes a request to SSAI.
    • Ten ad targeting variables are available for use, detailed in the next section of this document.
    • The ad targeting variables are used by all apps, with the exception of web apps do NOT use RDID, IDTYPE, APP_ID and IS_LAT. The ad targeting variables are detailed in the next section of this document.

Ad Targeting information

You can target ads based on the information in the table below:

Targeting Information
Type of Information Variable Name
(See note just above table)		 Value Macro Values
Platform platform {PLATFORM} iOS, Android, Roku, AppleTV, Web, STV
OS version os {OS} Device os version (for example, iOS 14)
Device model model {MODEL} Device model; browser version used for web apps
Manufacturer mfgr {MFGR} Device manufacturer; browser name used for web apps
Language lang {LOCALE} Language code set in the App (that comes from CMS)
User session sid {SID} Every time that app launches we want to have a unique integer created that is stored in memory and not persisted
Unique Device ID rdid {RDID} Resettable device ID (TIFA = Samsung, rida = Roku, adid = Android, etc) - if limited ad targeting is set on the App, then the id should be all zeros (not possible to identify the user/device). This item is not applicable to the web.
Is the user allowing tracking is_lat {IS_LAT} 0 if user has not opted to limit targeting, 1 if limiting ad targeting. This item is not applicable to the web.
device type idtype {IDTYPE}
  • adid: Android
  • afai: Amazon
  • tvOS: AppleTV (tvOS)
  • idfa: Apple phones (iOS)
  • rida: Roku
  • tifa: Samsung
  • vida: Vizio
  • msai: Xbox
This item is not applicable to the web.
App identifier app_id {APP_ID} This should be the App bundle name. This item is not applicable to the web.
GDPR Consent GDPR {GDPR} 1 - do not allow personalized ads
0 - allows personalized ads.

Only supported with a Privacy Consent Management Platform in place.
CCPA Consent CCPA {CCPA} 1 - do not allow personalized ads
0 - allows personalized ads.

Only supported with a Privacy Consent Management Platform in place.
GDPR Consent String GDPR_CONSENT {GDPR_CONSENT} TCF 2.0 Consent string from CMP.

Only supported with a Privacy Consent Management Platform in place.
CCPA Consent String US_PRIVACY {US_PRIVACY} A mandatory string for all publishers in which they must pass the privacy consent for users from California.

Only supported with a Privacy Consent Management Platform in place.
Global Privacy Platform string GPP {GPP}

Using Mobile App Consent, you can enable the IAB Global Privacy Platform (GPP) for enhanced compliance with US data privacy laws.

More info on: IAB Global Privacy Platform.

Only supported with a Privacy Consent Management Platform in place.

Metadata variables

Metadata variables are those that describe the content video, derived from both Beacon and Dynamic Delivery data sources. The values are URL encoded before being inserted into the URL templates.

Metadata variables are identified as: {metadata.*}

Field Description
custom_fields.{field_name} Beacon custom fields
long_description Beacon long description
name Beacon video name
reference_id Beacon reference id
tags Comma separated list of the Beacon tags for the video
title.duration Duration of the content in seconds
title.id Dynamic Delivery title id
title.name Dynamic Delivery title name
video_id Beacon video id

System variables

System variables are provided by the SSAI system and can be information about the end user or helper variables to generate random values. The values must be URI-encoded before being inserted into the URL templates.

System variables are identified as: {{system.*}}

Field Description
ad.position_time The time in seconds of the Cue Point that triggered the ad request; Only available for the VAST ad response type
ip_address End User's IP Address
random_number_32 Random 32-bit integer
random_number_<min>_<max> Generates a random number between two numbers. The range accepted goes from 0 to the max value of UInt32. Only positive numbers are allowed, and the min has to be lower than the max
random_guid Random UUID
referer End User's Referer header value
timestamp_utc Current time as a unix timestamp
unique_user_id MD5(ip_address + user_agent)
unix_timestamp Current time as a unix timestamp (seconds)
user_agent End User's User-Agent header value
uuid Random uuid
x_forwarded_for End User's X-Forwarded-For header value
xfp.correlator Random 64-bit Integer
xfp.ip_address End User's IP Address
xfp.unique_user_id MD5(ip_address + user_agent)
xfp.scor Random 64-bit Integer

Notes

  • This feature works across all platforms/devices iOS, Apple TV, Android, Roku, Fire TV, Web, and Smart TVs.
  • Beacon apps ad targeting can be used with both VOD SSAI and Live SSAI. The details of implementation are shown below.
  • Ad Tag Signals: Pass the user consent string to SSAI, so that SSAI can include their response in the VAST tag that is sent to the customer's ad server.
    • Google Ad Manager requirements
      • GDPR - You must either specifically set npa=1 or include simply npa (without a set value) to tag the request as non-personalized. Ad requests either missing this parameter, or set to npa=0, default to personalized ads.
      • CCPA - You must either specifically set rdp=1 or include simply rdp (without a set value) to restrict data processing. Ad requests either missing this parameter or set to rdp=0, will not restrict, unless the Restrict Data Processing network setting is enabled.
    • Springserve
      • GDPR - A consent string passed from various Consent Management Platforms (CMP's). Also accept numeric value for CTV consent. Value is “gdpr_consent=”.
      • CCPA - A mandatory string for all publishers in which they must pass the privacy consent for users from California. Value is “us_privacy=”.
    • For information about how to implemen OneTrust Cookie Consent with Brightcove Beacon, see Managing Cookie Compliance Using OneTrust Cookie Consent.
  • We support receiving more than one creative in a single pod.

Build your ad targeting parameters

Whether you are using ad targeting with VOD or Live, you need to build the query string which will be used with both. Use the following guidelines when building your ad targeting query string:

  • The client side parameters will be passed to the ad server when requesting ads.
  • Build your ad targeting parameters query string using this general format.: 
    variablename1={VALUEMACRO1}&variablename2={VALUEMACRO2}& ...
  • Example: 
    platform={PLATFORM}&os={OS}&app_id={APP_ID}&rdid={RDID}

Be sure to have your desired ad targeting query string built as you will need it in the implementation steps below in the two sections where you configure an Ad Configuration in Beacon Classic.

Building the ad tag

For the two sections below where you create an ad configuration in Video Cloud Studio, you need to combine your ad tag for your ad server and a modified version of your ad targeting variables query string.

For the instructions below, the ad server tag from the Overview section are used: 

https://ads.brightcove.com/ads?tech=dfpadrules&dur=15

For the instructions below, Beacon ad targeting variables from the Build your ad targeting parameters section are used: 

platform={PLATFORM}&os={OS}&app_id={APP_ID}&rdid={RDID}

VOD SSAI ad tag creation

To build the proper ad tag for the VOD SSAI creation in Video Cloud Studio follow these steps:

  1. In your ad targeting variables, make all the single braces into double braces and change the macro values to lowercase. 
    platform={{platform}}&os={{os}}&app_id={{app_id}}&rdid={{rdid}}
  2. Add url. in front of each value in the double curly braces. 
    platform={{url.platform}}&os={{url.os}}&app_id={{url.app_id}}&rdid={{url.rdid}}
  3. Use your ad tag and append the altered ad targeting variable query string, adding & (ampersand) in front of the ad targeting query string: 
    https://ads.brightcove.com/ads?tech=dfpadrules&dur=15&platform={{url.platform}}&os={{url.os}}&app_id={{url.app_id}}&rdid={{url.rdid}}

The different parts of the ad tag are detailed in the following table:

Ad tag section Description
https://ads.brightcove.com/ads?tech=dfpadrules&dur=15 Base URL of ad server and standard query parameters
&platform={{url.platform}}&os={{url.os}}
&app_id={{url.app_id}}&rdid={{url.rdid}}		 Beacon ad targeting variables

This newly created ad tag will be used in the VOD Steps section below.

Live SSAI ad tag creation

To build the proper ad tag for the Live SSAI creation in Video Cloud Studio follow these steps:

  1. In your ad targeting variables, make all the single braces into double braces and change the macro values to lowercase. 
    platform={{platform}}&os={{os}}&app_id={{app_id}}&rdid={{rdid}}
  2. Use your ad tag and append the altered ad targeting variable query string, adding & (ampersand) in front of the ad targeting query string: 
    https://ads.brightcove.com/ads?tech=dfpadrules&dur=15&platform={{platform}}&os={{os}}&app_id={{app_id}}&rdid={{rdid}}

The different parts of the ad tag are detailed in the following table:

Ad tag section Description
https://ads.brightcove.com/ads?tech=dfpadrules&dur=15 Base URL of ad server and standard query parameters
&platform={{platform}}&os={os}}
&app_id={{app_id}}&rdid={{rdid}}		 Beacon ad targeting variables

This newly created ad tag will be used in the Live steps section below.

VOD steps

Video Cloud steps - VOD

  1. In Video Cloud Studio, navigate to Admin → Server-Side Ad Settings. (For full details see the Implementing VOD SSAI document.)
  2. From the Create Ad Configuration dropdown, select VOD
    Create VOD Ad Config
    Create VOD Ad Config
  3. Complete the following:
    1. Add a name for the ad config.
    2. Select your ad response, VMAP or VAST is recommended. If you use VAST, add cuepoints to the videos to specify where ad breaks should appear.
    3. Paste in your ad tag in the format detailed in the VOD SSAI ad tag creation section above.
    SSAI Configuration VOD
    SSAI Configuration VOD
  4. Click Save.
  5. Find your new ad configuration in the table and copy your ad config ID. You will need this value for the Beacon advertising configuration in the next section.
    copy ad config ID
    Copy ad config ID

Beacon steps - VOD

  1. Open Beacon Classic and navigate to the Advertisement tab.
  2. Click Add New Configuration.
  3. Complete the following:
    1. Name the Ad Configuration.
    2. For the Provider, select Brightcove SSAI.
    3. Paste in the ad targeting parameters query string built in the Build your ad targeting parameters section above. Note that it is NOT proceeded by &.
    4. Paste in the SSAI ad config ID copied in the steps just above into VOD Ad Config ID.
    Beacon Ad Configuration
    Beacon Ad Configuration VOD
  4. Click Create New Advertisement.

Live steps

Video Cloud steps - Live

  1. In Video Cloud Studio, navigate to Admin → Server-Side Ad Settings. (For full details see the Implementing Live SSAI document.)
  2. From the Create Ad Configuration dropdown, select Live
    Create Live Ad Config
    Create Live Ad Config
  3. Complete the following:
    1. Add a name for the ad configuration.
    2. Select VAST for your ad response.
    3. Paste in your ad tag in the format detailed in the Live SSAI ad tag creation section above.
    SSAI Configuration Live
    SSAI Configuration Live
  4. Click Save.
  5. Find your new ad configuration in the table and copy your ad config ID. You will need this value for the Beacon advertising configuration in the next section.
    copy ad config ID
    Copy ad config ID

Beacon steps - Live

  1. Open Beacon Classic and go the Advertisement tab.
  2. Click Add New Configuration.
  3. Complete the following:
    1. Name the Ad Configuration.
    2. For the Provider, select Brightcove SSAI.
    3. Paste in the ad targeting parameters query string built in the Build your ad targeting parameters section above. Note that it is NOT proceeded by &.
    4. Paste in the SSAI ad config ID copied in the steps just above into Live Ad Config ID.
    Beacon Ad Configuration Live
    Beacon Ad Configuration Live
  4. Click Create New Advertisement.