Contact Support | System Status
Page Contents

    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

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

    • Ad targeting variable/value pairs are passed to the playback infrastructure.
    • The playback infrastructure then in turn passes the targeting information to SSAI via {{url.xxx}} ad macros.
    • SSAI then requests ads from your ad server using a VAST tag using the client side information.

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

    Within Video Cloud Studio and Beacon Classic, you can set up how this data is passed to your ad server or ad provider.

    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.
      • 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 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.

    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.

    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.

    Page last updated on 21 Oct 2021