From 90304edf3d1703a33cb829ec86a8c20781b2475d Mon Sep 17 00:00:00 2001 From: Muki Seiler Date: Thu, 19 Sep 2024 13:35:52 +0000 Subject: [PATCH 1/2] Add stored impressions examples --- dev-docs/examples/stored-impressions.md | 212 ++++++++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 dev-docs/examples/stored-impressions.md diff --git a/dev-docs/examples/stored-impressions.md b/dev-docs/examples/stored-impressions.md new file mode 100644 index 0000000000..5ff7b7bf67 --- /dev/null +++ b/dev-docs/examples/stored-impressions.md @@ -0,0 +1,212 @@ +--- +layout: example +title: PBS+PBJS Stored Impressions +description: Different prebid server stored impression variants + +sidebarType: 1 + +about: +- Show cases three variants of prebid server integrations +- stored impression in ortb2Imp object on the ad unit +- stored impression on a bids object with module configured +- client-side adapters that are configured as PBS adapters + +pid: 20 +--- + +Prebid.js has two main ways to select configuration for an ad unit. + +1. re-using the client-side configuration, but mark a bidder as server-side in the `s2sConfig` +2. set a stored impression id in the `ortb2Imp.ext.prebid.storedrequest.id` property + +Using prebid server offers a few benefits, such as + +1. reduced latency due to less requests +2. reduced javascript bundle size as most bidder adapters are not required +3. more control over configuration and faster reaction times, because no client-side configuration must be rolled-out + +There are however a few drawbacks, like + +1. reduced client-side analytics, because a lot of information is left on the server and prebid.js can't connect the dots +2. bidders lacking features on server-side, that are already available client-side + +## Integration variants + +Every option has a certain use case. Choose the one that fits best. + +You can learn more about the general configuration here. + +- [adunit reference on stored impressions](/dev-docs/adunit-reference.html#stored-imp) +- [prebidServer module for prebid.js](/dev-docs/modules/prebidServer.html) + +### Reusing client-side configuration + +{% capture tipNoteClientSide %} +Use this if you want to AB test client vs server +{% endcapture %} + +{% include alerts/alert_tip.html content=tipNoteClientSide %} + +{% capture warnNoteClientSide %} +This requires client-side adapters to be present +{% endcapture %} + +{% include alerts/alert_warning.html content=warnNoteClientSide %} + +```js +pbjs.setConfig({ + // configure a single prebid server instance + s2sConfig: [{ + accountId: '1001', + bidders: ['bidderA'], + endpoint: 'https://mypbs.example.com/path', + syncEndpoint: 'https://mypbs.example.com/path', + timeout: 1000 + }] +}); + +pbjs.addAdUnits({ + code: "test-div", + bids: [ + { + // this bidder is part of the bidders array, so it will not make client-side calls, but + // there params will be transfered to prebid server + bidder: 'bidderA', + params: { + placementId: 12345 + } + }, + { + // this one stays client-side + bidder: 'bidderB', + params: { + placementId: 55555 + } + } + ] +}); +``` + +### adUnit.ortb2Imp configuration + +{% capture tipNoteOrtb2Imp %} +When using [PBS stored impressions](/dev-docs/modules/prebidServer.html#stored-imp), bids is not required. +Use this if you want to configure everything server side and have a **single** prebid server endpoint. +{% endcapture %} + +{% include alerts/alert_tip.html content=tipNoteOrtb2Imp %} + +```js +pbjs.setConfig({ + // configure a single prebid server instance + s2sConfig: [{ + accountId: '1001', + bidders: ['bidderA', 'bidderB'], + endpoint: 'https://mypbs.example.com/path', + syncEndpoint: 'https://mypbs.example.com/path', + timeout: 1000 + }] +}); + +pbjs.addAdUnits({ + code: "test-div", + ortb2Imp: { + ext: { + prebid: { + storedrequest: { + id: 'stored-request-id' + } + } + } + } + // no bids object +}); +``` + +See [defining endpoints for prebid server](/dev-docs/modules/prebidServer.html#defining-endpoints) + +### bids[].module configuration + +{% capture tipNoteModule %} +Use [PBS stored impressions](/dev-docs/modules/prebidServer.html#stored-imp) together with client-side bidders - or stored impressions from multiple instances of Prebid Server +{% endcapture %} + +{% include alerts/alert_tip.html content=tipNoteModule %} + +```js +pbjs.setConfig({ + s2sConfig: [ + { + name: "pbs-appnexus", + accountId: '12345', + bidders: ['appnexus','pubmatic'], + defaultVendor: 'appnexus', + timeout: 1000, + }, + { + name: "pbs-rubicon", + accountId: '678910', + bidders: ['rubicon'], + defaultVendor: 'rubicon', + timeout: 1000, + }, + ] +}); + +pbjs.addAdUnits({ + code: "test-div", + bids: [ + { + module: "pbsBidAdapter", + params: { + configName: "pbs-appnexus" + }, + ortb2Imp: { + ext: { + prebid: { + storedrequest: { + id: 'stored-request-server-1' + } + } + } + } + }, + { + module: "pbsBidAdapter", + params: { + configName: "pbs-rubicon" + }, + ortb2Imp: { + ext: { + prebid: { + storedrequest: { + id: 'stored-request-server-2' + } + } + } + } + }, + { + bidder: 'client-bidder', + // ... + } + ] +}); +``` + +See [defining endpoints for prebid server](/dev-docs/modules/prebidServer.html#defining-endpoints) + +{% capture htmlCodePrebid %}
Div-1
+
+ +
+{% endcapture %} + +{% capture jsCode %}// TODO add code example +{% endcapture %} + +{% include code/web-example.html id="basic-prebid-example" html=htmlCodePrebid js=jsCode %} From 622d11272b0cfff807c25fcd086decf205949df5 Mon Sep 17 00:00:00 2001 From: bretg Date: Mon, 7 Oct 2024 12:41:16 -0400 Subject: [PATCH 2/2] wordsmithing --- dev-docs/examples/stored-impressions.md | 26 ++++++++++++------------- 1 file changed, 12 insertions(+), 14 deletions(-) diff --git a/dev-docs/examples/stored-impressions.md b/dev-docs/examples/stored-impressions.md index 5ff7b7bf67..e00cbc343b 100644 --- a/dev-docs/examples/stored-impressions.md +++ b/dev-docs/examples/stored-impressions.md @@ -10,31 +10,29 @@ about: - stored impression in ortb2Imp object on the ad unit - stored impression on a bids object with module configured - client-side adapters that are configured as PBS adapters - -pid: 20 --- -Prebid.js has two main ways to select configuration for an ad unit. +Prebid.js has two main ways to select configuration for an ad unit: -1. re-using the client-side configuration, but mark a bidder as server-side in the `s2sConfig` -2. set a stored impression id in the `ortb2Imp.ext.prebid.storedrequest.id` property +1. Reuse the client-side configuration, but mark a bidder as server-side in the `s2sConfig` +2. Set a stored impression id in the `ortb2Imp.ext.prebid.storedrequest.id` property -Using prebid server offers a few benefits, such as +Using Prebid Server offers a few benefits, such as: -1. reduced latency due to less requests -2. reduced javascript bundle size as most bidder adapters are not required -3. more control over configuration and faster reaction times, because no client-side configuration must be rolled-out +1. Reduced latency due to less requests +2. Reduced javascript bundle size as most bidder adapters are not required +3. More control over configuration and faster reaction times, because no client-side configuration must be rolled-out -There are however a few drawbacks, like +There are however a few drawbacks: -1. reduced client-side analytics, because a lot of information is left on the server and prebid.js can't connect the dots -2. bidders lacking features on server-side, that are already available client-side +1. Reduced client-side analytics, because some information is left on the server and not available to client-side analytics adapters. (Note, this problem is getting better with time.) +2. Some bidders may lack features in their server-side adapters that are available client-side ## Integration variants Every option has a certain use case. Choose the one that fits best. -You can learn more about the general configuration here. +You can learn more about the general configuration here: - [adunit reference on stored impressions](/dev-docs/adunit-reference.html#stored-imp) - [prebidServer module for prebid.js](/dev-docs/modules/prebidServer.html) @@ -90,7 +88,7 @@ pbjs.addAdUnits({ ### adUnit.ortb2Imp configuration {% capture tipNoteOrtb2Imp %} -When using [PBS stored impressions](/dev-docs/modules/prebidServer.html#stored-imp), bids is not required. +When using [PBS stored impressions](/dev-docs/modules/prebidServer.html#stored-imp), the `AdUnit.bids` array is not required. Use this if you want to configure everything server side and have a **single** prebid server endpoint. {% endcapture %}