diff --git a/dev-docs/bidders/equativ.md b/dev-docs/bidders/equativ.md index 4ddca56f68..7d39a7a6f6 100644 --- a/dev-docs/bidders/equativ.md +++ b/dev-docs/bidders/equativ.md @@ -30,7 +30,9 @@ sidebarType: 1 The Equativ bidder adapter requires setup and approval from the Equativ service team. Please reach out to your account manager for more information to start using it. -### Bid params +### Bid Params + +#### Fields {: .table .table-bordered .table-striped } | Name | Scope | Description | Example | Type | @@ -40,16 +42,53 @@ The Equativ bidder adapter requires setup and approval from the Equativ service | `pageId` | optional | The placement page ID. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | | `formatId` | optional | The placement format ID. _See **Bid Parameter Usage** notes below for more information_. | `1234` | `integer` | -#### Bid Parameter Usage +#### Usage Different combinations of parameters are required depending upon which ones you choose to use. -There are two options for passing parameters: +There are two options for passing Equativ-specific bidder parameters: through bidder params, or through ortb2. + +##### Through bidder params Object + +Publishers can specify required and/or optional parameters through the bidder params object hierarchy like this: + +```javascript +var adUnits = [ + { + /// ... mediaType and other stuff here + bids: [ + { + bidder: 'equativ', + params: { + networkId: 42, // REQUIRED + siteId: 142, // optional + pageId: 242, // optional + formatId: 342, // optional + }, + }, + ], + }, +]; +``` + +##### Through ortb2 -- **Option 1**. Specify `networkId` by itself (_and optionally providing_ `siteId`, `pageId` and `formatId`), or -- **Option 2**. Specify either `ortb2.site.publisher.id`, `ortb2.app.publisher.id` or `ortb2.dooh.publisher.id` +A second way to specify Equativ-specific bidder parameters is through the `ortb2` object. The example below references a `ortb2.site.publisher.id` hierarchy, but publishers can also use `ortb2.app.publisher.id` or `ortb2.dooh.publisher.id` as their needs dictate. -See **Sample Banner Setup** for examples of these parameter options. +```javascript +pbjs.setBidderConfig({ + bidders: ['equativ'], + config: { + ortb2: { + site: { + publisher: { + id: 42, + }, + }, + }, + }, +}); +``` ### Supported Media Types @@ -57,12 +96,12 @@ See **Sample Banner Setup** for examples of these parameter options. | Type | Support | |---|---| | `banner` | Supported | -| `video` | Not currently supported | -| `native` | Not currently supported | +| `video` | Supported | +| `native` | Supported | ### User Syncing -To enable cookie syncing, make sure their configuration setup is properly invoked. +To enable cookie syncing, make sure the configuration setup is properly invoked. This involves adding an entry for `setConfig()` that allows user syncing for iframes with `'equativ'` included as a bidder: @@ -88,54 +127,224 @@ pbjs.bidderSettings = { }; ``` -### Configuration Example +### Ad Unit Setup -#### Sample Banner Setup +#### Banner -As mentioned in the **Bid Parameter Usage** section, when including `'equativ'` as one of your available bidders your adunit setup, there are two approaches to how you can specify parameters. Below are examples that illustrate them. +As mentioned in the **Bid Params > Usage** section, when including `'equativ'` as one of the available bidders in an adunit setup, there are two approaches to how publishers can specify parameters. The below example uses the approach using the `params` object. -#### Option 1 -- Using networkId as a parameter +```javascript +var bannerAdUnits = [ + { + code: 'div-123', + mediaTypes: { + banner: { + sizes: [ + [600, 500], + [300, 600], + ], + }, + }, + bids: [ + { + bidder: 'equativ', + params: { + networkId: 42, // REQUIRED + siteId: 142, // optional + pageId: 242, // optional + formatId: 342, // optional + }, + }, + ], + }, +]; -```html - +pbjs.que.push(function () { + pbjs.addAdUnits(nativeAdUnits); +}); ``` -#### Option 2 - Using ortb2 for parameter info +#### Audio + +It is possible to specify audio inventory through the Equativ adapter. To do so, publishers can define a video-formatted ad unit and specify audio information through the `ortb2Imp` property, like the example shown below. -You can also, as an alternative to using bidder params, specify a value for `publisher.id` that may be nested under an `app`, `site` or `dooh` object. The Equativ adapter will, in turn, look for these property paths under the `ortb2` property of the request: +Note that the `optional`, `recommended` and `REQUIRED` comments apply to the property itself, and not necessarily the values used in this example (_i.e._ `minduration` _is a recommended property to include, but it is up to publishers to decide what particular value it should have_). + +```javascript +var audioAdUnits = [ + { + code: '/19968336/header-bid-tag-1', + mediaTypes: { + video: { + context: 'instream', + playerSize: [640, 480], + }, + }, + ortb2Imp: { + audio: { + mimes: ['audio/mpeg', 'audio/mp4'], // REQUIRED + api: [7], // optional + delivery: [2, 4], // optional + minbitrate: 128, // optional + maxbitrate: 192, // optional + minduration: 10, // recommended + maxduration: 30, // recommended + maxextended: -1, // optional + protocols: [1, 3, 4, 7], // recommended + startdelay: 5, // recommended + }, + }, + bids: [ + { + bidder: 'equativ', + params: { + networkId: 1234, + }, + }, + ], + }, +]; + +pbjs.que.push(function () { + pbjs.addAdUnits(audioAdUnits); +}); +``` -- `ortb2.app.publisher.id` -- `ortb2.site.publisher.id` -- `ortb2.dooh.publisher.id` +{: .alert.alert-warning :} +**Note**: If a demand partner of Equativ is not capable of reading an audio object, the audio object will be converted into a video object with audio mime types. There is, as of this writing, no built-in/default support for serving audio assets in Prebid, so publishers that wish to do so will need to ensure their ad server setups can process whatever hand-offs are necessary. ### Additional Resources