From 024d119e25f629c11ebd84b4874de513f2148186 Mon Sep 17 00:00:00 2001 From: bretg Date: Wed, 4 Nov 2020 18:15:55 -0500 Subject: [PATCH 1/6] pbjs native 2.0 initial commit --- _data/sidebar.yml | 2 +- _includes/dev-docs/native-assets.md | 21 + .../dev-docs/native-image-asset-sizes.md | 3 - dev-docs/publisher-api-reference.md | 1 + dev-docs/show-native-ads.md | 34 +- prebid/native-implementation.md | 438 ++++++++++++++++++ 6 files changed, 469 insertions(+), 30 deletions(-) create mode 100644 _includes/dev-docs/native-assets.md create mode 100644 prebid/native-implementation.md diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 4e7b4bf487..268a826a66 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: 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/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/prebid/native-implementation.md b/prebid/native-implementation.md new file mode 100644 index 0000000000..f112bce528 --- /dev/null +++ b/prebid/native-implementation.md @@ -0,0 +1,438 @@ +--- + +layout: page_v2 +title: About Prebid.js +description: An overview of Prebid.js +sidebarType: 1 + +--- + +# Prebid.js Native Implementation Guide +{: .no_toc} + +* TOC +{:toc} + +{% capture version2 %} +This document replaces the original native documentation 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} +