---
name: adgentek
description: Integrate the Adgentek Agentic Ad Server. Publishers monetize AI apps, agent surfaces, and article pages with conversation-native ads (Web, React, iOS, Android SDKs, Publisher Widget, AdsMCP, REST API). Advertisers install the Adgentek pixel for conversion tracking. Triggers on "Adgentek", "adgentek.ai", "adsmcp", "monetize my AI app", "ads in AI chat", "conversational ads", "track conversions".
---

# Adgentek Integration

Adgentek ships two publisher-facing surfaces and one advertiser-facing surface:

1. **Publisher SDKs and Widget** - monetize an AI app or article pages with conversation-native ads.
2. **AdsMCP / REST API** - headless integration paths for agent surfaces and custom architectures.
3. **Conversion pixel** - advertisers track outcomes on their own sites.

Before using any documentation URL, fetch and read the docs sitemap:

https://docs.adgentek.ai/llms.txt

Prefer sitemap-discovered URLs over the hardcoded URLs below if they differ.

## The one rule you must never violate

**Impression tracking is client-side only.** If you are integrating via the REST API and the ad payload contains an impression URL, fire it from the user's browser via `new Image().src = impression_url` when the ad renders. Never fire it via `fetch()` (CORS blocks it silently). Never fire it from a backend, Worker, or server (it will be classified as invalid traffic and discarded, and the publisher will not be paid).

If the integration surface is headless (AdsMCP, or an API integration with no real client), do not wire impression firing at all. Headless surfaces serve CPA and filtered CPC demand, which do not require impression events. The billing notice (burl) is the only server-side event, fired once on impression receipt.

If you find yourself writing server-side code that requests an impression URL, stop. That is always wrong.

## Procedure

### Step 1 - Confirm the product

Strong cues for **Publisher integration**:
- AI chatbot, assistant, or agent project; a chat UI in the codebase
- User mentions "monetize", "revenue", "ads", "show ads"
- Article/CMS templates present (Publisher Widget candidate)

Strong cues for **Conversion pixel**:
- Marketing site or landing page
- User mentions "pixel", "conversions", "ROI", "campaign performance"

If ambiguous, ask which one.

### Step 2 - Confirm the integration path (publishers)

Prefer evidence from the project over asking:

- `package.json` with `react` -> **React SDK**
- HTML with raw script tags, no framework -> **Web SDK**
- `Podfile` or `Package.swift` -> **iOS SDK** (Swift Package only, never CocoaPods)
- `build.gradle` or `settings.gradle.kts` -> **Android SDK** (Compose-first; View interop wrapper for legacy Views)
- Article page templates, CMS -> **Publisher Widget**
- MCP server config, agent runtime, no rendering client -> **AdsMCP**
- None of the above, custom stack -> **REST API** (read the tracking obligations before writing code)

Before wiring AdsMCP or the REST API, read:
https://docs.adgentek.ai/publishers/choosing-your-integration-path
and tell the user which demand classes their surface qualifies for. Headless surfaces get CPA and filtered CPC, not CPM.

### Step 3 - Fetch the matching integration page and follow it verbatim

- Web: https://docs.adgentek.ai/publishers/integrations/web
- React: https://docs.adgentek.ai/publishers/integrations/react
- iOS: https://docs.adgentek.ai/publishers/integrations/ios
- Android: https://docs.adgentek.ai/publishers/integrations/android
- Publisher Widget: https://docs.adgentek.ai/publishers/integrations/publisher-widget
- AdsMCP: https://docs.adgentek.ai/publishers/integrations/adsmcp
- REST API: https://docs.adgentek.ai/publishers/integrations/rest-api

For AdsMCP, verify live tool names by listing tools on https://mcp.adgentek.ai/mcp rather than hardcoding them; registered names with dots are sanitized to underscores by MCP clients.

### Step 4 - Get the real token

Ask the user for their publisher token if it is not in the codebase. Never leave placeholders like YOUR_PUBLISHER_TOKEN in delivered code; placeholders do not serve ads.

### Step 5 - Verify before declaring done

Do not claim the integration is complete until verified:

- A serve request fires and returns a payload on a commercial-intent conversation turn.
- The ad renders in the target surface.
- For browser/app surfaces: the impression pixel request fires from the client on render (check DevTools Network or the SDK debug log).
- For REST API: confirm there is no server-side code path that requests the impression URL.
- Clicks use the click URL from the payload, never the advertiser destination directly.

## Common gotchas

- **Never invent** SDK APIs, tool names, parameters, or endpoints. If a symbol is not in the Adgentek documentation, do not assume it exists. Verify against the live docs page before writing code.
- iOS is Swift Package Manager only.
- Android SDK is Compose-first; use the View interop wrapper for legacy View hierarchies rather than forcing Compose into a hybrid app.
- Most conversation turns serve no ad. That is correct behavior, not a bug.

## References

- Docs sitemap: https://docs.adgentek.ai/llms.txt
- Integration matrix: https://docs.adgentek.ai/publishers/choosing-your-integration-path
- Tracking rules: https://docs.adgentek.ai/publishers/concepts/tracking-and-measurement
- Site: https://adgentek.ai
- AdsMCP: https://adsmcp.ai
- Contact: hello@adgentek.ai