Skip to content

Commit

Permalink
Add native aspect ratio info to AN adapter docs (#543)
Browse files Browse the repository at this point in the history 
* Add native aspect ratios to AppNexus adapter docs

Also did some general cleanup and formatting while I was in there.

* Update field defs a bit; add OpenRTB native link

* Remove OpenRTB note based on feedback

* Add banner, video, and native sections

* WIP native updates across several pages

* Tweak language in AN bidder doc links

* Edit down to a single native example; s/Ast//g

* Update native example code; s/Ast//g

* Show `mediaTypes.native.image.sizes` in examples

In addition to updating the basic examples to use sizes for images and
icons, we add a section to both the API reference and the 'Show Native
Ads' page that lists both ways to define sizes for image-like assets.

Since the content is the same, it's in a shared file sourced using the
Liquid `include` keyword.

* Fix code formatting issue with included file

* `adUnit.sizes` is ignored on native ad units

* Remove `adUnit.sizes` since banner sizes are used

* Remove redundant `adUnit.sizes` from native ad

* Use correct syntax for native "image-type" ad
  • Loading branch information
@rmloveland
rmloveland authored and Rich Loveland committed Feb 14, 2018
1 parent 4dec78a commit b2a2ce2
Show file tree
Hide file tree
Showing 4 changed files with 149 additions and 63 deletions.
35 changes: 35 additions & 0 deletions _includes/dev-docs/native-image-asset-sizes.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
There are two methods for defining sizes for image-like assets (`image` and `icon`). Both are shown below, but the first example (using `sizes`) is more widely supported by demand partners.

Using `mediaTypes.native.image.sizes` (or `mediaTypes.native.icon.sizes` for icons):

{% highlight js %}

mediaTypes: {
native: {
image: {
required: true,
sizes: [150, 50]
}
}
}

{% endhighlight %}

Using `mediaTypes.native.image.aspect_ratios` (or `mediaTypes.native.icon.aspect_ratios` for icons):

{% highlight js %}

mediaTypes: {
native: {
image: {
required: true,
aspect_ratios: [{
min_width: 300, /* Optional */
ratio_width: 2, /* Required */
ratio_height: 3, /* Required */
}]
}
}
}

{% endhighlight %}
63 changes: 52 additions & 11 deletions dev-docs/bidders/appnexus.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,19 +10,31 @@ hide: true
prebid_1_0_supported : true
---

### bid params
**Table of Contents**

- [Bid params](#appnexus-bid-params)
- [Support for publisher-defined keys](#appnexus-pub-keys)
- [Banner Ads](#appnexus-Banner)
- [Video Ads](#appnexus-Video)
- [Native Ads](#appnexus-Native)

<a name="appnexus-bid-params" />

### Bid params

{: .table .table-bordered .table-striped }
| Name | Scope | Description | Example |
|----------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------|
| `placementId` | required | The placement ID from AppNexus. You may identify a placement using the `invCode` and `member` instead of a placement ID. | `"234234"` |
| "arbitraryKey" | optional | This key can be *any publisher-defined string*. The value (also a string) maps to a querystring segment for enhanced buy-side targeting. Multiple key-value pairs can be added. See example below. | `'genre': 'rock'` |
| `invCode` | optional | The inventory code from AppNexus. Must be used with `member`. | `"abc123"` |
| `member` | optional | The member ID from AppNexus. Must be used with `invCode`. | `"12345"` |
| `reserve` | optional | Sets a floor price for the bid that is returned. | `0.90` |
| Name | Scope | Description | Example |
|------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------|
| `placementId` | required | The placement ID from AppNexus. You may identify a placement using the `invCode` and `member` instead of a placement ID. | `"234234"` |
| `"arbitraryKey"` | optional | This key can be *any publisher-defined string*. The value (also a string) maps to a querystring segment for enhanced buy-side targeting. Multiple key-value pairs can be added as shown [below](#appnexus-pub-keys). | `'genre': 'rock'` |
| `invCode` | optional | The inventory code from AppNexus. Must be used with `member`. | `"abc123"` |
| `member` | optional | The member ID from AppNexus. Must be used with `invCode`. | `"12345"` |
| `reserve` | optional | Sets a floor price for the bid that is returned. | `0.90` |

<a name="appnexus-pub-keys" />

#### Support for publisher-defined keys

{: .alert.alert-info :}
**Support for Publisher-Defined Keys**
To pass in a publisher-defined key whose value maps to a querystring segment for buy-side targeting, set up your `params` object as shown below. For more information, see the [query string targeting documentation](https://wiki.appnexus.com/x/7oCzAQ) (login required).

{% highlight js %}
Expand All @@ -43,4 +55,33 @@ var adUnits = [{
}]
{% endhighlight %}

(Sizes set in `adUnit` object will also apply to the AppNexus bid requests.)
{: .alert.alert-info :}
Sizes set in the `adUnit` object will also apply to the AppNexus bid requests.

<a name="appnexus-Banner" />

#### Banner Ads

AppNexus supports the banner features described in:

- [the `adUnit` banner documentation]({{site.baseurl}}/dev-docs/publisher-api-reference.html#adUnit-banner)
- [Getting Started for Developers]({{site.baseurl}}/dev-docs/getting-started.html)

<a name="appnexus-Video" />

#### Video Ads

AppNexus supports the video features described in:

- [the `adUnit` video documentation]({{site.baseurl}}/dev-docs/publisher-api-reference.html#adUnit-video).
- [Show Video Ads]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html)
- [Show Outstream Video Ads]({{site.baseurl}}/dev-docs/show-outstream-video-ads.html)

<a name="appnexus-Native" />

#### Native Ads

AppNexus supports the native features described in:

- [the `adUnit` native documentation]({{site.baseurl}}/dev-docs/publisher-api-reference.html#adUnit-native).
- [Show Native Ads]({{site.baseurl}}/dev-docs/show-native-ads.html)
76 changes: 39 additions & 37 deletions dev-docs/publisher-api-reference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -613,41 +613,44 @@ See the table below for the list of properties in the `mediaTypes` object of the
For an example of a native ad unit, see below. For more detailed instructions, see [Show Native Ads]({{site.baseurl}}/dev-docs/show-native-ads.html).

```javascript
pbjs.addAdUnits({
code: slot.code,
sizes: slot.size,
mediaTypes: {
native: {
image: {
required: true
},
title: {
required: true,
len: 80
},
sponsoredBy: {
required: true
},
clickUrl: {
required: true
},
body: {
required: true
},
icon: {
required: true
pbjs.addAdUnits({
code: slot.code,
mediaTypes: {
native: {
image: {
required: true,
sizes: [150, 50]
},
title: {
required: true,
len: 80
},
sponsoredBy: {
required: true
},
clickUrl: {
required: true
},
body: {
required: true
},
icon: {
required: true,
sizes: [50, 50]
},
},
},
bids: [{
bidder: 'appnexusAst',
params: {
placementId: '9880618'
}
}, ]
}
})
bids: [{
bidder: 'appnexus',
params: {
placementId: '9880618'
}
}, ]
}
})
```

{% include dev-docs/native-image-asset-sizes.md %}

<a name="adUnit-video">

##### Video
Expand All @@ -664,7 +667,7 @@ pbjs.addAdUnits({
},
},
bids: [{
bidder: 'appnexusAst',
bidder: 'appnexus',
params: {
placementId: '9333431',
video: {
Expand Down Expand Up @@ -709,13 +712,12 @@ For an example of a banner ad unit, see below. For more detailed instructions,
```javascript
pbjs.addAdUnits({
code: slot.code,
sizes: slot.size,
mediaTypes: {
banner: {
sizes: [[300, 250], [300, 600]]
},
bids: [{
bidder: 'appnexusAst',
bidder: 'appnexus',
params: {
placementId: '9880618'
}
Expand Down Expand Up @@ -1168,11 +1170,11 @@ To define an alias for a bidder adapter, call this method at runtime:

{% highlight js %}

pbjs.aliasBidder('appnexusAst', 'newAlias');
pbjs.aliasBidder('appnexus', 'newAlias');

{% endhighlight %}

Defining an alias can help avoid user confusion since it's possible to send parameters to the same adapter but in different contexts (e.g, The publisher uses `"appnexusAst"` for demand and also uses `"newAlias"` which is an SSP partner that uses the `"appnexusAst"` adapter to serve their own unique demand).
Defining an alias can help avoid user confusion since it's possible to send parameters to the same adapter but in different contexts (e.g, The publisher uses `"appnexus"` for demand and also uses `"newAlias"` which is an SSP partner that uses the `"appnexus"` adapter to serve their own unique demand).

It's not technically necessary to define an alias, since each copy of an adapter with the same name gets a different ID in the internal bidder registry so Prebid.js can still tell them apart.

Expand Down
38 changes: 23 additions & 15 deletions dev-docs/show-native-ads.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ nav_section: prebid-native

In this tutorial, we'll set up Prebid.js to show native ads.

We'll use the [AppNexus AST adapter]({{site.github.url}}/dev-docs/bidders.html#appnexusAst) 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.
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.

Similarly, we'll use DFP as the ad server, but the concept and implementation should be pretty similar to other ad servers.

Expand Down Expand Up @@ -110,11 +110,11 @@ Each key's value is an object with several fields. Most important is the `requi

pbjs.addAdUnits({
code: slot.code,
sizes: slot.size,
mediaTypes: {
native: {
image: {
required: true
required: true,
sizes: [150, 50]
},
title: {
required: true,
Expand All @@ -130,11 +130,12 @@ pbjs.addAdUnits({
required: true
},
icon: {
required: true
required: true,
sizes: [50, 50]
},
},
bids: [{
bidder: 'appnexusAst',
bidder: 'appnexus',
params: {
placementId: '9880618'
}
Expand Down Expand Up @@ -166,19 +167,26 @@ And the following optional fields:
+ icon
+ cta

A native `image` ad unit can be set up in the manner below:

{% highlight js %}
A native "image-type" ad unit can be set up as shown in the following example.

const adUnits = [{
```javascript
const adUnits = [{
code: 'adUnit-code',
mediaTypes: { native: { type: 'image' } }
bids: [
{ bidder: 'appnexusAst', params: { placementId: '123456' } }
]
}];
mediaTypes: {
native: {
type: 'image'
}
}
bids: [{
bidder: 'appnexus',
params: {
placementId: '123456'
}
}]
}];
```

{% endhighlight %}
{% include dev-docs/native-image-asset-sizes.md %}

### 3. Add your native ad tag to the page body as usual:

Expand Down

0 comments on commit b2a2ce2

Please sign in to comment.