ContentItem lists, the content index, or organic analytics callbacks.
This page documents the Web SDK. The iOS, Android and React Native advertising APIs are not documented here yet.
Prerequisites
- A placement created in the Admin Portal under Advertising then Feeds & sources. Its Feed placement key identifies it from the SDK.
- Analytics consent granted on the SDK instance.
analyticsConsentdefaults to'granted'; with'denied'no ads are served. - For the Google sources, the feed must use the default
swipePaging: 'sdk'. Ads are not served whenswipePagingis'browser'.
Enable advertising on a feed
1
Grant consent per source
Call
setAdvertisingConsent on the SDK instance before enabling a placement. Each key allows one source; a source that is missing or false is never served, even if the placement is configured for it. Call it again whenever the user’s choice changes, for example from your consent management platform.app.js
2
Attach the placement to the feed
Pass the placement key and, for the Google sources, the ad units this page agrees to serve.Calling
app.js
setAdvertising again replaces the configuration.3
Report when your UI covers the feed
The SDK observes the browser viewport, but not your own overlays. When a modal, drawer or cookie banner covers the feed, call
setAdvertisingVisibility(false); call it with true when the feed is unobscured again. The default is true.app.js
Ad sources
A placement can serve several sources. The server picks the ad for each slot from the sources that are configured on the placement, consented by the user and allowed by the page.
The
gptNative and gptDisplay allowlists are an agreement from the page, not a request: the SDK only renders an ad whose unit is in the list. Leave a key out to opt the page out of that source. The google_swipeable consent key belongs to a native-only source; it is never served on web.
Disclosure label
Every web ad cell shows a disclosure label. The default isSponsored. Set disclosureLabel to change it (up to 40 printable characters). A label that breaks this limit, or an empty or malformed ad-unit list, makes the whole setAdvertising call be ignored silently, so validate the values you pass:
app.js
Header bidding for display slots
For thegam_display source the host page runs the auction and the SDK owns the slot. While an ad cell is being prepared, the SDK defines the Google Publisher Tag (GPT) slot, attaches the placement’s targeting, then calls your beforeAdRequest hook. You run your header-bidding auction for that slot and set the winning bids as targeting. The request to Ad Manager is sent later, when the cell is presented to the viewer — which may be well after the hook settled, or never if the viewer leaves first. In Ad Manager your direct, programmatic and header-bidding demand compete as on any other page.
The hook contract
beforeAdRequest receives a GptDisplayAuctionContext:
Rules:
- Return a promise that settles within
timeoutMs. On timeout or a thrown error the SDK goes ahead without your bids and requests the slot at presentation as usual; it never blocks the feed on the auction. - Set targeting on
slot(or through your wrapper’s GPT integration). Do not callgoogletag.display,pubads().refreshordestroySlotson the slot — the SDK does. A host-initiated refresh of an SDK slot ends that ad’s presentation. - Nothing from the ad request (ids, tokens) is passed to the hook, and nothing you return is read.
- The SDK prepares ad cells ahead of the viewer, so an auction may run for a slot that is never shown.
onAdSlotDestroyedfires once per defined slot, before the SDK destroys it, so you can release anything you registered for its element id.
Prebid.js example
app.js
setTargetingForGPTAsync matches the Prebid ad unit to the GPT slot by element id, which is why the ad unit code is elementId. If you use a managed wrapper instead of Prebid directly, run its per-slot auction for elementId and let it apply targeting to the slot the same way.
GPT page notes
-
Initial load disabled is supported. If your page calls
googletag.pubads().disableInitialLoad()(orgoogletag.setConfig({ disableInitialLoad: true })), the SDK refreshes its slot after displaying it. Nothing else is needed. -
Single request mode. Pages that enable
enableSingleRequest()should also disable initial load, so the SDK’s request is the only one for its slot. -
Page-wide refreshes. Exclude the SDK’s
sk-gpt-*element ids frompubads().refresh()calls that refresh every slot on the page: - Services. Load GPT and enable services as you normally do. If the page has not enabled them when the first ad is prepared, the SDK enables them.
Turn advertising off
Passnull to stop serving ads on the feed. Prepared ad cells are torn down and onAdSlotDestroyed fires for each defined display slot; an ad that is currently visible finishes before it is torn down.
app.js
setAdvertisingConsent stops that source without touching the placement configuration.
Next steps
- Configuration — the feed options that apply alongside advertising.
- Analytics — the organic events the SDK reports; ad presentations are never counted as content views.