diff --git a/_data/sidebar.yml b/_data/sidebar.yml
index 4e7b4bf487..81fe93e36a 100644
--- a/_data/sidebar.yml
+++ b/_data/sidebar.yml
@@ -574,7 +574,7 @@
- sbSecId: 1
title: Native Ads
- link: /dev-docs/show-native-ads.html
+ link: /prebid/native-implementation.html
isHeader: 0
isSectionHeader: 0
sectionTitle:
@@ -1056,7 +1056,7 @@
subgroup: 0
- sbSecId: 3
- title: 'Guide to Ad Manager'
+ title: 'Guide to Prebid in Ad Manager'
link: /adops/step-by-step.html
isHeader: 0
isSectionHeader: 0
@@ -1064,7 +1064,7 @@
subgroup: 0
- sbSecId: 3
- title: 'Setting up for AMP'
+ title: 'Setting up for AMP in GAM'
link: /adops/setting-up-prebid-for-amp-in-dfp.html
isHeader: 0
isSectionHeader: 0
@@ -1072,7 +1072,7 @@
subgroup: 0
- sbSecId: 3
- title: 'Setting up Multi-Format'
+ title: 'Setting up Multi-Format in GAM'
link: /adops/setting-up-prebid-multi-format-in-dfp.html
isHeader: 0
isSectionHeader: 0
@@ -1080,15 +1080,15 @@
subgroup: 0
- sbSecId: 3
- title: 'Setting up Native (Alpha)'
- link: /adops/setting-up-prebid-native-in-dfp.html
+ title: 'Setting up Native in GAM'
+ link: /adops/gam-native.html
isHeader: 0
isSectionHeader: 0
sectionTitle:
subgroup: 0
- sbSecId: 3
- title: 'Setting up Video'
+ title: 'Setting up Video in GAM'
link: /adops/setting-up-prebid-video-in-dfp.html
isHeader: 0
isSectionHeader: 0
@@ -1096,7 +1096,7 @@
subgroup: 0
- sbSecId: 3
- title: 'Setting up Long-Form Video'
+ title: 'Setting up Long-Form Video in GAM'
link: /adops/setting-up-prebid-ott-video-in-gam.html
isHeader: 0
isSectionHeader: 0
diff --git a/_includes/dev-docs/native-assets.md b/_includes/dev-docs/native-assets.md
new file mode 100644
index 0000000000..912b0e62ee
--- /dev/null
+++ b/_includes/dev-docs/native-assets.md
@@ -0,0 +1,21 @@
+{: .table .table-bordered .table-striped }
+| Asset Code | Description | Macro |
+|---------------+--------------------------------------------------------------------------------------|-----------------------|
+| `title` | The title of the ad, usually a call to action or a brand name. | `##hb_native_title##` |
+| `body` | Text of the ad copy. | `##hb_native_body##` |
+| `body2` | Additional Text of the ad copy. | `##hb_native_body2##` |
+| `sponsoredBy` | The name of the brand associated with the ad. | `##hb_native_brand##` |
+| `icon` | The brand icon that will appear with the ad. | `##hb_native_icon##` |
+| `image` | A picture that is associated with the brand, or grabs the user's attention. | `##hb_native_image##` |
+| `clickUrl` | Where the user will end up if they click the ad. | `##hb_native_linkurl##` |
+| `displayUrl` | Text that can be displayed instead of the raw click URL. e.g, "Example.com/Specials" | `##hb_native_displayUrl##`|
+| `privacyLink` | Link to the Privacy Policy of the Buyer, e.g. http://example.com/privacy | `##hb_native_privacy##` |
+| `privacyIcon` | Icon to display for the privacy link, e.g. http://example.com/privacy_icon.png | `##hb_native_privicon##` |
+| `cta` | *Call to Action* text, e.g., "Click here for more information". | `##hb_native_cta##` |
+| `rating` | Rating information, e.g., "4" out of 5. | `##hb_native_rating##` |
+| `downloads` | The total downloads of the advertised application/product | `##hb_native_downloads##` |
+| `likes` | The total number of individuals who like the advertised application/product | `##hb_native_likes##` |
+| `price` | The non-sale price of the advertised application/product | `##hb_native_price##` |
+| `salePrice` | The sale price of the advertised application/product | `##hb_native_saleprice##` |
+| `address` | Address of the Buyer/Store. e.g, "123 Main Street, Anywhere USA" | `##hb_native_address##` |
+| `phone` | Phone Number of the Buyer/Store. e.g, "(123) 456-7890" | `##hb_native_phone##` |
diff --git a/_includes/dev-docs/native-image-asset-sizes.md b/_includes/dev-docs/native-image-asset-sizes.md
index 9c8ad557af..269818b3ef 100644
--- a/_includes/dev-docs/native-image-asset-sizes.md
+++ b/_includes/dev-docs/native-image-asset-sizes.md
@@ -34,6 +34,3 @@ mediaTypes: {
}
{% endhighlight %}
-
-{: .alert.alert-success :}
-NOTE: If you're using `aspect_ratios` in a native request sent to Prebid Server, the `min_width` and `min_height` fields become required instead of optional. If these fields are not included, that native request will be rejected.
\ No newline at end of file
diff --git a/adops/before-you-start.md b/adops/before-you-start.md
index 34957c3e6a..d8e15305a8 100644
--- a/adops/before-you-start.md
+++ b/adops/before-you-start.md
@@ -14,7 +14,7 @@ sbUUID: 3.2
Prebid products are designed to integrate with the ad ops line item configuration on the publisher's selected ad server. Whether using Prebid.js, Prebid Server or Prebid Mobile, bid targeting parameters are passed to the ad server. The ad server then attempts to match the targeting parameters to a preset line item. If successful, that line item is compared to other line items and if the Prebid bid wins the auction, the creative is returned to the web page or app for display.
{% capture importantNote %}
-This page assumes you have read [Getting Started with Prebid.js]({{site.baseurl}}/overview/getting-started.html), though it applies to Prebid SDK and Server as well.
+This page assumes you have read [Getting Started with Prebid.js](/overview/getting-started.html), though it applies to Prebid SDK and Server as well.
{% endcapture %}
{% include alerts/alert_important.html content=importantNote %}
@@ -29,14 +29,14 @@ The table below lists ad servers supported by Prebid and provides links to step
{: .table .table-bordered .table-striped }
| Server | Page |
|--------------+-----------------------------------------------------------------------------------------------------------------------------------------|
-| **Google Ad Manager** | [Step by step guide to Google Ad Manager setup]({{site.baseurl}}/adops/step-by-step.html) |
-| | [Send all bids to the ad server]({{site.baseurl}}/adops/send-all-bids-adops.html) |
-| | [Setting up Prebid for AMP in Google Ad Manager]({{site.baseurl}}/adops/setting-up-prebid-for-amp-in-dfp.html) |
-| | [Setting up Prebid Video in Google Ad Manager]({{site.baseurl}}/adops/setting-up-prebid-video-in-dfp.html) |
-| | [Setting up Prebid Native in Google Ad Manager]({{site.baseurl}}/adops/setting-up-prebid-native-in-dfp.html) |
-| **AppNexus** | [Setting up Prebid with the AppNexus Publisher Ad Server]({{site.baseurl}}/adops/setting-up-prebid-with-the-appnexus-ad-server.html) |
-| **Smart Ad Server** | [Setting up Prebid.js with Smart Ad Server]({{site.baseurl}}/adops/setting-up-prebidjs-with-Smart-Ad-Server.html) |
-| **FreeWheel** | [FreeWheel Guide for Premium Long-Form Video]({{site.baseurl}}/adops/setting-up-prebid-video-in-freewheel.html) |
+| **Google Ad Manager** | [Step by step guide to Google Ad Manager setup](/adops/step-by-step.html) |
+| | [Send all bids to the ad server](/adops/send-all-bids-adops.html) |
+| | [Setting up Prebid for AMP in Google Ad Manager](/adops/setting-up-prebid-for-amp-in-dfp.html) |
+| | [Setting up Prebid Video in Google Ad Manager](/adops/setting-up-prebid-video-in-dfp.html) |
+| | [Setting up Prebid Native in Google Ad Manager](/adops/gam-native.html) |
+| **AppNexus** | [Setting up Prebid with the AppNexus Publisher Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) |
+| **Smart Ad Server** | [Setting up Prebid.js with Smart Ad Server](/adops/setting-up-prebidjs-with-Smart-Ad-Server.html) |
+| **FreeWheel** | [FreeWheel Guide for Premium Long-Form Video](/adops/setting-up-prebid-video-in-freewheel.html) |
## Decide on price bucket granularity
@@ -108,6 +108,6 @@ Implementing header bidding requires much more collaboration with your dev team
## Related Topics
-- [Getting Started with Prebid.js]({{site.baseurl}}/overview/getting-started.html): How Prebid.js works at a high level.
-- [What is Prebid?]({{site.baseurl}}/overview/intro.html): Overview and history of header bidding and Prebid.js.
-+ [Docs by Format]({{site.baseurl}}/dev-docs/docs-by-format.html): Engineering and ad ops docs arranged by ad format (video, native, etc.).
+- [Getting Started with Prebid.js](/overview/getting-started.html): How Prebid.js works at a high level.
+- [What is Prebid?](/overview/intro.html): Overview and history of header bidding and Prebid.js.
++ [Docs by Format](/dev-docs/docs-by-format.html): Engineering and ad ops docs arranged by ad format (video, native, etc.).
diff --git a/adops/gam-native.md b/adops/gam-native.md
new file mode 100644
index 0000000000..dbd2beb1b5
--- /dev/null
+++ b/adops/gam-native.md
@@ -0,0 +1,221 @@
+---
+layout: page_v2
+title: Setting up Prebid Native in Google Ad Manager
+head_title: Setting up Prebid Native in Google Ad Manager
+description: Setting up Prebid Native in Google Ad Manager
+sidebarType: 3
+---
+
+# Setting up Prebid Native in Google Ad Manager
+{: .no_toc}
+
+This page describes how to set up native creatives in Google Ad Manager for use with Prebid.js.
+
+For more information about Google Ad Manager native ad setup, see the [Google Ad Manager native ads documentation](https://support.google.com/admanager/answer/6366845).
+
+{% capture version2 %}
+This document replaces the [original documentation](/adops/setting-up-prebid-native-in-dfp.html) that described how to set up Prebid.js native for GAM. That documentation is still valid, but the approach described here is better in every way, so we recommend that all new and revised implementations follow this approach. Here are the key differences between the original approach and the preferred approach described in this document:
+{::nomarkdown}
+
+- The macro format is different: instead of using AdServer-defined macros, Prebid.js now has its own macro format.
+
- Targeting variables aren't sent from Prebid.js to the AdServer. Rather, they're queried at display time.
+
- A different rendering library is used.
+
+{:/}
+{% endcapture %}
+{% include alerts/alert_important.html content=version2 %}
+
+* TOC
+{:toc}
+
+## 1. Create a native ad
+
+From Google Ad Manager, select **Delivery > Native**. Click **Create Native Ad**.
+
+![native delivery](/assets/images/ad-ops/dfp-native/create_prebid_native.png){: .pb-md-img :}
+
+Select the **HTML & CSS editor** option.
+
+![HTML editor option](/assets/images/ad-ops/dfp-native/prebid_native_html_option.png){: .pb-md-img :}
+
+## 2. Define settings for native format
+
+For **Ad size** you can select a specific size for the ad unit or specify the "fluid" size. In this case we'll go with **Fluid**.
+
+Under **Custom format**, select **New format**. (If you’ve already created an ad unit with the format you want, you can select Existing format and select the format to apply to this ad unit.)
+
+Every format needs at least one "variable". In this example we've added **title** as a variable. Don't worry, you can add more later. Or not. Either way, GAM requires at least one variable in order to move on to the next step.
+
+![native adunit settings](/assets/images/ad-ops/dfp-native/gam-native-format.png){: .pb-md-img :}
+
+When done, click **Continue**.
+
+## 3. Style your native ad
+
+Next, add the HTML and CSS to define your native ad template. To allow for trackers, titles, images, and other assets within a Prebid native creative template, you’ll need to include a CDN-hosted script in the HTML.
+
+![native ad styling](/assets/images/ad-ops/dfp-native/gam-native-template.png){: .pb-xlg-img :}
+
+{: .alert.alert-warning :}
+Any link that needs to fire a click tracker must include `class='pb-click'`.
+
+If this creative is served, it will fire impression trackers on load. Clicking the link will fire the click tracker and the link will work as normal, in this case going to the `hb_native_linkurl` destination.
+
+The creative template HTML will depend on which of the three scenarios you're implementing, as described in the [Native Implementation Guide](/prebid/native-implementation.html). You can choose to manage the native template:
+
+- in GAM ([section 3.1](/adops/gam-native.html#31-managing-the-native-template-in-gam) below)
+- in the Prebid.js AdUnit ([section 3.2](/adops/gam-native.html#32-managing-the-native-template-outside-of-gam) below)
+- in a separate JavaScript file ([section 3.2](/adops/gam-native.html#32-managing-the-native-template-outside-of-gam) below)
+
+### 3.1. Managing the native template in GAM
+
+There are three key aspects of the native template:
+
+1. Build the creative with special Prebid.js macros, e.g. `##hb_native_assetname##`. See the appendix for an exhaustive list of assets and macros. Note that macros can be placed in the body (HTML) and/or head (CSS) of the native creative.
+2. Load the Prebid.js native rendering code. You may utilize the jsdelivr version of native-render.js or host your own copy. If you use the version hosted on jsdelivr, make sure to declare jsdelivr as an ad technology provider in GAM. Admin → EU User Consent → Declare ad technology providers
+3. Invoke the Prebid.js native rendering function with an object containing the following attributes:
+ - adid - used to identify which Prebid.js creative holds the appropriate native assets
+ - pubUrl - the URL of the page, which is needed for the HTML postmessage call
+ - requestAllAssets - tells the renderer to get all the native assets from Prebid.js.
+
+Example creative HTML:
+```
+
+
+
+```
+
+{: .alert.alert-warning :}
+When using `Send All Bids` you should update `pbNativeTagData.adId = "%%PATTERN:hb_adid_biddercode%%";` for each bidder’s creative
+
+Example CSS:
+```
+.sponsored-post {
+ background-color: #fffdeb;
+ font-family: sans-serif;
+ padding: 10px 20px 10px 20px;
+}
+
+.content {
+ overflow: hidden;
+}
+
+.thumbnail {
+ width: 120px;
+ height: 100px;
+ float: left;
+ margin: 0 20px 10px 0;
+ background-image: url(##native_image##);
+ background-size: cover;
+}
+
+h1 {
+ font-size: 18px;
+ margin: 0;
+}
+
+a {
+ color: #0086b3;
+ text-decoration: none;
+}
+
+p {
+ font-size: 16px;
+ color: #444;
+ margin: 10px 0 10px 0;
+}
+
+.attribution {
+ color: #fff;
+ font-size: 9px;
+ font-weight: bold;
+ display: inline-block;
+ letter-spacing: 2px;
+ background-color: #ffd724;
+ border-radius: 2px;
+ padding: 4px;
+}
+```
+
+### 3.2. Managing the native template outside of GAM
+
+The GAM creative is identical whether the template is defined in the AdUnit or the external render JavaScript. There are two key aspects of the native creative in this scenario:
+
+1. Load the Prebid.js native rendering code. You may utilize the jsdelivr version of native-render.js or host your own copy. If you use the version hosted on jsdelivr, make sure to declare jsdelivr as an ad technology provider in GAM. Admin → EU User Consent → Declare ad technology providers
+2. Invoke the Prebid.js native rendering function with an object containing the following attributes:
+ - adid - used to identify which Prebid.js creative holds the appropriate native assets
+ - pubUrl - the URL of the page, which is needed for the HTML postmessage call
+ - requestAllAssets - tells the renderer to get all the native assets from Prebid.js.
+
+Example creative HTML:
+```
+
+
+```
+
+{: .alert.alert-warning :}
+When using `Send All Bids` you should update `pbNativeTagData.adId = "%%PATTERN:hb_adid_biddercode%%";` for each bidder’s creative
+
+The example CSS in section 3.1 applies here as well.
+
+
+## 4. Create new native order and line items
+
+1. Create a new order as usual.
+2. Create a new line item as usual, selecting Ad type "Display".
+3. Add your native format in the "Expected creatives" section.
+
+
+![create a native order and line item](/assets/images/ad-ops/dfp-native/gam-line-item.png){: .pb-md-img :}
+
+{:start="4"}
+4. For targeting, set inventory targeting and key-value targeting on `hb_pb` or `hb_pb_BIDDER` corresponding to the line item’s CPM.
+5. Save the line item
+
+
+## 5. Create a new native creative
+
+1. After saving the line item, click on **Creatives** and then **New creative**.
+
+![create a new native creative](/assets/images/ad-ops/dfp-native/gam-new-creative.png){: .pb-md-img :}
+
+{:start="2"}
+2. On the creative type screen choose **Native Format** and select the format you created above.
+
+![Native Format](/assets/images/ad-ops/dfp-native/gam-creative-type.png){: .pb-md-img :}
+
+{:start="3"}
+3. Under **Settings**, enter a Name for your creative. Enter any value into the **Click-through URL** field; this value will be overwritten by the native asset values. Also, if you operate in Europe and are using the jsdelivr-hosted native-render.js, make sure you set jsdelivr as your ad technology provider.
+
+![Native Creative](/assets/images/ad-ops/dfp-native/gam-new-creative-part2.png){: .pb-md-img :}
+
+{:start="4"}
+4. Click **Save**.
+5. Review the order, line item, and creative.
+6. Approve the order as needed.
+
+## Further Reading
+
+- [Prebid Native Format](/formats/native.html)
+- [Prebid Native Implementation Guide](/prebid/native-implementation.html)
diff --git a/adops/setting-up-prebid-multi-format-in-dfp.md b/adops/setting-up-prebid-multi-format-in-dfp.md
index ecaf4731ca..5562c1b0a8 100644
--- a/adops/setting-up-prebid-multi-format-in-dfp.md
+++ b/adops/setting-up-prebid-multi-format-in-dfp.md
@@ -81,6 +81,5 @@ Follow the instructions for creating line items, creatives, custom native format
-[bannerAdSetup]: {{site.baseurl}}/adops/send-all-bids-adops.html
-[nativeAdSetup]: {{site.baseurl}}/adops/setting-up-prebid-native-in-dfp.html
-[createCustomNativeFormat]: {{site.baseurl}}/adops/setting-up-prebid-native-in-dfp.html#create-a-custom-native-ad-format
+[bannerAdSetup]: /adops/send-all-bids-adops.html
+[nativeAdSetup]: /adops/gam-native.html
diff --git a/adops/setting-up-prebid-native-in-dfp.md b/adops/setting-up-prebid-native-in-dfp.md
index 9e5301cefd..6a04ee6dff 100644
--- a/adops/setting-up-prebid-native-in-dfp.md
+++ b/adops/setting-up-prebid-native-in-dfp.md
@@ -15,6 +15,12 @@ sidebarType: 3
# Setting up Prebid Native in Google Ad Manager (Alpha)
{: .no_toc}
+{% capture version1 %}
+The procedures in this document still work, but we strongly recommend
+using the improved [Guide for Setting up Prebid Native in GAM](/adops/gam-native.html).
+{% endcapture %}
+{% include alerts/alert_warning.html content=version1 %}
+
This page describes how to set up native creatives in Google Ad Manager for use with Prebid.js.
For more information about Google Ad Manager native ad setup, see the [Google Ad Manager native ads documentation](https://support.google.com/admanager/answer/6366845).
diff --git a/assets/images/ad-ops/dfp-native/gam-creative-type.png b/assets/images/ad-ops/dfp-native/gam-creative-type.png
new file mode 100644
index 0000000000..bd35cf0c0d
Binary files /dev/null and b/assets/images/ad-ops/dfp-native/gam-creative-type.png differ
diff --git a/assets/images/ad-ops/dfp-native/gam-line-item.png b/assets/images/ad-ops/dfp-native/gam-line-item.png
new file mode 100644
index 0000000000..43689e2e85
Binary files /dev/null and b/assets/images/ad-ops/dfp-native/gam-line-item.png differ
diff --git a/assets/images/ad-ops/dfp-native/gam-native-format.png b/assets/images/ad-ops/dfp-native/gam-native-format.png
new file mode 100644
index 0000000000..03981dcfd6
Binary files /dev/null and b/assets/images/ad-ops/dfp-native/gam-native-format.png differ
diff --git a/assets/images/ad-ops/dfp-native/gam-native-template.png b/assets/images/ad-ops/dfp-native/gam-native-template.png
new file mode 100644
index 0000000000..562b43c367
Binary files /dev/null and b/assets/images/ad-ops/dfp-native/gam-native-template.png differ
diff --git a/assets/images/ad-ops/dfp-native/gam-new-creative-part2.png b/assets/images/ad-ops/dfp-native/gam-new-creative-part2.png
new file mode 100644
index 0000000000..f495875a23
Binary files /dev/null and b/assets/images/ad-ops/dfp-native/gam-new-creative-part2.png differ
diff --git a/assets/images/ad-ops/dfp-native/gam-new-creative.png b/assets/images/ad-ops/dfp-native/gam-new-creative.png
new file mode 100644
index 0000000000..14d1561e81
Binary files /dev/null and b/assets/images/ad-ops/dfp-native/gam-new-creative.png differ
diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md
index 4d63511e46..260a7e962c 100644
--- a/dev-docs/publisher-api-reference.md
+++ b/dev-docs/publisher-api-reference.md
@@ -2119,6 +2119,7 @@ To accomplish this, Prebid does the following:
* New targeting replaces original targeting before targeting is flattened.
The targeting key names and the associated prefix value filtered by `allowTargetingKeys`:
+
{: .table .table-bordered .table-striped }
| Name | Value |
|------------+------------|
diff --git a/dev-docs/show-native-ads.md b/dev-docs/show-native-ads.md
index 4863f9cfc8..8e47637677 100644
--- a/dev-docs/show-native-ads.md
+++ b/dev-docs/show-native-ads.md
@@ -4,16 +4,19 @@ title: Show Native Ads with Prebid.js
description: Show Native Ads with Prebid.js
pid: 0
is_top_nav: yeah
-top_nav_section: dev_docs
-nav_section: prebid-native
sidebarType: 1
---
-
-
# Show Native Ads with Prebid.js
{: .no_toc }
+{% capture change-notice %}
+The procedures in this document still work, but we strongly recommend
+using the [improved Prebid.js native ad](/prebid/native-implementation.html) support.
+{% endcapture %}
+
+{% include alerts/alert_warning.html content=change-notice %}
+
In this tutorial, we'll set up Prebid.js to show native ads.
We'll use the [AppNexus adapter]({{site.github.url}}/dev-docs/bidders.html#appnexus) since that adapter supports native ads, but the concepts and setup will be largely the same for any bidder adapter that supports the `"native"` media type.
@@ -84,28 +87,7 @@ The native object (shown [below](#native-object)) contains the following keys th
{: .alert.alert-danger :}
Specific bidders may not support all of the fields listed below or may return differing responses for the assets that are requested.
-{: .table .table-bordered .table-striped }
-| Key | Description | Ad Server Key Value |
-|---------------+--------------------------------------------------------------------------------------|-----------------------|
-| `title` | The title of the ad, usually a call to action or a brand name. | `hb_native_title` |
-| `body` | Text of the ad copy. | `hb_native_body` |
-| `body2` | Additional Text of the ad copy. | `hb_native_body2` |
-| `sponsoredBy` | The name of the brand associated with the ad. | `hb_native_brand` |
-| `icon` | The brand icon that will appear with the ad. | `hb_native_icon` |
-| `image` | A picture that is associated with the brand, or grabs the user's attention. | `hb_native_image` |
-| `clickUrl` | Where the user will end up if they click the ad. | `hb_native_linkurl` |
-| `displayUrl` | Text that can be displayed instead of the raw click URL. e.g, "Example.com/Specials" | `hb_native_displayUrl`|
-| `privacyLink` | Link to the Privacy Policy of the Buyer, e.g. http://example.com/privacy | `hb_native_privacy` |
-| `privacyIcon` | Icon to display for the privacy link, e.g. http://example.com/privacy_icon.png | `hb_native_privicon` |
-| `cta` | *Call to Action* text, e.g., "Click here for more information". | `hb_native_cta` |
-| `rating` | Rating information, e.g., "4" out of 5. | `hb_native_rating` |
-| `downloads` | The total downloads of the advertised application/product | `hb_native_downloads` |
-| `likes` | The total number of individuals who like the advertised application/product | `hb_native_likes` |
-| `price` | The non-sale price of the advertised application/product | `hb_native_price` |
-| `salePrice` | The sale price of the advertised application/product | `hb_native_saleprice` |
-| `address` | Address of the Buyer/Store. e.g, "123 Main Street, Anywhere USA" | `hb_native_address` |
-| `phone` | Phone Number of the Buyer/Store. e.g, "(123) 456-7890" | `hb_native_phone` |
-
+{% include dev-docs/native-assets.md %}
Each key's value is an object with several fields. Most important is the `required` field, which says whether that asset should be filled in by the bid response. Specifically, bids that do not have all of the native assets marked as required will be dropped from the auction and will not be sent to the ad server.
diff --git a/formats/native.md b/formats/native.md
index f6a638a2c1..aecf26f0a4 100644
--- a/formats/native.md
+++ b/formats/native.md
@@ -16,11 +16,11 @@ Native ads are supported by Prebid.js for mobile web. Prebid Server support is c
### Adops
-- [Setting up Prebid Native in Google Ad Manager](/adops/setting-up-prebid-native-in-dfp.html)
+- [Setting up Prebid Native in Google Ad Manager](/adops/gam-native.html)
### Developers
-- [Setting up Prebid Native](/dev-docs/show-native-ads.html)
+- [Prebid Native Implementation](/prebid/native-implementation.html)
### Prebid.js bid adapters that support the Native format
diff --git a/prebid/native-implementation.md b/prebid/native-implementation.md
new file mode 100644
index 0000000000..71194f7412
--- /dev/null
+++ b/prebid/native-implementation.md
@@ -0,0 +1,448 @@
+---
+
+layout: page_v2
+title: Prebid.js Native Implementation Guide
+description: Prebid.js Native Implementation Guide
+sidebarType: 1
+
+---
+
+# Prebid.js Native Implementation Guide
+{: .no_toc}
+
+{% capture version2 %}
+This document replaces the [original native documentation](/dev-docs/show-native-ads.html) that described how Prebid.js supported native creatives. That documentation is still valid, but the approach described here is better in every way, so we recommend that all new and revised implementations should follow this approach. Here are the key differences between the original approach and the new, preferred approach:
+{::nomarkdown}
+
+- The macro format is different: instead of using AdServer-defined macros, Prebid.js now has its own macro format.
+
- Targeting variables aren't sent from Prebid.js to the AdServer. Rather, they're queried at display time.
+
- A different rendering library is used.
+
+{:/}
+{% endcapture %}
+{% include alerts/alert_important.html content=version2 %}
+
+* TOC
+{:toc}
+
+
+## Overview
+
+A native ad is made up of assets such as a title, description, and image URL that are plugged into a publisher-defined HTML template. The template includes placeholder macros for those assets, and may be styled to match the form of the surrounding page.
+
+At a high level, Prebid.js’ support for native ads works like this:
+
+- The publisher establishes one or more native rendering templates and sets up the ad server.
+- The publisher defines which AdUnits are eligible for native ads and the bidders participating in the auction.
+- Prebid.js requests native demand from bidder adapters that support the “native” mediatype.
+- Native bids are stored in the Prebid.js memory space.
+- The call to the ad server is made as usual.
+- If the native ad wins, it’s displayed and any trackers are fired.
+
+{: .alert.alert-info :}
+To determine whether a bidder can supply native demand, check the [bidder parameter page](/dev-docs/bidders.html).
+
+## 1. Set up your ad server ad slot and HTML div
+
+Create your ad server in-page implementation as usual. See [Setting Up Prebid Native in GAM](/adops/gam-native.html) for instructions for how to do this with Google Ad Manager.
+
+## 2. Determine where the native template will be defined
+
+There are three options for defining the native template:
+
+- If you want to manage your creative within the ad server (e.g. Google Ad Manager), follow the instructions for [AdServer-Defined Template](#41-implementing-adserver-defined-template).
+- If you’d prefer to manage your creative within the Prebid.js AdUnit, follow the instructions for [AdUnit-Defined Template](#42-implementing-adunit-defined-template).
+- If you’d prefer to manage your creative from a separate piece of JavaScript, follow the instructions for the [Custom Renderer](#43-implementing-the-custom-renderer-scenario).
+
+This table summarizes how the 3 approaches work:
+
+**Table 1: Native Implementation Approaches**
+
+{: .table .table-bordered .table-striped }
+| Component | AdServer-Defined Creative Scenario | AdUnit-Defined Creative Scenario | Custom Renderer Scenario |
+| --- | --- |--- |--- |
+| Prebid.js | mediaTypes.native.sendTargetingKeys:false | sendTargetingKeys:false and mediaTypes.native.adTemplate contains ##macros## | sendTargetingKeys:false and mediaTypes.native.rendererUrl |
+| Ad Server Key Value Pairs | hb_adid | hb_adid | hb_adid |
+| Ad Server | Native template loads native-render.js and calls renderNativeAd(). Uses Prebid ##macro## format. | Native creative loads native-render.js and calls renderNativeAd() with requestAllAssets: true | Native creative loads native-render.js and calls renderNativeAd(), with requestAllAssets:true |
+| Prebid Universal Creative | renderNativeAd resolves macros in the creative body and CSS. | renderNativeAd resolves ##macros## in adTemplate and CSS, appending the adTemplate to the creative body | renderNativeAd loads javascript from renderUrl, calls the renderAd function, appending the results to the creative body. |
+| Javascript rendering function | n/a | n/a | Receives hash of attributes, responsible for resolving any macro format and returning an HTML block. |
+
+## 3. Prebid.js Native AdUnit Overview
+
+The Prebid.js AdUnit needs to defines a native mediatype object to tell bidders which assets are required. This table defines all attributes that could be included in AdUnit.mediatypes.native. Specific examples of the three different scenarios follow.
+
+**Table 2: Prebid.js AdUnit Native MediaType Options**
+
+{: .table .table-bordered .table-striped }
+| Attribute | Scope | Description | Example | Type |
+| --- | --- | --- | --- | --- |
+| sendTargetingKeys | optional | Defines whether or not to send the hb_native_ASSET targeting keys to the ad server. Defaults to `true` for now, though we recommend setting this to `false` and utilizing one of the ways to define a native template. | `false` | boolean |
+| adTemplate | optional | Used in the ‘AdUnit-Defined Creative Scenario’, this value controls the Native template right in the page. | See [example](#5-implementing-adunit-defined-creative) below. | escaped ES5 string |
+| rendererUrl | optional | Used in the ‘Custom Renderer Scenario’, this points to javascript code that will produce the Native template. | 'https://host/path.js' | string |
+| type | optional | A “type” is like a macro that defines a group of assets. The only value currently supported is ‘image’, which implies the following assets: image, title, sponsoredBy, clickUrl, body, icon, and cta. The first 4 are required attributes. | `image` | string |
+| ASSETCODE. required | optional | Defines whether native bids must include this asset. Defaults to `false`. | `true` | boolean |
+| ASSETCODE. len | optional | For text assets, bidders should pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. | 40 | integer |
+| ASSETCODE. sizes | optional | For image assets, bidders may pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. Format is an array with two elements: [WIDTH, HEIGHT] | `[50, 50]` | array of integers |
+| ASSETCODE. aspect_ratios | optional | For image assets, bidders may pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. Format is an object with the attributes in the rows below. | | object |
+| ASSETCODE. aspect_ratios.min_width | optional | Part of the aspect_ratios object, bidders may pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. | 50 | integer |
+| ASSETCODE. aspect_ratios.min_height | optional | Part of the aspect_ratios object, bidders may pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. | 75 | integer |
+| ASSETCODE. aspect_ratios.ratio_width | optional | Part of the aspect_ratios object, bidders may pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. | 2 | integer |
+| ASSETCODE. aspect_ratios.ratio_height | optional | Part of the aspect_ratios object, bidders may pass this value through to the endpoint. Prebid.js does not enforce the responses and there’s no default. | 3 | integer |
+
+
+**Table 3: Native Assets Recognized by Prebid.js**
+
+{% include dev-docs/native-assets.md %}
+
+{: .alert.alert-warning :}
+Specific bidders may not support all of the fields listed below or may return differing responses for the assets that are requested.
+
+### 3.1. Two ways to define image sizes
+
+{% include dev-docs/native-image-asset-sizes.md %}
+
+## 4. Implementing the Native Template
+
+- If you want to manage your creative within the ad server (e.g. Google Ad Manager), follow the instructions for [AdServer-Defined Creative](#4-implementing-adserver-defined-creative).
+- If you’d prefer to manage your creative within the Prebid.js AdUnit, follow the instructions for [AdUnit-Defined Creative](#5-implementing-adunit-defined-creative)
+- If you’d prefer to manage your creative from a separate piece of JavaScript, follow the instructions for the [Custom Renderer](#6-implementing-the-custom-renderer-scenario).
+
+### 4.1. Implementing AdServer-Defined Template
+
+In this scenario, the body of the native creative template is managed within the ad server and includes special Prebid.js macros.
+
+#### Turn Targeting Keys off in Prebid.js
+
+When the native AdUnit is defined in the page, declare `sendTargetingKeys: false` in the native Object. This will prevent Prebid.js from sending all the native-related ad server targeting variables.
+
+Example Native AdUnit:
+```
+pbjs.addAdUnits({
+ code: slot.code,
+ mediaTypes: {
+ native: {
+ sendTargetingKeys: false,
+ image: {
+ required: true,
+ sizes: [150, 50]
+ },
+ title: {
+ required: true,
+ len: 80
+ },
+ sponsoredBy: {
+ required: true
+ },
+ clickUrl: {
+ required: true
+ },
+ privacyLink: {
+ required: false
+ },
+ body: {
+ required: true
+ },
+ icon: {
+ required: true,
+ sizes: [50, 50]
+ }
+ }
+ },
+ bids: [{
+ ...
+ }]
+});
+```
+
+Here’s an example native AdUnit using the ‘type’ feature, which implies a number of required and optional attributes.
+
+```
+const adUnits = [{
+ code: 'adUnit-code',
+ mediaTypes: {
+ sendTargetingKeys: false,
+ native: {
+ type: 'image'
+ }
+ }
+ bids: [{
+ ...
+ }]
+}];
+```
+#### Native Template in AdServer
+
+There are three key aspects of the native template:
+
+1. Build the creative with special Prebid.js macros, e.g. ##hb_native_assetname##. (See the Native Assets table above for an exhaustive list of assets and macros.) Note that macros can be placed in the body (HTML) and/or head (CSS) of the native creative.
+2. Load the Prebid.js native rendering code. You may utilize the jsdelivr version of native-render.js or host your own copy. If you use the version hosted on jsdelivr, make sure any necessary ad server permissions are established.
+3. Invoke the Prebid.js native rendering function with an object containing the following attributes:
+ 1. adid - used to identify which Prebid.js creative holds the appropriate native assets
+ 2. pubUrl - the URL of the page, which is needed for the HTML postmessage call
+ 3. requestAllAssets - tells the renderer to get all the native assets from Prebid.js rather than having to scan the template to find which specific assets are needed.
+
+Example creative HTML:
+```
+
+
+
+```
+
+{: .alert.alert-warning :}
+When using 'Send All Bids' mode you should update `pbNativeTagData.adId = "%%PATTERN:hb_adid_BIDDERCODE%%";` for each bidder’s creative
+
+Example CSS:
+```
+.sponsored-post {
+ background-color: #fffdeb;
+ font-family: sans-serif;
+ padding: 10px 20px 10px 20px;
+}
+
+.content {
+ overflow: hidden;
+}
+
+.thumbnail {
+ width: 120px;
+ height: 100px;
+ float: left;
+ margin: 0 20px 10px 0;
+ background-image: url(##native_image##);
+ background-size: cover;
+}
+
+h1 {
+ font-size: 18px;
+ margin: 0;
+}
+
+a {
+ color: #0086b3;
+ text-decoration: none;
+}
+
+p {
+ font-size: 16px;
+ color: #444;
+ margin: 10px 0 10px 0;
+}
+
+.attribution {
+ color: #fff;
+ font-size: 9px;
+ font-weight: bold;
+ display: inline-block;
+ letter-spacing: 2px;
+ background-color: #ffd724;
+ border-radius: 2px;
+ padding: 4px;
+}
+```
+### 4.2 Implementing AdUnit-Defined Template
+
+In this scenario, the body of the native creative template is managed within the Prebid.js AdUnit and includes special Prebid.js macros.
+
+#### Prebid.js AdUnit Setup
+
+When the Native AdUnit is defined in the page:
+
+- Declare `sendTargetingKeys: false` in the native Object. This will prevent Prebid.js from sending all the native-related ad server targeting variables.
+- Define the adTemplate as an escaped ES5 string using Prebid.js ##macros##. (See the appendix for an exhaustive list of assets and macros.) Note that this approach only affects the HTML body. Any CSS definitions need to be defined in the body of the template or in the AdServer.
+
+Example AdUnit:
+```
+var adUnits = [{
+ code: 'native-div',
+ mediaTypes: {
+ native: {
+ sendTargetingKeys: false,
+ adTemplate: "