Once UX VMAP for Twitter Amplify

API Developer
Social Sharing
VOD 2.0

Once UX VMAP for Twitter Amplify is an extension to Brightcove’s Once UX service. It is built upon the IAB VMAP 1.0 specification which is consumable by Twitter’s video player in iOS, Android and desktop applications. Utilizing native Once device detection and decisioning logic, or alternatively when explicitly requesting the Amplify format, the service will respond to the client with the applicable VMAP 1.0 XML and video content based upon in-request or preconfigured business logic as detailed within this document.


  • Utilize new or existing Once VOD content when distributing via Twitter Amplify.
  • No need to change ad decisioning systems to work with Amplify and non-Amplify distribution.
  • Flexible usage based on per-request, pre-configured, or ad server-derived Amplify required parameters.
  • All ad and beacon tracking will be exposed to the Twitter client which will fire all impressions, tracking events and other callbacks presented via the Once UX VMAP response.


As an extension of the Once UX service, the VMAP XML presented to Twitter Amplify is based upon Internet Advertising Bureau (IAB) specifications for VMAP 1.0 and VAST 3.0. All video session metadata - both publisher and ad creative content - is formatted to adhere to the Twitter Amplify specification for consumption by the Twitter client application. Once UX contains built-in functionality capable of determining the requesting device and application, dynamically generating a Twitter Amplify VMAP response which includes advertising data, 3rd party audience measurement data and the video content stream URI.


  • You must use an Ad Partner that can adhere to the unique response requirements to fulfill Twitter requirements for the brandId (the Twitter ownerId of the advertiser)
  • You must provide your Twitter ownerId (the id for your Twitter account) to be associated with all content delivered through Twitter Amplify
  • Only a single pre-roll is supported by Twitter Amplify - any additional ad configuration could result in ad beacons never being requested by the Amplify Player

Once UX API request

All requests will be type GET and must be made via SSL (this is a Twitter requirement):

Argument Description
domainGUID Unique identifier for the domain
applicationGUID Unique identifier for the application
mediaitemGUID or foreignKey Unique identifier for the media item
Forcetav=true Explicit parameter to generate a VMAP with Twitter extensions (required)
Parameter values Dynamic or static key/value pairs used to pass information to the ad server (optional)

For a forced rendition:

Argument Description
deliveryType Method of delivery type (adaptive|stitched)
requestedFileType Type of file being returned (m3u8|mp4)
domainGUID Unique identifier for the domain
applicationGUID Unique identifier for the application
mediaitemGUID or foreignKey Unique identifier for the media item
Forcetav=true Explicit parameter to generate a VMAP with Twitter extensions (required)
Parameter values Dynamic or static key/value pairs used to pass information to the ad server (optional)


Twitter card excerpt:

Twitter Amplify Metadata Requirements

Publisher ownerId (required)

The Publisher's Twitter ownerId is required and must be a numeric ID associated with the Twitter account where the content will be served. The ID can be retrieved from Twitter. This value SHOULD be passed as extended metadata on ingest for the video content into the Once system.

Example of adding extended metadata within ingest request (see the guide to the API Content Ingest for more details):


Options for ownerId retrieval

  • Configured for the entire domain
    • Should only be done if multiple Twitter accounts are not associated to the same domain.
  • Configured for the application
    • Can be used for existing customers with content already in the Once system.
    • Provides granularity in case a single domain delivers to multiple Twitter accounts.
    • An application configuration will overwrite any existing domain configuration.
  • Set via Query String
    • Can be set explicity on the query string of the Once UX request.
      • Example: ?twownerId=ownerId or &twownerId=ownerId
    • A query string value will overwrite any application and domain configurations.

Publisher contentId (required)

The contentId is used by Twitter to uniquely identify the content being viewed. The "Foreign Key" within the Once system is used to pass into the Twitter Amplify VMAP response. Items within the Once system should be configured with foreign keys otherwise it could impact metrics gathered by Twitter for accurate reporting.

Advertiser brandId (required)

The brandid should be included in the ad server response and adhere to Twitter Amplify requirements, where brandid must be numeric and represents the advertiser’s Twitter ownerId. The brandid from the customer ADS must follow the same xpath to ensure proper parsing by the Once system for visibility in the VMAP object.

Notify Brightcove Support of any changes to the ADS.

Options for brandId (if not supported by ADS)

  • Set via Query String
    • In the case that the ADS does not respond with a brandId , the appropriate brandId can be retrieved from Twitter and passed on the Once UX request
      • Example: ?twbrandId=brandId or &twbrandId=brandId

Content and Ad Tracking Events

Content and Ad tracking are both configurable within the Once system to expose impressions and tracking events to the Twitter Amplify client, which in-turn will fire events at appropriate playhead intervals. These supported beacons include:

  • start
  • firstQuartile
  • midpoint
  • thirdQuartile
  • complete
  • pause
  • rewind
  • resume

Content tracking MUST be preconfigured by Brightcove with the appropriate third party tracking tag URLs. These beacons are configurable per application, and can further be configured to pass dynamic or static metadata values.

Video Ad Creatives

Video ad creatives do not need to be pre-loaded into Once, as the system will automatically ingest any new ad creatives utilizing the Ad Cache service and prepare them for server-side insertion and delivery.


Below is a sample Twitter Card html.

For help on creating the Twitter Amplify VMAP XML, contact Once Support.

Twitter Card html

<!DOCTYPE html>
<html lang="en">
        <meta charset="utf-8">

        <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">


    <meta name="twitter:card" content="amplify"/>
    <meta name="twitter:description" content="Video Description">
    <meta name="twitter:domain" content="https://twitter.com/DomainName">
    <meta name="twitter:site" content="@DomainName">
    <meta name="twitter:player:width" content="320">
    <meta name="twitter:player:height" content="240">
    <meta name="twitter:image:src" content="https://brightcove.com/image.jpg">
    <meta name="twitter:player:stream:content_type" content="video/mp4">
    <meta name="twitter:creator" content="@OnceTesting">
    <meta name="twitter:amplify:vmap" content="https://Once UX.unicornmedia.com/now/ads/vmap/od/auto/b2df377d-7f81-4be2-92c2-f07dc272064a/c92617d4-b9bb-4df2-935f-d75a009bd4fd/d482b365-1a4f-4464-af2a-43d0b322211e/content.once?forcetav=true" />
             color: #FFFFFF;

            <div class="noText">Some place holder text</div>