Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Native phase 2 #2479

Merged
merged 6 commits into from
Jan 13, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 8 additions & 8 deletions _data/sidebar.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -1056,47 +1056,47 @@
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
sectionTitle:
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
sectionTitle:
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
sectionTitle:
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
sectionTitle:
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
Expand Down
21 changes: 21 additions & 0 deletions _includes/dev-docs/native-assets.md
Original file line number Diff line number Diff line change
@@ -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##` |
3 changes: 0 additions & 3 deletions _includes/dev-docs/native-image-asset-sizes.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
24 changes: 12 additions & 12 deletions adops/before-you-start.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 %}
Expand All @@ -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

Expand Down Expand Up @@ -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.).
221 changes: 221 additions & 0 deletions adops/gam-native.md
Original file line number Diff line number Diff line change
@@ -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}
<ul>
<li>The macro format is different: instead of using AdServer-defined macros, Prebid.js now has its own macro format.
<li>Targeting variables aren't sent from Prebid.js to the AdServer. Rather, they're queried at display time.
<li>A different rendering library is used.
</ol>
{:/}
{% 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:
```
<div class="sponsored-post">
<div class="thumbnail" style="background-image: url(##hb_native_image##);"></div>
<div class="content">
<h1><a href="%%CLICK_URL_UNESC%%##hb_native_linkurl##" target="_blank" class="pb-click">##hb_native_title##</a></h1>
<p>##hb_native_body##</p>
<div class="attribution">##hb_native_brand##</div>
</div>
</div>
<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-render.js"></script>
<script>
var pbNativeTagData = {};
pbNativeTagData.pubUrl = "%%PATTERN:url%%";
pbNativeTagData.adId = "%%PATTERN:hb_adid%%";
// if you're using 'Send All Bids' mode, you should use %%PATTERN:hb_adid_BIDDER%%
pbNativeTagData.requestAllAssets = true;
window.pbNativeTag.renderNativeAd(pbNativeTagData);
</script>
```
Comment on lines +82 to +100
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @bretg

When I was looking at this page on the local build, it seems the formatting around this code block isn't working as expected which affected the following code/formatting down to the next major heading. I attached a screenshot for reference:
Screen Shot 2021-01-13 at 8 42 33 AM

Could you take a look?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jsnellbaker - I don't see this mis-formatting on my local Jekyll. And the markdown looks ok. Am going to go ahead and merge, will check the site and fix if needed.


{: .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:
```
<script src="https://cdn.jsdelivr.net/npm/prebid-universal-creative@latest/dist/native-render.js"></script>
<script>
var pbNativeTagData = {};
pbNativeTagData.pubUrl = "%%PATTERN:url%%";
pbNativeTagData.adId = "%%PATTERN:hb_adid%%";
// if you're using 'Send All Bids' mode, you should use %%PATTERN:hb_adid_BIDDER%%
pbNativeTagData.requestAllAssets = true;
window.pbNativeTag.renderNativeAd(pbNativeTagData);
</script>
```

{: .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)
5 changes: 2 additions & 3 deletions adops/setting-up-prebid-multi-format-in-dfp.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,5 @@ Follow the instructions for creating line items, creatives, custom native format

<!-- Reference Links -->

[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
6 changes: 6 additions & 0 deletions adops/setting-up-prebid-native-in-dfp.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/ad-ops/dfp-native/gam-line-item.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading