The Smalk integration is publisher-facing. This page tells you exactly what to integrate **before** creating a Smalk account, so your team can validate feasibility upfront. **Three components to integrate:** 1. **JS Tracker** — single ` ``` **What the JS tracker does (in order of importance):** 1. **Detects headless-browser crawlers** — its original and primary purpose. Many bots (Googlebot, Bingbot, AppleBot, and an increasing share of AI agents) navigate via a headless browser that **does execute JavaScript**. These crawlers are invisible to pure server-side log analysis (their User-Agent often looks like a real browser) — the tracker catches them client-side via fingerprinting. 2. Drives ad framing (visual decoration around server-rendered ad content for human visitors). 3. Renders the on-page ad summary widget. > **GDPR note:** the tracker is bot-focused. It does **not** track human visitors, build profiles, set cookies, or store PII. Smalk has no human-analytics product and will not add one. **Placement:** `` or just before `` on every page. CMS plugins (WordPress / Drupal / Wix) auto-inject; custom integrations add the tag once in the global template. Required regardless of which other integration paths you choose. --- ## 1. CMS Plugin Integration (no-code path) Each official plugin handles **everything**: JS tracker injection, server-side AI bot tracking, ad div placement, Ad Server fetch, cache purge. - **WordPress** — install [`smalk-ai-analytics`](https://wordpress.org/plugins/smalk-ai-analytics) (free, WP.org). Paste API Key in **AI Analytics → Settings**. For ad monetization, also install **Smalk AI Ads Pro v1.1.0** (private zip). - **Drupal 9 / 10 / 11** — clone [`smalk-ai/drupal_plugin`](https://github.com/smalk-ai/drupal_plugin) into `modules/contrib/smalk`, then `drush en smalk -y`, configure at `/admin/config/services/smalk`. - **Wix (Velo)** — see [`smalk-ai/wix_velo_plugin`](https://github.com/smalk-ai/wix_velo_plugin). Enable Dev Mode, add `SMALK_API_KEY` + `SMALK_PROJECT_KEY` to Wix Secrets Manager, drop `backend/smalk.jsw`. - **Next.js** — `npm install @smalk/nextjs-ads @smalk/analytics`. Use `` (App Router) or `getSmalkAd()` + `` (Pages Router). See [`@smalk/nextjs-ads`](https://www.npmjs.com/package/@smalk/nextjs-ads). --- ## 2. Custom Integration (any backend) ### 2.1. Place the ad slot Add **exactly one** empty `

` per page, class `smalk-ads`, **no other attributes**: ```html

``` > **Hard rules:** one slot per page max — multiple `smalk-ads` divs not supported. No `id`, no `data-*`, no inline styles. The contract is the class token `smalk-ads` and nothing else. The old `selector_id` / `id` attribute mechanism is deprecated. If the Ad Server returns `{"html": ""}`, **do not remove or replace the div** — leave it intact (Smalk uses div presence to verify the placement is installed). #### Battle-tested regex (production plugins) **WordPress (PHP):** ```php if (!preg_match('/<(div|section|aside)\b[^>]*\bsmalk-ads\b/i', $html)) return $html; $open_tag_pattern = '/<(div|section|aside)\b[^>]*\bsmalk-ads\b[^>]*>/i'; ``` **Drupal (PHP):** ```php const DIV_PATTERN = '/<(\w+)[^>]*\bsmalk-ads(?:="[^"]*"|=\'[^\']*\'|=[^\s>]+|(?=\s)|(?=>))[^>]*>.*?<\/\1>/is'; ``` **Next.js / Node (TypeScript):** ```ts const SMALK_ADS_PATTERN = /<(\w+)[^>]*\bsmalk-ads\b[^>]*>[\s\S]*?<\/\1>/i; if (!body || body.indexOf('smalk-ads') === -1) return res; // fast-path ``` **Python (Django, FastAPI, Flask, …):** ```python import re SMALK_ADS_PATTERN = re.compile( r'<(\w+)[^>]*\bsmalk-ads\b[^>]*>.*?', re.IGNORECASE | re.DOTALL, ) if 'smalk-ads' not in html: return html # fast-path ``` **Why these patterns:** `\b…\b` boundaries → exact class-token match; `<(\w+) … ` → same opening + closing tag (works for `

`, `

`); `indexOf('smalk-ads')` fast-path skips the regex on ~99% of pages. ### 2.2. Server-side ad injection — `POST /api/v1/transform/ads/content/` On every HTML request, detect the `

`, POST to the Ad Server with a **150ms timeout** (100ms preferred), replace the div with `response.html` (only if non-empty). **Required:** `project_key` (UUID), `page_url` (full URL — `current_url` accepted as alias). **Strongly recommended:** `user_agent` (critical for AI-bot detection + ad targeting). **Optional:** `referer`, `preview`. (`client_ip` is accepted for backward compatibility but ignored — no caller IP is ever read.) **Latency (production):** avg ≈ 12 ms, p90 ≈ 40 ms, p99 < 100 ms. **SLA:** < 100 ms p99. See the **GEA - Ad Content** group below for the full spec. **Reference middlewares** (Django, Express, Laravel, PHP, Python, Node — always aligned with the current API): [https://app.smalk.ai/ads-inventory/integration](https://app.smalk.ai/ads-inventory/integration) → **Custom Integration** tab. ### 2.3. Cache & freshness — Active Ad URLs sweep > This endpoint is **not** used to detect which pages contain the smalk-ads div. Div detection happens via **regex on the HTML response at request time** (Section 2.1). `/active-ad-urls/` exists only to drive the daily cache-freshness job below. - **Page cache TTL ≤ 6 hours** (CDN, Varnish, Nginx, Cloudflare cache rules, plugin page cache). - **Daily job:** `GET /api/v1/projects/{id}/ads/inventory/active-ad-urls/`, then for each URL → bump `Last-Modified` (touch resource / regenerate page / update source timestamp) + purge CDN. **CDN purge options:** DIY against your provider's API, **or** register CDN credentials at `https://app.smalk.ai/workspaces/{id}/ads/brand-safety/cdn` (Cloudflare, CloudFront, Fastly, Akamai, KeyCDN, BunnyCDN) and Smalk runs the purge for you nightly. See the **Ad Placement Inventory** group below. ### 2.4. AI agent tracking (mandatory) > The JS tracker (Section 0) is also required — it catches headless-browser crawlers and drives ad framing + summary. The options below cover **plain-HTTP AI agents** that never execute JavaScript. Pick **one**: - **Option A — Server-side REST** (any stack): `POST /api/v1/tracking/visit/` with `Api-Key` auth. Always **async / fire-and-forget** (`response.on('finish')`, `defer`, any background-job system you already use). 150 ms client timeout = safety net, never an objective. See **Tracking** group below. High-traffic sites can batch up to 500 visits per request via `POST /api/v1/tracking/visit/batch/` (same auth). - **Option B — Cloudflare Worker** (recommended if on Cloudflare): drop-in Worker mirroring every request to Smalk async. Managed from your Smalk workspace (Integrations → Cloudflare → Worker mode). No origin changes. - **Option C — Cloudflare Logpush** (Enterprise plans): no code. Destination URL `https://api.smalk.ai/api/v1/tracking/cloudflare/logpush?header_Authorization=Api-Key%20YOUR_API_KEY`. Dataset `http_requests`, filter on `ClientRequestHost`, fields `ClientIP, ClientRequestHost, ClientRequestMethod, ClientRequestReferer, ClientRequestURI, ClientRequestUserAgent, EdgeStartTimestamp, EdgeResponseStatus, EdgeResponseBytes`, timestamp `rfc3339`. **GDPR header allowlist:** forward **only** `User-Agent` and `Referer`. **Never send** `X-Real-IP`, `X-Forwarded-For` or any other IP-bearing header, nor `Authorization`, `Cookie`, JWT, API tokens, CSRF tokens or session headers. No visitor IP is collected on any path: IP-bearing headers are stripped at ingest before anything is queued or written, so a legacy integration that still sends one is not a compliance problem — the value is discarded on arrival. Headers outside the allowlist are not analyzed, not processed and not stored. --- ## 3. Operational requirements | Concern | Requirement | |---|---| | Ad Server timeout (client side) | ≤ 150 ms hard cap (100 ms preferred) | | Ad Server SLA (server side) | < 100 ms p99 (observed: avg ≈ 12 ms, p90 ≈ 40 ms) | | Page cache TTL | ≤ 6 hours | | Active-ad URLs sweep | every 24h minimum (6h ideal) | | `Last-Modified` bump | daily, on URLs returned by `/active-ad-urls/` | | Tracking call | async / fire-and-forget, never blocks rendering | | Failure behavior | **Fail open** — never break the page if Smalk is slow/down | | Empty ad response | leave the `

` in place | --- ## 4. Verification (before going live) - [ ] `

` present in server-rendered HTML (visible in `curl` / "View Source", not just DevTools) - [ ] Ad Server call uses `Api-Key` auth and ≤150ms timeout - [ ] Empty `html` response leaves the div unchanged - [ ] Tracking endpoint hit on every page (check the Smalk dashboard Visits page shows traffic) - [ ] Headers filtered — no `Cookie` / `Authorization` forwarded - [ ] Daily job calls `/active-ad-urls/`, bumps `Last-Modified`, purges CDN - [ ] Page cache TTL ≤ 6h on ad-bearing URLs - [ ] Curl test from an AI-bot UA returns the ad HTML inline: ```bash curl -A "Mozilla/5.0 (compatible; ChatGPT-User/1.0)" https://your.site/article | grep -A2 smalk-ads ``` --- ## 5. Going further - **Reference middlewares** (always up to date): `https://app.smalk.ai/ads-inventory/integration` - **Analytics integration** (JS tracker + REST tracking variants): `https://app.smalk.ai/integrations` - **CDN credentials dashboard:** `https://app.smalk.ai/workspaces/{workspace-id}/ads/brand-safety/cdn` - **WordPress plugin source (reference impl):** [github.com/smalk-ai/smalk-ai-ads-pro](https://github.com/smalk-ai) — server-side ad injection, daily freshness sweep, cache purge - **Support:** [support@smalk.ai](mailto:support@smalk.ai)