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.
- The ad tag you provide in this setup will include:
- 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_IDandIS_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:
| 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} |
|
| 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=1or include simplynpa(without a set value) to tag the request as non-personalized. Ad requests either missing this parameter, or set tonpa=0, default to personalized ads. - CCPA - You must either specifically set
rdp=1or include simplyrdp(without a set value) to restrict data processing. Ad requests either missing this parameter or set tordp=0, will not restrict, unless the Restrict Data Processing network setting is enabled.
- GDPR - You must either specifically set
- 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=”.
- GDPR - A consent string passed from various Consent Management Platforms (CMP's). Also accept numeric value for CTV consent. Value is
- For information about how to implemen OneTrust Cookie Consent with Brightcove Beacon, see Managing Cookie Compliance Using OneTrust Cookie Consent.
- Google Ad Manager requirements
- 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=15For 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:
- 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}} - 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}} - 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}} |
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:
- 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}} - 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}} |
Beacon ad targeting variables |
This newly created ad tag will be used in the Live steps section below.
VOD steps
Video Cloud steps - VOD
- In Video Cloud Studio, navigate to Admin → Server-Side Ad Settings. (For full details see the Implementing VOD SSAI document.)
-
From the dropdown, select VOD
Create VOD Ad Config - Complete the following:
- Add a name for the ad config.
- 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.
- Paste in your ad tag in the format detailed in the VOD SSAI ad tag creation section above.
SSAI Configuration VOD - Click Save.
- 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
Beacon steps - VOD
- Open Beacon Classic and navigate to the Advertisement tab.
- Click .
- Complete the following:
- Name the Ad Configuration.
- For the Provider, select Brightcove SSAI.
- 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 &.
- Paste in the SSAI ad config ID copied in the steps just above into VOD Ad Config ID.
Beacon Ad Configuration VOD - Click .
Live steps
Video Cloud steps - Live
- In Video Cloud Studio, navigate to Admin → Server-Side Ad Settings. (For full details see the Implementing Live SSAI document.)
-
From the Create Ad Configuration dropdown, select Live
Create Live Ad Config - Complete the following:
- Add a name for the ad configuration.
- Select VAST for your ad response.
- Paste in your ad tag in the format detailed in the Live SSAI ad tag creation section above.
SSAI Configuration Live - Click Save.
- 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
Beacon steps - Live
- Open Beacon Classic and go the Advertisement tab.
- Click .
- Complete the following:
- Name the Ad Configuration.
- For the Provider, select Brightcove SSAI.
- 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 &.
- Paste in the SSAI ad config ID copied in the steps just above into Live Ad Config ID.
Beacon Ad Configuration Live - Click .