Native ads are 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. For more information on native ads, see the following:
How it works
- A call for a native ad is made to Authorized Buyers. The call specifies one or both of the native ad templates below, each specifying the desired native fields.
- Authorized Buyers sends buyers an RTB bid request containing a list of the fields being requested.
- Interested buyers respond with the requested fields.
- Authorized Buyers runs an auction to select the winning bid and sends the buyer's supplied creative assets to the publisher.
- The publisher assembles the assets into a native ad and styles them to fit the site's design.
Required and recommended fields
The tables below show fields labeled Required or Recommended. The following rules apply:- Fields marked Required are required by the bidder.
- Fields marked Recommended are not required by the bidder, and the publisher may or may not display them if supplied (for example, star rating).
- Call to Action (CTA) is always marked as Recommended because a default is assigned if one is not sent by the bidder, but it will always be displayed if sent.
Native ad templates
Authorized Buyers supports the two most common native ad templates:
Other templates exist, and may have a different set of requirements for fields, dimensions, and sizes.
App install ad template
The following table lists the fields of an app install ad template. Mobile apps use these fields to create native app install ads.
| Field | Description | Required or Recommended? | Always displayed? | Recommended image size/max number of chars | Example |
|---|---|---|---|---|---|
| Headline | The app title | Required | Yes | 25 chars | Flood-It! |
| Image | A screenshot from the app, or another relevant image | Required | No | 1,200px x 627px or 600px x 600px depending on the aspect ratio required by the publisher. | <A screenshot from the game Flood-It!> |
| Body | Main text of the app | Required | No | 90 chars | Deceptively simple + tantalizingly challenging = delightfully addictive! |
| App icon | The app icon | Required | No | 128 x 128 px | <Flood-it! app icon> |
| Call to action | Desired user action | Recommended | Yes | 15 chars | Install |
| Star rating | Number of stars (0 - 5) representing the app's rating in the app store | Recommended | No | 0 - 5 | 4.5 |
| Price | The cost of the app | Recommended | No | 15 chars | Free |
Notes about 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 Authorized Buyers 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.
Notes about 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.
- Images that have aspect ratios substantially different than those implied by the height and width may be filtered.
Content ad template
The following table lists the fields of a content ad template. Publishers use these fields to create native content ads.
| Field | Description | Required or Recommended? | Always displayed? | Recommended image size/max number of chars * | Example |
|---|---|---|---|---|---|
| Headline | The ad header | Required | Yes | 25 chars | Lowest mortgage rates |
| Image | The ad's primary image | Required | No | 1,200px x 627px or 600px x 600px depending on the aspect ratio required by the publisher. | <Ad's main image> |
| Body | The ad content | Required | No | 90 chars | Your home sweet Brooklyn home - cheaper and sooner than you think! |
| Logo | Advertiser’s logo or another relevant small image | Recommended | No | 128 x 128 px | <NY Mortgage Inc.'s logo> |
| Call to action | User's desired action | Recommended | No | 15 chars | Get a quote |
| Advertiser | Text that identifies the advertiser or brand | Required | No | 25 chars | NY Mortgage Inc. |
Meta fields
The following meta fields are shared by the app install ad template and the content ad template:
| Authorized Buyers real time protocol buffer | Authorized Buyers 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. |
Ad.click_through_url |
Bid.adomain |
Must be set if the bidder intends to bid. This is the set of destination URLs for the snippet,
including 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_urls |
Link.clicktrackers |
Optional. Additional URLs that allow advertisers to track user clicks on the ad. |
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 Authorized Buyers real-time bidding proto or Native imptrackers in OpenRTB. |
Required and recommended fields
required_fields
and recommended_fields are specified by the publisher. We show
how to translate these bit fields to determine if a field is required or
recommended.
A bit field uses each bit of a binary value to store a true or false statement,
equivalent to sending many boolean signals like is_logo_required,
is_header_required, etc. but all packed together.
Example
For this example we'll use a required_fields value of 1085.
First, find the equivalent binary
value: 10000111101
Once you have the binary value, you can check the bits to see if a field is required (1) or not required (0).
The table below maps the fields to their place in the binary value. Read the binary from right to left, with the 1-bit corresponding to the right-most place in the binary value.
| Field | Binary value placement (right to left) |
|---|---|
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 |
1024 |
Looking at the example binary value 10000111101, the 1-bit
(rightmost) is 1, signifying a required value. According to the
table, the 1-bit corresponds to HEADLINE.
The 2-bit (second value from the right) is 0 signifying not required.
The 2-bit corresponds to BODY.
Here are all the interpreted required fields in our example:
| Value | Description | Required? |
|---|---|---|
1 |
VIDEO |
Yes |
0 |
STORE |
No |
0 |
PRICE |
No |
0 |
STAR_RATING |
No |
0 |
APP_ICON |
No |
1 |
LOGO |
Yes |
1 |
IMAGE |
Yes |
1 |
ADVERTISER |
Yes |
1 |
CALL_TO_ACTION |
Yes |
0 |
BODY |
No |
1 |
HEADLINE |
Yes |
NativeAdTemplate message
For native ads support, Authorized Buyers adds the NativeAdTemplate
message within the
BidRequest.AdSlot message. This message provides specifications for:
- Fields that are required or recommended.
- Dimensions for images, logos, and app icons.
- Specifications for the style in which the ad is rendered.
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;
}
// 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;
// Globally distinct id for the specific style, HTML, and CSS with which
// the native ad is rendered.
optional int32 style_id = 16;
// Type of style layout for each native ad template.
enum LayoutType {
PIXEL = 0;
FLUID = 1;
}
optional LayoutType style_layout_type = 17 [default = PIXEL];
// If the style_layout_type is Pixel, width and height of the
// entire native ad after rendering. If the style_layout_type is
// Fluid, the style_height and style_width may optionally
// not be populated.
optional int32 style_height = 18;
optional int32 style_width = 19;
}
repeated NativeAdTemplate native_ad_template = 51;
}
// ...
}
NativeAd message
For native ads support, Authorized Buyers 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 URLs to use for click tracking. This will be used throughout the
// serving stack and will incorporate any URL in click_tracking_urls.
repeated string click_tracking_urls = 15;
};
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: 87
recommended_fields: 896
headline_max_safe_length: 25
body_max_safe_length: 90
call_to_action_max_safe_length: 15
store_max_safe_length: 15
price_max_safe_length: 15
image_width: 1200
image_height: 627
app_icon_width: 128
app_icon_height: 128
}
native_ad_template {
required_fields: 31
recommended_fields: 32
headline_max_safe_length: 25
body_max_safe_length: 90
call_to_action_max_safe_length: 15
advertiser_max_safe_length: 25
image_width: 1200
image_height: 627
logo_width: 128
logo_height: 128
style_id: 68070
style_layout_type: FLUID
style_height: 1
style_width: 1
}
}
...
}
Example bid response
Note that the values in this response are not intended to match the corresponding request above.
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"
body: "Your home sweet Brooklyn home - cheaper and sooner than you think!"
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_urls: "https://my_click_tracking_url.com/"
}
}
}
Example OpenRTB request
{
"id": "W1ggggEEEO4KUaXnhgPhtA",
"imp": [
{
"id": "1",
"banner": {
"w": 300,
"h": 250,
"pos": 1,
"api": [
3,
5
],
"format": [
{
"w": 300,
"h": 250
},
{
"w": 320,
"h": 240
}
]
},
"tagid": "2480000090",
"bidfloor": 1.1100000000000001,
"bidfloorcur": "USD",
"secure": 1,
"native": {
"request": "{\"ver\":\"1.2\",\"assets\":[{\"id\":1,\"required\":1,\"title\":{\"len\":90}},{\"id\":2,\"data\":{\"type\":12,\"len\":15}},{\"id\":3,\"required\":1,\"data\":{\"type\":1,\"len\":25}},{\"id\":4,\"required\":1,\"img\":{\"type\":3,\"wmin\":1200,\"hmin\":627}},{\"id\":5,\"img\":{\"type\":2,\"wmin\":100,\"hmin\":100}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}],\"ext\":{\"style_id\":106354,\"style_height\":240,\"style_width\":320}}",
"ver": "1.2",
"api": [
3,
5
]
},
"metric": [
{
"type": "viewability",
"value": 0.69999999999999996,
"vendor": "EXCHANGE"
},
{
"type": "session_depth",
"value": 1,
"vendor": "EXCHANGE"
}
],
"ext": {
"billing_id": [
"36884972063",
"16723629405",
"26278646423"
],
"publisher_settings_list_id": [
"11112222333344445555",
"66662222333344445555",
],
"allowed_vendor_type": [
10
],
"ampad": 2
}
}
],
"app": {
"name": "Weeronline - weer & radar",
"cat": [
"IAB15-10"
],
"bundle": "12345678",
"publisher": {
"id": "pub-3333222211111111",
"ext": {
"country": "NL"
}
},
"content": {
"url": "https://itunes.apple.com/app/id12345678",
"contentrating": "DV-G",
"language": "nl"
}
},
"device": {
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77",
"ip": "11.111.11.0",
"geo": {
"country": "NLD",
"region": "NL-NH",
"city": "Amsterdam",
"utcoffset": 120
},
"carrier": "70360",
"make": "apple",
"model": "iphone",
"os": "iOS",
"osv": "11.4.4",
"devicetype": 4,
"ifa": "11223344-AAAA-BBBB-CCCC-D3415AB2642D",
"hwv": "6s",
"w": 320,
"h": 568,
"pxratio": 2
},
"user": {
"id": "AAAAAkbEH-bU3qXaVgNSGhVVfk",
"data": [
{
"id": "DetectedVerticals",
"name": "DoubleClick",
"segment": [
{
"id": "63",
"value": "0.5"
},
{
"id": "1462",
"value": "0.5"
}
]
}
],
"ext": {
"consented_providers_settings": {
"consented_providers": [
"1024",
"2044"
]
}
}
},
"tmax": 122,
"cur": [
"USD"
],
"bcat": [
"IAB14-1",
"IAB23-6"
],
"regs": {
"ext": {
"gdpr": true
}
}
}
NATIVE PART ONLY
Deobjectified under request
{
"ver": "1.2",
"assets": [
{
"id": 1,
"required": 1,
"title": {
"len": 90
}
},
{
"id": 2,
"data": {
"type": 12,
"len": 15
}
},
{
"id": 3,
"required": 1,
"data": {
"type": 1,
"len": 25
}
},
{
"id": 4,
"required": 1,
"img": {
"type": 3,
"wmin": 1200,
"hmin": 627
}
},
{
"id": 5,
"img": {
"type": 2,
"wmin": 100,
"hmin": 100
}
}
],
"eventtrackers": [
{
"event": 1,
"methods": [
1
]
}
],
"ext": {
"style_id": 106354,
"style_height": 240,
"style_width": 320
}
}
Example OpenRTB response
Note that the values in this response are not intended to match the corresponding request above.
⋮
adm_native {
ver: "1.0"
assets {
id: 1
required: false
title {
text: "Example Title"
}
}
assets {
id: 2
required: false
data {
value: "E-VEHICLES | URBAN STYLE | SMART DESIGN | COOL TECHNOLOGY"
}
}
assets {
id: 3
required: false
data {
value: "Read More"
}
}
assets {
id: 4
required: false
data {
value: "Plugin Magazine"
}
}
assets {
id: 5
required: false
img {
url: "https://www.example.com/image.jpg?w=1200&h=627&fit=crop&crop=faces&fm=jpg"
w: 1200
h: 627
}
}
link {
url: "https://r1.example.com/r/u1dhfh3cow00/b1_googleadx/830/41972/?_b_ctrl=1"
}
imptrackers: "https://b1.example.com/?enc=PZ4WSCOOHY&price=%%WINNING_PRICE%%&rzuid=9ab9-9727"
imptrackers: "https://b2.example.com/spp.pl?a=1000157933821"
imptrackers: "https://b3.example.com/usersync/rtbimp/"
}