Protected Audience API¶
Important
This initiative is in its testing phase and the details on this page are a combination of the FLEDGE instructions on Github, Google’s own docs, and discussions with customers. If you know of anything missing or incorrect on this page, please talk to your account manager as BidSwitch is also trying to keep abreast of changes.
This initiative was formally known as TURTLEDOVE, then FLEDGE, and now Protected Audiences API (PAA). As part of Privacy Sandbox, Chrome proposed this in-browser API that lets advertisers and ad tech companies show interest-group targeted ads without relying on third-party cookies. For Suppliers and Buyers to use this when trading through BidSwitch a number of factors need to be taken into account.
Impressions and other types of conversion reporting need to be monitored closely for discrepancies during testing.
Bid requests and bid responses contain new fields within the Open RTB (ORTB) format, and some existing fields may not be passed in requests.
Bidders need to adjust to responding with signals that will be executed in the browser. Particularly the
generateBid()and thereportWin()functions.
Impression counting¶
The two most important sections about how impressions counting should work come from AdX’s own documentation and the FLEDGE documentation. This section explains BidSwitch’s reading of these two documents and is open to change as we test this new methodology.
https://github.com/WICG/turtledove/blob/main/FLEDGE.md#52-buyer-reporting-on-render-and-ad-events
https://developers.google.com/authorized-buyers/rtb/fledge-origin-trial#bid_feedback_notification
During the Protected Audience API testing with RTB partners, Google will count impressions when the browser calls its reportResult() function and subsequently fetches Google’s reporting URL in a call to sendReportTo().
Since the event used by Google for counting impressions in Protected Audience in-browser auctions might be different from the event used for counting impressions by its RTB buyer partners, impression counts might differ. One of Google’s goals for testing the Protected Audience API is to identify and reduce these discrepancies.
Important
For businesses using the BURL for impression tracking, there doesn’t appear to be a server-to-server equivalent with PAA. All events originate from the browser.
Creatives¶
Note
This section applies to Buyers testing PAA with Google AdX.
Creatives must be reviewed and approved by Google before they can be served from Protected Audience in-browser auctions. This can be done in two ways:
You can submit creatives for review through the Real-time Bidding API. This method should be used to get your creatives approved if you need a campaign to run successfully from the beginning.
You can submit unapproved creatives as part of the normal bidding process so that they are automatically scanned. While being scanned and approved, bids using such creatives are not eligible to win at auction. These creatives need to have two HTTP headers set so that they can be scanned.
Authorized-Buyers-Creative-IDThe Buyer-specific creative ID.Authorized-Buyers-Click-Through-URLsThe set of declared destination URLs for the creative encoded according to RFC 2396.
Authorized-Buyers-Creative-ID:123456
Authorized-Buyers-Click-Through-URLs:https%3A%2F%2Fwww.advertiser.com%2FclickUrl1,https%3A%2F%2Fwww.advertiser.com%2FclickUrl12
Bid requests¶
Requests may not contain any User Object for website traffic, nor any device.ifa
for in-app traffic. All other standard fields should be present. The following new
extension fields are being used when testing PAA.
imp.ext.aeint (Required) Specifies the auction environment.0(Default) all on the server-side, i.e traditional auction.1Requests with Protected Audience API support, in which a contextual auction runs on the exchange’s servers and the interest group bidding and the final auction runs in the browser.
imp.ext.interest_group_auction.widthint (Optional) Width of the ad slot for the PAA auction in pixels.imp.ext.interest_group_auction.heightint (Optional) Height in pixels.imp.ext.interest_group_auction.render_interest_group_adsint (Optional) PAA ads may or may not render depending on the current integration stage. This field indicates whether the winning PAA ad will be rendered.
{
"imp":[
{
"ext":{
"ae":1,
"interest_group_auction":{
"width":728,
"height":90,
"render_interest_group_ads":1
}
}
}
]
}
Bid responses¶
Responses must contain the following Interested Group Bid details.
ext.igbidarray of objects (Required) Interest group bids.ext.igbid.idstring (Required) Refers to the adslot being bid on, the ID should match original requestimp.idfield.ext.igbid.igbuyer.originstr (Required) Should match the origins where thegenerateBid()functions are hosted.ext.igbid.igbuyer.buyerdataAny JSON (Optional) Can include a buyer’s signals in the contextual bid response, which are propagated to the on-device bidding function. It is most likely this will be an array or an object.ext.igbid.igbuyer.maxbidfloat (Optional) In CPM. Expected maximum bid is the maximum bid price that your bidding function is expected to return. If the winning bid reported from the in-browser auction exceeds this amount, then the winning bid isn’t counted as a billable event.ext.igbid.igbuyer.maxbidcurstring (Optional) The bidding currency, the default is US Dollars e.g. “USD”
{
"ext":{
"igbid":[
{
"id":"adslot ID",
"igbuyer":[
{
"origin":"https://fledge.example.com",
"buyerdata":{
}
},
{
"origin":"https://fledge.example.com",
"buyerdata":{
},
"maxbid":3.21
}
]
}
]
}
}
Note
The following complete example was provided by Google DV360, it’s worth nothing the
buyerdata field.
{
"id": "XXXXXX",
"seatbid": [
{
"bid": [
{
"id": "0",
"impid": "1",
"price": 0.13322999999999999,
"adid": "1234",
"adm": "<iframe src=\"http://dsp.com/imp?bc=12345aaabbb&price=${AUCTION_PRICE}\"><\/iframe>",
"adomain": [
"foo.com"
],
"cid": "xxxxx",
"crid": "xxxx",
"w": 300,
"h": 300,
"lurl": "URL",
"language": "en",
"ext": {}
}
],
"seat": "0"
}
],
"cur": "USD",
"ext": {
"igbid": [
{
"impid": "1",
"igbuyer": [
{
"origin": "https://td.doubleclick.net",
"buyerdata": [
[
[
[
"V1tT-FetRW4",
[
-0.0052490234375,
0.0067138671875,
0.1103515625,
-0.03759765625,
-0.150390625,
0.042724609375,
0.10302734375,
-0.05419921875,
0.064453125,
-0.16796875,
-0.004974365234375,
0.0439453125,
0.0145263671875,
-0.1669921875,
0.017333984375,
0.0311279296875,
0.083984375,
0.00531005859375,
0.1455078125,
-0.05712890625,
-0.0673828125,
-0.050048828125,
-0.107421875,
0.05712890625,
0.0869140625,
0.0576171875,
0.22265625,
0.0230712890625,
-0.39453125,
0.12060546875,
-0.0380859375,
-0.013427734375
]
]
],
[
[
"_y5iTMo47PU",
[
0.11328125,
0.0869140625,
-0.216796875,
0.734375,
-0.259765625,
-0.80859375,
1.1171875,
-0.1640625,
0.20703125,
0.5625,
-0.423828125,
-0.10888671875,
-0.306640625,
0.39453125,
-0.240234375,
-0.314453125,
0.56640625,
-0.1640625,
-0.322265625,
0.68359375,
-0.10693359375,
-0.216796875,
-0.050048828125,
0.90625,
-0.00469970703125,
-1.109375,
-0.294921875,
0.10107421875,
0.341796875,
0.80859375,
-0.60546875,
-0.8203125
]
]
],
[
[
"TQOxNVMHAmI",
[
0.1455078125,
0.17578125,
-0.0284423828125,
0.02197265625,
-0.1484375,
-0.0166015625,
-0.1044921875,
0.0908203125,
-0.0030670166015625,
0.1083984375,
0.318359375,
-0.06591796875,
-0.07470703125,
-0.04248046875,
0.09912109375,
-0.00640869140625,
-0.189453125,
-0.022216796875,
0.1455078125,
0.12255859375,
-0.080078125,
0.049560546875,
0.026611328125,
0.01025390625,
0.11767578125,
0.1572265625,
-0.03173828125,
0.0390625,
-0.01324462890625,
0.039794921875,
-0.0478515625,
-0.01092529296875
]
]
]
],
null,
[
1,
null,
[
null,
null,
null,
null,
null,
200000000
],
[
0.59999999999999998,
0.5,
0.80000000000000004,
null,
null,
10000000
],
null,
null,
null,
null,
null,
null,
null,
-1
],
"CNzxjeeHmoADFUGOpgQdnGYC3Q",
[
[
[
12,
1,
[
982741561,
3709503834
],
null,
null,
1
],
[
17,
1,
[
883147996,
2574970911,
873292890,
3271548610,
1765613733,
3570008378,
58418197,
1856083587,
379825718,
1144167856,
1719887699,
3402406417,
3373656528,
3899325247,
1653238717,
3836813892,
2263373725,
323763093,
238681852,
1483739687,
2531254900,
2192113027,
640312438,
1800396439,
3704039431,
2348581961,
1477131866,
2659871432,
971659954,
2026941795,
2715897949,
3727275496,
733872185,
536790114,
1777413001,
3288213147,
2393773409,
839459846,
1917184603,
2374229924,
1873446359,
2670924888,
1561383826,
3243263147,
71247128,
3150041492,
4175686136,
837116398,
2029694006,
371040785,
1286368546,
859045723,
319229080,
2976461123,
1681891145,
1446331671,
2835225892,
1874345,
794241689,
3354570092,
2720580570,
2857989744,
3393085555,
1718442870,
1675946221,
1281446469,
3883367020,
3671347789,
1248365859,
412964539,
3608970400,
1212495135,
2189276618,
398936688,
1927556157,
1206570237,
14997819,
3191279870,
2907135631,
3352701625,
3497247849,
908966221,
2294267214,
3477941395,
3529570599,
3358944592,
4268446903,
645794230,
978032878,
784051053,
2553184221,
73615971,
1631329097,
1725396793,
1793228532
],
null,
null,
1
],
[
5,
2,
null,
null,
[
2,
[
[
1,
null,
[
[
1042011003,
281544554
],
[
1414564948,
2882104047
],
[
2899323555,
2853433402
],
[
3901930208,
150976083
],
[
307605786,
2417404249
],
[
58901805,
2042918802
],
[
867182116,
2711947438
],
[
1570856068,
809656459
],
[
2971085174,
3415245801
],
[
1553307687,
3176817806
],
[
474397255,
3828417771
]
],
1
],
[
1,
[
[
2,
[
[
1,
null,
[
[
129829215,
3489528076
],
[
2888600035,
2602240606
],
[
1177537022,
1659693691
],
[
63905763,
4101153881
],
[
2656807706,
3832123276
],
[
1055629525,
160234292
],
[
4096269628,
187714027
]
]
],
[
1,
null,
[
[
3434522020,
3677977530
],
[
3868694671,
205109439
],
[
287331834,
3840720748
],
[
3359952360,
2451005151
],
[
2211562793,
217894773
],
[
3928264956,
2337622826
]
]
]
]
],
[
2,
[
[
1,
null,
[
[
3567495275,
959771500
],
[
2236383389,
630039864
],
[
2656807706,
3832123276
],
[
1737388399,
2722542460
]
]
]
],
[
[
152527608,
4224866733
]
]
],
[
2,
null,
[
[
152527608,
4224866733
],
[
1737388399,
2722542460
]
]
],
[
2,
null,
[
[
152527608,
4224866733
],
[
598159185,
4145684349
]
]
]
],
[
[
179168982,
935539280
],
[
4091773390,
720466654
],
[
4023294142,
2532708125
],
[
2753741333,
1986588302
],
[
106847149,
1389186060
],
[
1000359766,
3848965643
],
[
63905763,
4101153881
],
[
994097604,
3867943592
],
[
1708736146,
3636966350
],
[
1117354013,
857283173
],
[
2268647318,
4232755516
],
[
305226282,
2478181157
],
[
989457612,
1279622940
],
[
2962250923,
3033037700
],
[
1692108892,
3958112210
],
[
1242058130,
3795134366
],
[
1372718728,
2560456909
]
]
],
[
2,
null,
[
[
1303372974,
3176710188
]
],
1
],
[
1,
[
[
2,
null,
[
[
932711769,
1282057313
]
],
1
]
],
[
[
1762650809,
1689856295
],
[
4228375758,
1877386433
]
]
]
]
],
1
],
[
15,
1,
[
3567640638,
963380490,
1949467216,
3500346062,
508601628
],
null,
null,
1
],
[
16,
1,
[
141881627,
3472114473,
3638820241,
4226763282,
1230527026,
1278410718,
2959528840,
4173778150,
338776886
]
],
[
14,
1,
[
982741561
]
],
[
18,
1,
[
3495345401
],
null,
null,
1
]
],
[
[
23,
4,
null,
null,
null,
null,
[
[
156,
7,
[
692,
602,
854,
1178,
1136,
914,
419
]
],
[
156,
7,
[
61,
505,
136,
430,
295,
511,
823
]
],
[
156,
7,
[
125,
437,
869,
908,
200,
356,
638
]
],
[
156,
7,
[
114,
645,
696,
549,
375,
42,
594
]
],
[
156,
7,
[
633,
117,
891,
396,
624,
855,
828
]
],
[
156,
7,
[
514,
1012,
739,
325,
1204,
574,
700
]
],
[
1200,
7,
[
3956,
3386,
1526,
986,
7856,
146,
5411
]
],
[
1200,
7,
[
8317,
3577,
9352,
2062,
7687,
5407,
3607
]
],
[
1200,
7,
[
3965,
4085,
5765,
2540,
5960,
7940,
4670
]
],
[
1200,
7,
[
6930,
1125,
6360,
4005,
5655,
1770,
9330
]
],
[
1200,
7,
[
5625,
5685,
1275,
6540,
240,
9015,
5340
]
],
[
1200,
7,
[
1762,
4372,
8707,
4837,
6292,
4702,
9052
]
],
[
3500,
7,
[
22356,
12986,
9526,
15386,
17456,
17746,
15011
]
],
[
3500,
7,
[
21917,
4377,
19752,
10862,
25287,
3807,
22807
]
],
[
3500,
7,
[
2365,
19285,
8165,
6540,
17160,
16740,
3070
]
],
[
3500,
7,
[
18930,
1125,
7160,
20005,
22455,
12970,
19730
]
],
[
3500,
7,
[
16825,
3285,
4475,
12140,
1040,
5815,
22940
]
],
[
3500,
7,
[
8962,
4372,
27107,
11237,
7892,
19902,
3452
]
]
]
],
[
22,
3,
null,
null,
null,
[
"HZsVLywYbiY="
]
],
[
3,
1,
[
3652312201,
628126327,
947657540
]
],
[
24,
2,
null,
null,
[
[
2687367950,
315686729
],
[
721732586,
707827744
],
[
2179334229,
150720264
],
[
3596965136,
2587171063
],
[
122552735,
2086563616
],
[
1967747925,
1837052093
],
[
1471041537,
2078122492
],
[
2846316006,
519881975
],
[
3795476793,
2367706139
],
[
189895056,
2255604482
],
[
2532182881,
2689091460
],
[
1079586705,
298183182
],
[
444844341,
1292152778
],
[
2152405022,
1938726547
],
[
36042150,
2463126926
],
[
3360817563,
1237425143
],
[
4130785876,
3794886437
],
[
3309551881,
2878671765
],
[
1659543210,
2318664779
],
[
4063710783,
3142124436
],
[
3536827326,
3754774993
],
[
3030983645,
1671207724
],
[
1661864964,
2055360350
],
[
3254726147,
3653028612
],
[
1344083688,
1989066912
],
[
1522716679,
911746605
],
[
657664748,
1255778512
],
[
2631314631,
2352426762
],
[
927940967,
3741621588
],
[
4068072755,
1983656710
],
[
1692889898,
2287824135
],
[
4219643083,
2471850981
],
[
736056222,
669901878
],
[
1523495574,
3664088911
],
[
3323357791,
2349110166
],
[
1964177330,
1210481747
],
[
600001145,
4120943933
],
[
343870951,
3609932798
],
[
2365182043,
4062069478
],
[
309905629,
1596220768
],
[
1176049137,
2024361689
],
[
4035066339,
2304528373
],
[
3909467552,
804267835
],
[
2317172254,
247147053
],
[
2993922495,
2614054925
],
[
1774617399,
4094583585
],
[
3083444954,
2397181785
],
[
2161314118,
767917507
],
[
4283088215,
876671417
],
[
1314467899,
2412738532
],
[
730458598,
355790934
],
[
3673661517,
1939482093
],
[
3343686159,
3942793793
],
[
2831517563,
616824649
],
[
2966635193,
1729831330
],
[
2447018857,
1466506847
],
[
2921159844,
2362857914
],
[
2804380881,
3914678516
],
[
3554846173,
2986374119
],
[
1381542454,
2748794397
],
[
4251449262,
705196334
],
[
1889380046,
3353101593
],
[
691644180,
3365312518
]
]
],
[
19,
3,
null,
null,
null,
[
"dfTOmp0oFrU="
]
],
[
7,
2,
null,
null,
[
[
3931197429,
2707431213
],
[
3512580629,
543549395
],
[
995371194,
2563740660
],
[
944401176,
1104276254
],
[
1310338544,
1324121108
],
[
2364099629,
4090125282
],
[
1710131554,
3020067260
],
[
3686189411,
892706500
],
[
35092671,
2159125892
],
[
2521289443,
1799802379
],
[
544316994,
234258256
],
[
2808070461,
3548355068
],
[
3178565376,
2613679320
],
[
598923240,
2063043804
],
[
45405125,
3773767172
],
[
1169887221,
1980238956
],
[
260414369,
2246488008
],
[
1775621348,
2011657029
],
[
3537677641,
2793047748
],
[
4044084542,
1716376630
],
[
322662353,
1707275122
],
[
653128618,
816129492
],
[
1291837669,
430147816
],
[
3133404309,
4214708169
],
[
3821831023,
706627865
],
[
442618368,
2092838946
],
[
2740582848,
3778804278
],
[
4074255889,
2359589928
],
[
2588714583,
1287119466
],
[
3069451349,
3445051489
],
[
4148808734,
1329925900
],
[
1237809778,
2279705427
],
[
1629778280,
4031142945
],
[
2832877633,
3886294427
],
[
3206227104,
1610956767
],
[
1646475784,
353295474
],
[
116508619,
3051549720
],
[
139668736,
727128672
],
[
3809979890,
3549359814
],
[
1752216591,
91208550
],
[
1499147609,
2824357682
],
[
447794952,
1257360206
],
[
1009130626,
2922862417
],
[
1582787354,
3814215714
],
[
2230230130,
313643010
],
[
378494547,
2365886155
],
[
3428402947,
2927013949
],
[
3632440567,
2587212415
],
[
1414979454,
1287587118
],
[
248285055,
4190151969
],
[
215727952,
1408070400
],
[
3678220660,
2255626520
],
[
804963587,
1951906364
],
[
3623845799,
3803705820
],
[
2022727017,
1274565787
],
[
1465875600,
1550128305
],
[
3292086925,
1165088661
],
[
2017381044,
915857736
],
[
3773087513,
1298781211
],
[
1839559849,
490702661
],
[
174504739,
2145379985
],
[
4079489572,
2799701991
],
[
3024352778,
3182218899
],
[
2543572489,
313626170
],
[
1093673694,
1869602799
],
[
721989294,
3357148553
],
[
3728167851,
155158505
],
[
2253851599,
1207349863
],
[
4168358632,
54284812
],
[
4106225749,
4220158575
],
[
3696999320,
4082056870
],
[
1636593400,
1113930859
],
[
3662199275,
3694406415
],
[
531548221,
1565925735
]
]
],
[
21,
3,
null,
null,
null,
[
"HZsVLywYbiY="
]
],
[
20,
3,
null,
null,
null,
[
"dfTOmp0oFrU="
]
]
]
],
[
null,
null,
null,
null,
[],
null,
null,
0.0072499765625878886
],
[
null,
null,
null,
null,
[]
],
0.0072499765625878886,
null,
null,
1,
[
1,
1,
null,
null,
1
],
null,
null,
null,
null,
4
]
}
]
}
]
}
}