# Publisher SDK: Integration Guide (v1) The Adgeist Publisher SDK serves ads into slots on your pages, measures their views and clicks, sends page events to the Adgeist CDP, and manages user consent. You add one script tag and one `` element per ad slot. The SDK fills the slots on its own, and you call its global functions to identify users and send custom events. | | | | ------------ | --------------------- | | Global | `window.adsbyadgeist` | | Bundle size | ~31 kB gzipped | | Dependencies | nothing to install | **Steps** 1. [Integrate the SDK](#step-1-integrate-the-sdk) 2. [Access the SDK](#step-2-access-the-sdk) 3. [Global functions](#step-3-global-functions): `setUserDetails`, `trackCustomEvent`, `showConsentBanner` 4. [Version](#step-4-version) **Reference:** [API reference](#api-reference) · [How it works](#appendix-how-it-works) · [Troubleshooting](#troubleshooting) --- ## Step 1: Integrate the SDK ### 1.1 Add the script tag **Where:** once, in your site's root file: the shared layout or template that every page uses (`index.html`, `app/layout.tsx`, a base template). That single tag loads the SDK on every page; you don't add it per page or per component. `` is the usual spot; the end of `` works too. ```html ``` **No `init()` call.** The SDK starts on its own when the script loads. | Attribute | Required | Default | Purpose | | ---------------------------------- | -------- | ------- | ---------------------------------------------------------------- | | `data-publisher-id` | **yes** | | Your Adgeist publisher ID. Without it no ads are shown. | | `data-should-ingest-events-to-cdp` | no | `true` | Set to `"false"` to stop sending page events to the Adgeist CDP. | Put these attributes on the SDK's own ` ``` #### Configure consent Set the config **before** the SDK loads, in an inline ` ``` or queue it with `window.adgeistConsent = [['setConsentConfig', config]]`. | Field | Type | Default | Notes | | ------------ | ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------ | | `mode` | `'opt-in' \| 'opt-out'` | `'opt-out'` | `opt-out`: collection runs until the user rejects. `opt-in`: collection is off until the user accepts. | | `autoShow` | `boolean` | `false` | Show the banner automatically when the user hasn't made a choice yet. | | `ui` | `'default' \| 'none'` | `'default'` | `'none'` to bring your own UI. | | `policyUrl` | `string` | | Link shown in the banner. | | `cookieName` | `string` | `'adgeist_consent'` | Cookie that stores the user's choice. | | `persist` | `boolean` | `true` | `false` stops the config from being remembered on later page loads. | To supply your own UI, set `ui: "none"` and use `window.adgeistConsent` (`acceptAll()`, `rejectAll()`, `setConsent()`, `onConsentChange()`, …). --- ## Step 4: Version **Purpose.** Tells you which SDK version is running on the page. ```ts window.adsbyadgeist.version: string // e.g. '1.4.3' ``` It is a property, not a function. Use it when debugging or reporting an issue: ```js console.log(window.adsbyadgeist && window.adsbyadgeist.version); ``` **Which version you get** depends on the script URL ([channels](#channels)): - `v1` (floating): the latest `1.x.y`. Fixes and backward-compatible features arrive automatically. Breaking changes ship as `v2`, which you opt into. - `` (pinned): exactly that version, never changes. Required for SRI. - `v1-beta`: pre-release versions. Beta and production share version numbers; only the script URL (`cdn-beta.adgeist.ai/.../v1-beta` vs `cdn.adgeist.ai/.../v1`) tells them apart. --- ## API reference ```ts window.adsbyadgeist.setUserDetails(details: { userId: string; email?: string; phone?: string; name?: string; companyName?: string; }): Promise window.adsbyadgeist.trackCustomEvent( eventType: string, eventData: Record, ): Promise window.adsbyadgeist.showConsentBanner(): void window.adsbyadgeist.version: string ``` --- ## Appendix: How it works ### Single-page apps Client-side route changes are handled automatically. New slots are filled, and slots that are already showing an ad keep it. React Router, Next.js and Vue Router need no extra setup. ### Ad formats The ad's layout comes from the type of the ad space: | Type | Shows | | ----------- | ------------------------------------------------------------------- | | `banner` | One image or video filling the slot | | `display` | Image or video with headline and text, laid out to fit the slot | | `companion` | Video with a mute toggle, a banner below it, and advertiser details | Ads render in an isolated frame, so your page's CSS doesn't affect the ad and the ad's CSS doesn't affect your page. ### Views and clicks A view is counted when at least 50% of the ad is on screen for 1 second (2 seconds for video). Clicks are counted when the user clicks the ad. --- ## Troubleshooting ### Slot stays empty 1. **Check `data-ad-slot`** is present and matches your ad space ID. 2. **Check the slot meets the minimum size** for its type (see the table in [1.2](#12-place-an-ad-slot)). 3. **Check `data-publisher-id`** is on the SDK's own `