Native Video Ads

Native video ads are one type of native ad unit available on Ad Exchange. The bid request and bid response for native video units are virtually identical to those of non-video native, except the request also indicates video as one of the required or optional fields--and the response includes an additional URL field that opens to a valid VAST XML document, like this example.

Native ads are component-based ads formatted to fit the surrounding content and visual design, making them more likely to be viewed and clicked by users. Native ad inventory is available on mobile apps as well as desktop and mobile websites. This is true of native video as well.

How it works

  1. A call for a native ad is made to Ad Exchange. The call specifies one or more of the native ad templates below, each specifying the desired native fields.

  2. Ad Exchange sends buyers an RTB bid request containing a list of the fields being requested. For native video, one of the requested fields will be video.

  3. Interested buyers respond with the requested fields, including a VAST video URL for native video.

  4. Ad Exchange runs an auction to select the winning bid and sends the buyer's supplied creative assets to the publisher.

  5. The publisher assembles the assets into a native ad and styles them to fit the site's design.

Native video ad templates

Ad Exchange uses the following two native video ad templates:

Major differences from native non-video are highlighted below.

Video app install ad template

Field Description Must buyers supply the field? Must publishers show the field? Recommended image size/max number of chars * Example
Video The video VAST response containing all necessary assets to play back a video ad. Yes Yes - A URL to VAST XML containing a Flood-It! Video ad
Headline The app title Yes Yes 25 chars Flood-It!
Image Image (thumbnail) shown in the player before the video ad is clicked or while it is loading. Yes No, but recommended Should match aspect ratio of video (for example: 1280x720 for 16x9 video, 4x3 for 640x480 video). A screenshot from the game Flood-It! Or from the video
Body Main text of the app Yes No, but recommended 90 chars Deceptively simple + tantalizingly challenging = delightfully addictive!
App icon The app icon Yes Yes 128 x 128 px Flood-it! app icon
Call to action Desired user action Yes Yes 15 chars Install
Star rating Number of stars (0 - 5) representing the app's rating in the app store No, but recommended No, but recommended 0 - 5 4.5
Price The cost of the app No, but recommended No, but recommended 15 chars Free

* Note

  • Video
    • Note that all video must be in the form of a VAST URL. The bidder cannot return a raw video file (WebM, MP4, etc.).
  • Text length

    • If a buyer sends a text asset (body text, for example) longer than the suggested maximum number of characters, the text may be truncated and ellipsized by Ad Exchange or the publisher. Note that the truncation limits are half the size in Chinese, Japanese, and Korean. For example, the headline limit is 90 for English and 45 for Chinese.
  • Image size - publishers are allowed to:

    • Crop the main image symmetrically by up to 20% in one dimension (height or width).
    • Scale the image without changing its aspect ratio.

App install ad example

Video content ad template

Field Description Must buyers supply the field? Must publishers show the field? Recommended image size/max number of chars * Example
Video The video VAST response containing all necessary assets to play back a video ad. Yes Yes - A URL to VAST XML containing a Flood-It! Video ad
Headline The ad header Yes Yes 25 chars Lowest mortgage rates
Image Image (thumbnail) shown in the player before the video ad is clicked or while it is loading. Yes No, but recommended Should match aspect ratio of video (for example: 1280x720 for 16x9 video, 4x3 for 640x480 video). A screenshot from the video
Body The ad content Yes Yes 90 chars Your home sweet Brooklyn home - cheaper and sooner than you think!
Logo Advertiser’s logo or another relevant small image No, but recommended No, but recommended 128 x 128 px NY Mortgage Inc.'s logo
Call to action User's desired action Yes No, but recommended 15 chars Get a quote
Advertiser Text that identifies the advertiser or brand Yes No, but recommended 25 chars NY Mortgage Inc.

Meta fields

The following meta fields are shared by the video app install ad template and the video content ad template:

Ad Exchange Protocol Buffer Ad Exchange OpenRTB Equivalent Description
NativeAd.click_link_url Link.url The URL that will be called by the browser when the user clicks the ad. Can be the first step of a redirect chain that eventually leads to the landing page. Video clicks should be done through the VAST standard fields.
Ad.click_through_url Bid.adomain The set of destination URLs for the snippet. This includes the URLs that the user will go to if they click on the displayed ad, and any URLs that are visible in the rendered ad. Do not include intermediate calls to the adserver that are unrelated to the final landing page. A BidResponse that returns a snippet or video ad but declares no click_through_url will be discarded. Only set this field if html_snippet, video_url, or native_ad are set. This data is used as a destination URL declaration, for example for post-filtering of publisher-blocked URLs or ad categorization.
For non-native ads, it is not used for click tracking or any other ad functionality; it is only used as a destination URL declaration.
For native ads, if NativeAd.click_link_url is not set, the first value of click_through_url is used to direct the user to the landing page. In addition, all values are used as destination URL declarations (similar to the non-native case).
NativeAd.click_tracking_url Link.clicktrackers Additional URLs that allow advertisers to track user clicks on the ad. This is part of the Native message in the response, and is used for tracking clicks on portions of the native ad unit that are not the video. Video click tracking should be done through the VAST standard fields.
Ad.ad_choices_destination_url BidExt.ad_choices_destination_url Link to an ad preferences or opt-out page. If present, a standard AdChoices icon is added to the native creative and linked to this URL. This is supported for native ads but is not part of the native message in the bid response.
Ad.impression_tracking_url NativeResponse.imptrackers The native impression should be tracked with impression_tracking_url in Ad Exchange proto or Native imptrackers in OpenRTB.
The non-video impression tracker is the official impression tracker for billing purposes. It is also acceptable and typical to include an impression tracker within the VAST XML itself so the VAST ad server has a record of the impression, and both will be pinged on an impression, notwithstanding that the VAST impression tracker is not the official impression for billing.


NativeAdTemplate message

For native ads support, Ad Exchange adds the NativeAdTemplate message within the BidRequest.AdSlot message:

message BidRequest {
  //...
  message AdSlot {
    //...
    message NativeAdTemplate {
      // Defines the bits used in required_fields and recommended_fields.
      // There is one bit for each of the fields in BidResponse.Ad.NativeAd
      enum Fields {
        HEADLINE = 1;
        BODY = 2;
        CALL_TO_ACTION = 4;
        ADVERTISER = 8;
        IMAGE = 16;
        LOGO = 32;
        APP_ICON = 64;
        STAR_RATING = 128;
        PRICE = 256;
        STORE = 512;
        VIDEO = 0x400;
      }

      // Bitfield describing which fields are required by the publisher. Bid
      // responses with no value for these fields will be rejected. Click
      // and view tracking urls are always implicitly required.
      optional int64 required_fields = 1;

      // Bitfield describing which fields are recommended by the publisher.
      // All recommended field are supported, but not all recommended fields
      // are required.
      optional int64 recommended_fields = 2;

      // max_safe_length indicates the maximum number of Unicode characters
      // that are guaranteed to be shown without truncation. Longer strings
      // may be truncated and ellipsized by AdExchange or the publisher
      // during rendering.
      optional int32 headline_max_safe_length = 3;
      optional int32 body_max_safe_length = 4;
      optional int32 call_to_action_max_safe_length = 5;
      optional int32 advertiser_max_safe_length = 6;
      optional int32 store_max_safe_length = 14;
      optional int32 price_max_safe_length = 15;

      // Image widths and heights are specified in pixels. You may provide a
      // larger image in the response.
      optional int32 image_width = 7;
      optional int32 image_height = 8;
      optional int32 logo_width = 9;
      optional int32 logo_height = 10;
      optional int32 app_icon_width = 11;
      optional int32 app_icon_height = 12;
    }
    repeated NativeAdTemplate native_ad_template = 51;
  }
  // ...
}

NativeAd message

For native ads support, Ad Exchange adds the NativeAd message within the BidResponse.Ad message. A buyer who responds to a native ad bid request must supply the fields declared in the NativeAd message.

message BidResponse {
  //...
  message Ad {
    //...
    message NativeAd {
      // A short title for the ad.
      optional string headline = 1;

      // A long description of the ad.
      optional string body = 2;

      // A label for the button that the user is supposed to click.
      optional string call_to_action = 3;

      // The name of the advertiser or sponsor, to be displayed in the ad
      // creative.
      optional string advertiser = 4;

      // Next tag to use: 4
      message Image {
        optional string url = 1;
        // Image width and height are specified in pixels. You may provide a
        // larger image than was requested, so long as the aspect ratio is
        // preserved.
        optional int32 width = 2;
        optional int32 height = 3;
      }

      // A large image.
      optional Image image = 5;

      // A smaller image, for the advertiser's logo.
      optional Image logo = 6;

      // The app icon, for app download ads.
      optional Image app_icon = 7;

      // The app rating in the app store. Must be in the range [0-5].
      optional double star_rating = 8;

      // The URLs are called when the impression is rendered.
      // Deprecated. Use the regular impression tracking URL instead.
      repeated string impression_tracking_url = 9;

      // The URL to use for click tracking. The SDK pings click tracking url
      // on a background thread. When resolving the url, HTTP 30x redirects
      // are followed. The SDK ignores the contents of the response; this URL
      // has no effect on the landing page for the user.
      optional string click_tracking_url = 11;

      // The URL to fetch a video ad. The URL should return an XML response that
      // conforms to the VAST 2.0 standard. Only set this field if the
      // BidRequest is for native ads and video field is requested.
      optional string video_url = 13;
    };

    optional NativeAd native_ad = 18;

    // The set of destination URLs for the snippet. This includes
    // the URLs that the user will go to if they click on the displayed
    // ad, and any URLs that are visible in the rendered ad. Do not
    // include intermediate calls to the adserver that are unrelated to the
    // final landing page. A BidResponse that returns a snippet or video
    // ad but declares no click_through_url will be discarded. Only set
    // this field if html_snippet or video_url or native_ad are set.
    // This data is used as a destination URL declaration for things like
    // post-filtering of publisher-blocked URLs or ad categorization.
    //
    // For non-native ads, it is not used for click tracking or any
    // other ad functionality; it is only used as a destination URL
    // declaration.
    //
    // For native ads, if NativeAd.click_link_url is not set, the first
    // value of click_through_url is used to direct the user to the landing
    // page. In addition, all values are used as destination
    // URL declarations (similar to the non-native case).
    repeated string click_through_url = 4 [
        (datapol.semantic_type) = ST_CONTENT_DEPENDENT,
        (datapol.data_format) = DF_URL
    ];

    // The URLs to call when the impression is rendered. The SDK pings
    // impression urls on a background thread and ignores the contents
    // of the response. Replaces the native impression tracking URL.
    repeated string impression_tracking_url = 19;

    // Link to ad preferences page. This is only supported for native ads.
    // If present, a standard AdChoices icon is added to the native ad creative and
    // linked to this URL.
    optional string ad_choices_destination_url = 21;
  }
}

Example bid request

bid_request {
  ...
  adslot {
    ....
    native_ad_template {
      required_fields: 1111
      recommended_fields: 896
      headline_max_safe_length: 25
      body_max_safe_length: 90
      call_to_action_max_safe_length: 15
      app_icon_width: 128
      app_icon_height: 128
    }
    native_ad_template {
      required_fields: 1085
      recommended_fields: 2
      headline_max_safe_length: 25
      body_max_safe_length: 90
      call_to_action_max_safe_length: 15
      advertiser_max_safe_length: 25
      logo_width: 128
      logo_height: 128
    }
  }
  ...
}

Example bid response

bid_response {
  ad {
    ...
    click_through_url: "https://www.exampleDomain.com"
    impression_tracking_url: "https://my_impression_tracking_url.com/"
    ad_choices_destination_url: "https://my_ad_choices_destination_url.com/"
    ...
    native_ad {
      headline: "Lowest mortgage rates"
      video_url: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast"
      call_to_action: "Get a quote"
      advertiser: "NY Mortgage Inc."
      image {
        url: "https://www.example.net/mypromoimage.png"
        width: 1200
        height: 700
      }
      logo {
        url: "https://www.example.net/mylogo.png"
        width: 200
        height: 200
      }
      click_link_url: "https://r1.example.com/r/u1dhfh3cow00/b1_googleadx/830/41972/ ?_b_ctrl=1"
      click_tracking_url: "https://my_click_tracking_url.com/"
    }
  }
}

Send feedback about...

Real-Time Bidding Protocol
Real-Time Bidding Protocol