Contact Support | System Status
Page Contents

    Beacon Apps Ad Targeting

    Beacon Apps Ad targeting allows Beacon customers to send important device-level and user-specific information from the customer’s Beacon apps to their ad server or ad provider.

    Introduction

    Client-side information is passed from the apps to SSAI, and then SSAI includes this data in the customer’s VAST tag, which then allows customers to target ads based on this data. The purpose of this is to increase the value of customers’ ad inventory, therefore increasing ad revenue for their business.

    Within Studio and Beacon CMS, you can set up how this data is passed to their ad server or ad provider.

    Benefits

    Improved ad targeting

    • User Session ID: we generate 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 params like Device ID, you can pass this valuable information to programmatic ad buyers, which will then enhance their 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. 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 their apps and pass the device params to your ad server. Inside your ad server, you will implement the business logic that splits the ad inventory by device. The platforms also require passing LAT - Limited Ad Targeting - for Ad Inventory Split, which is a parameter we are now sending to your ad server.

    User Privacy improvements

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

    Targeting information

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

    Targeting Information
    Type of information Variable Name Values
    Platform platform iOS, Android, Roku, AppleTV, Web, STV
    OS version os device os version (for example, iOS 14)
    Device model model device model. Browser version used for web apps
    Manufacturer mfgr device manufacturer; browser name used for web apps
    Language lang Language code set in the App (that comes from CMS)
    User session 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 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 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 adid = Android, idfa = Apple phones (iOS), afai = Amazon, rida: Roku tvOS: AppleTV (tvOS)
    App identifier app_id This should be the App bundle name

    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.

    Implementation

    Below is a list of value macros that will be passed to the app, which will then substitute the real values before sending to the ad server. They are NOT configurable.

    Value Macros
    Macro Description
    PLATFORM The appropriate beacon platform: iOS, AppleTV, Android, Roku, Web, STV
    OS full qualified OS (including version) - example iOS 14
    MFGR the Manufacturer of the device; (Web - user's browser)
    MODEL Device Model; (Web - browser version)
    APP_ID Application id (for example bundle ID); Web: app domain
    LOCALE ISO 639-1 (2-letter) language code followed by an underscore and a ISO 3166-1 (2-letter) country code (example en_us) - language set in the app
    RDID Resettable device ID (tifa: Samsung, rida: Roku, adid: Android, etc. - see Device identifiers below for more values) - if limited ad targeting is set on the App, then the id should be all zeros (meaning not possible to identify the user/device)
    IDTYPE Type resettable ID (tifa: Samsung, rida: Roku, adid: Android, etc. - see Device identifiers below for more values)
    IS_LAT Flag that tells if limited ad targeting is selected by user: 0 if user has not opted to limit targeting, 1 if limiting ad targeting
    SID Unique session identifier (reset every time the app starts). Not dependent on user sign in / Sign up. Switching from foreground to background status does not change this ID.

    Device identifiers

    • adid: Android
    • afai: Amazon
    • tvOS: AppleTV (tvOS)
    • idfa: Apple phones (iOS)
    • rida: Roku
    • tifa: Samsung
    • vida: Vizio
    • msai: Xbox

    VOD steps

    Video Cloud part - VOD

    1. Create an ad config from the Server Side Ad settings page in Studio:
      1. Click Create Ad Configuration and select VOD
        Create VOD Ad Config
        Create VOD Ad Config
        SSAI Configuration VOD
        SSAI Configuration VOD
      2. Add a name for the ad config.
      3. Select your ad response - VMAP or Vast is recommended. If you use Vast, you will need to add cuepoints to the videos to specify where ad breaks should appear.
      4. Paste in your ad tag (from you ad provider).
      5. Copy your ad config ID, as you will need it for the Beacon advertising configuration.

    Beacon part - VOD

    1. Open the Beacon Classic UI and go the Advertisement tab:
      1. Click Add New Configuration
        Beacon Ad Configuration
        Beacon Ad Configuration VOD
      2. Name the Ad Configuration
      3. Select Brightcove SSAI
      4. Paste in the SSAI ad config ID into VOD Ad Config ID
    2. Once you have your Ad config setup in Studio and Beacon Classic, you need to implement the client side params that will be passed to the customers ad server. Client side parameters can be passed in the Playback APIs (provided in the VMAP/Manifest entry point) - those will be available to the SSAI infrastructure in the form of {{url.xxx}} macros where the xxx corresponds to the parameter key that is submitted in the playback API URL.
      1. Enter ad targeting params in the Ad-Target field in Beacon. The input will be a string in query form. Example: d={PLATFORM}&os={OS}&man={MFGR}&mo={MODEL}&appid={APP_ID}&lan={LOCALE}&did={RDID}&dt={IDTYPE}&lat={IS_LAT}&sid={SID}
      2. You can configure the keys before the equal sign. They MUST match the keys that are added to the SSAI ad tag.
      3. Next, update your ad tag in the SSAI Studio Settings page. Here is an example of params that were entered in the Beacon Classic Ad-Targeting and added to SSAI Ad tag: d={PLATFORM}&os={OS}&appid={APP_ID}&did={RDID}&dt={IDTYPE}&lat={IS_LAT}&sid={SID}
      4. These params get translated into this in this Ad tag: https://ads.brightcove.com/ads?tech=dfpadrules&dur=15&pre=3&d={{url.d}}&os={{url.os}}&appid={{url.appid}}&did={{url.did}}&dt={{url.dt}}&lat={{url.latl}}&sid={{url.sid}}

    Live steps

    1. First, construct your ad-targeting parameter string, as you will need it both in the SSAI and Beacon configurations. You can reuse the params for VOD, or select a different set.

      Example:

      ip={{client.ipaddress}}&num={{random.int32}}&d={{PLATFORM}}&os={{OS}}&did={{RDID}}&dt={{IDTYPE}}&lat={{IS_LAT}}
    2. Create an ad config from the Server Side Ad settings page in Studio:
      1. Click Create Ad Configuration and select Live
        Create Live Ad Config
        Create Live Ad Config
        SSAI Configuration Live
        SSAI Configuration Live
      2. Add a name for the ad config
      3. Select Vast your ad response
      4. Paste in your ad tag, appending your query string of ad targeting params.

        Example:

        https://ad-provider-host.com/path/to/ad-handler?ip={{client.ipaddress}}&num={{random.int32}}&d={{PLATFORM}}&os={{OS}}&did={{RDID}}&dt={{IDTYPE}}&lat={{IS_LAT}}
      5. Copy your ad config ID for the Beacon Advertising configurations
    3. Open the Beacon Classic UI and go the Advertisement tab
      1. Click Add New Configuration
        Beacon Ad Configuration Live
        Beacon Ad Configuration Live
      2. Name the Ad Configuration
      3. Select Brightcove SSAI
      4. Paste in the SSAI ad config ID into Live Ad Config ID
    4. Paste your string of ad-targeting params in the Ad-Target field.

      Example:

      d={{PLATFORM}}&os={{OS}}&did={{RDID}}&dt={{IDTYPE}}&lat={{IS_LAT}}

    Page last updated on 29 Apr 2021