Learn how to update audience data by configuring an update URL for a Protected Audience API interest group. Read the developer guide for the full lifecycle of the Protected Audience API, and refer to the Protected Audience API explainer for an in-depth proposal of how browsers record interest groups.
Not a developer? Refer to the Protected Audience API overview.
Protected Audience API interest groups
A Protected Audience API interest group represents a group of people with a common interest, corresponding to a remarketing list. Every Protected Audience API interest group has an owner.
Interest group owners act as the buyer in the Protected Audience API ad auction. Interest group membership is stored by the browser, on the user's device, and is not shared with the browser vendor or anyone else.
API functions
Example usage
Here's the example from the guide on how to define audience data showing how to create an interest group and ask the browser to join the group.
const interestGroup = {
owner: 'https://dsp.example',
name: 'custom-bikes',
biddingLogicUrl: ...,
biddingWasmHelperUrl: ...,
updateUrl: ...,
trustedBiddingSignalsUrl: ...,
trustedBiddingSignalsKeys: ['key1', 'key2'],
userBiddingSignals: {...},
ads: [bikeAd1, bikeAd2, bikeAd3],
adComponents: [customBike1, customBike2, bikePedal, bikeFrame1, bikeFrame2],
};
navigator.joinAdInterestGroup(interestGroup, 7 * kSecsPerDay);
The updateUrl provides a URL that returns JSON to update interest group attributes. This must have the same origin as the owner.
Update attributes
updateUrl specifies a web server that returns JSON defining interest group properties, corresponding to the interest group object passed to joinAdInterestGroup().
This allows the group's owner to periodically update the attributes of the interest group. In the current implementation, the following attributes can be changed:
biddingLogicUrlbiddingWasmHelperUrltrustedBiddingSignalsUrltrustedBiddingSignalsKeysadspriority
Any field not specified in the JSON won't be overwritten—only fields specified in the JSON get updated—whereas calling navigator.joinAdInterestGroup() overwrites any existing interest group.
Updates are best-effort, and can fail under the following conditions:
- Network request timeout (currently 30 seconds).
- Other network failure.
- JSON parsing failure.
Updates are rate-limited to a maximum of one per day.
Updates can be canceled if too much contiguous time has been spent updating, though this doesn't impose any rate limiting on canceled (remaining) updates. Updates that fail due to network errors are retried after an hour, and updates that fail due to disconnection from the internet are retried immediately on reconnection.
Manual updates
Updates to interest groups owned by the current frame's origin can be triggered manually using navigator.updateAdInterestGroups().
Rate limiting prevents updates from happening too frequently: repeated calls to navigator.updateAdInterestGroups() don't do anything until the rate limit period (currently one day) has passed.
The rate limit gets reset if navigator.joinAdInterestGroup() is called again for the same interest group owner and name.
Automatic updates
All interest groups loaded for an auction are updated automatically after an auction completes, subject to the same rate limits as manual updates.
For each owner with at least one interest group participating in an auction, it's as if navigator.updateAdInterestGroups() is called from an iframe whose origin matches that owner.
All Protected Audience API references
API reference guides are available:
- Developer guide for the Protected Audience API.
- Ad buyer guide to Protected Audience interest groups and bid generation.
- Ad seller guide to Protected Audience ad auctions.
- Guide to reporting auction results
- Best practices for Protected Audience ad auction latency
- Troubleshoot Protected Audience
The Protected Audience API explainer also provides detail about feature support and constraints.