Developer docs

One SDK call.
Matching stays on-device.

Seven SDKs, one integration model. The Browser JS SDK is live today; the rest are built and land as the public repo opens: replace your LLM call (or enqueue a script tag) and Cognatu handles topic matching, ad selection, and optional private attribute verification locally, raw conversation text never leaves the device or process it started in.

🤖 Give it to your AI agent → Public repo & package registries, coming soon
For publishers

Give this to your coding agent.

Paste it into Claude Code, Cursor, or whatever you use. It reads your codebase, picks the right SDK below, and wires it up. You only do one thing afterward: drop your real publisher key into the env var it tells you to.

Cognatu integration prompt

    

  









  

    
Choose a platform

    
Pick your SDK

    
Every SDK exposes the same shape: a client (or middleware) configured with your publisher ID and gateway URL, one call per turn/screen, and an on-device privacy layer that's on by default.

    

       Available now
       Coming soon
    


    


    

      

        
Go
Reference implementation

        
Coming soon. Needs the public repo and package registry. The Browser JS SDK works today. Email us for early access.

        
Contextual ad injection for Go LLM apps. Every other Cognatu SDK ports from or calls into this implementation via FFI/WASM/gomobile. Not yet on a module proxy under its own path, import directly from this repo's module.

        
Install

        
go get github.com/cognatu/cognatu@latest

        
Quickstart

        
import "github.com/cognatu/cognatu/pkg/sdk"

mw := sdk.NewMiddleware(sdk.Config{
    PublisherID:   "pub_your_id",
    GatewayURL:    "https://api.cognatu.com",
    GatewayAPIKey: "pub_key_...",              // authenticates auction calls — server-side only
    UpstreamURL:   "https://api.groq.com/openai",
    APIKey:        os.Getenv("GROQ_API_KEY"),  // upstream LLM credential, NOT the gateway key
    LLMModel:      "llama-3.3-70b-versatile",
})
http.Handle("/v1/chat/completions", mw)

        
Middleware wraps any OpenAI-compatible chat completions endpoint: it forwards the request upstream, extracts a conversation context from the messages + response, runs the ad auction, and (on a win) appends a clearly labelled sponsored block before returning.

      


      

        
Python
FastAPI · Starlette · Django ASGI

        
Coming soon. Needs the public repo and package registry. The Browser JS SDK works today. Email us for early access.

        
Contextual ad injection for Python LLM apps. Matching, topic decay, and private attribute verification run on-device in your own process.

        
Install

        
pip install cognatu

        
Quickstart, zero-code (ASGI middleware)

        
from cognatu import CognatuMiddleware

app.add_middleware(
    CognatuMiddleware,
    publisher_id="pub_your_id",
    gateway_url="https://api.cognatu.com",
    api_key="pub_key_your_gateway_key",
)

        
Quickstart, explicit client

        
from cognatu import CognatuClient

client = CognatuClient(
    publisher_id="pub_your_id",
    gateway_url="https://api.cognatu.com",
    api_key="pub_key_your_gateway_key",
)

# Async (FastAPI, async Django)
enriched = await client.enrich(messages, llm_response_text)

# Sync (Flask, Django sync views)
enriched = client.enrich_sync(messages, llm_response_text)

        
Use the middleware when you want zero code changes; use the explicit client when you call the LLM yourself and want control over when/where the ad appears, works with the OpenAI SDK, LangChain, liteLLM, etc.

      


      

        
iOS (Swift)
iOS 15+ / macOS 12+

        
Coming soon. Needs the public repo and package registry. The Browser JS SDK works today. Email us for early access.

        
Contextual ad injection for native iOS/macOS apps. Matching and private attribute verification both run on-device. Not yet on a registry (SPM index or CocoaPods trunk), add as a local or git-URL Swift Package dependency.

        
Quickstart

        
let cognatu = CognatuClient(
    publisherID: "pub_your_id",
    gatewayURL: "https://api.cognatu.com",
    persistWallet: true, // persist the privacy layer across app restarts (Keychain)
)
let result = await cognatu.auction(screenName: "ArticleDetail", contentText: article.body)
if result.won, let ad = result.winningAd {
    CognatuAdView(ad: ad, result: result, client: cognatu)
}

        
Building or running without the optional native library present still works. The client degrades gracefully rather than crashing; line items that require verification simply won't match.

      


      

        
Android (Kotlin)
JDK 17

        
Coming soon. Needs the public repo and package registry. The Browser JS SDK works today. Email us for early access.

        
Contextual ad injection for native Android apps. Matching and private attribute verification both run on-device, backed by the same core every other Cognatu SDK uses. Not yet on Maven, add as a Gradle source dependency.

        
Quickstart

        
val cognatu = CognatuClient(
    publisherID = "pub_your_id",
    gatewayURL  = "https://api.cognatu.com",
    context     = applicationContext, // persist the privacy layer across app restarts
)
val result = cognatu.auction(screenName = "ArticleDetail", contentText = article.body)
if (result.won) CognatuAdCard(ad = result.winningAd!!, result = result, client = cognatu)

        
Pass any Android Context (application context is fine) and on-device state is saved to EncryptedSharedPreferences.

      


      

        
React Native
Expo & bare RN · Android + iOS

        
Coming soon. Needs the public repo and package registry. The Browser JS SDK works today. Email us for early access.

        
Contextual ad injection for React Native / Expo apps. Matching and private attribute verification both run on-device on both platforms, via each platform's own native module. Not yet on npm, point package.json at a path or git URL.

        
Install

        
npm install /path/to/cognatu-sdk-react-native
# or: npm install github:cognatu/cognatu#path:pkg/sdk/react-native

        
Quickstart

        
import { CognatuClient, CognatuAdView } from 'cognatu-rn';

const cognatu = new CognatuClient({
  publisherID: 'pub_your_id',
  gatewayURL: 'https://api.cognatu.com',
});

<CognatuAdView client={cognatu} screenName="ArticleDetail" contentText={article.body} />

        
Reuse one CognatuClient across screens, only the client instance holds the decay-accumulated topic state that makes multi-screen targeting work. Call resetConversation() when the user starts an unrelated task.

      


      

        
Browser JS
Any static site or SPA

        
No build step, no package. A single script tag. Matching and (optional) private attribute verification both run in the browser via WASM; the WordPress plugin is just this same script enqueued for you.

        
Quickstart, content slot

        
<script src="https://api.cognatu.com/sdk.js" data-pub="pub_pk_..." async></script>
<div data-cognatu-slot></div>

        
Quickstart, conversational mode (chat widgets)

        
<script src="https://api.cognatu.com/sdk.js" data-pub="pub_pk_..." data-mode="conversation" async></script>
<script>
  window.Cognatu.matchTurn(userText, onStep);
</script>

        
The privacy layer is on by default, add data-disable-wallet="true" to opt out, which also skips fetching its WASM module entirely.

      


      

        
WordPress
WordPress 5.9+ · PHP 7.4+

        
Coming soon. Needs the public repo and package registry. The Browser JS SDK works today. Email us for early access.

        
A thin plugin that enqueues the Browser JS SDK above with your publisher key, all on-device matching and verification happen in that same script, WordPress just wires up the settings page and shortcode.

        
Install (development)

        
cp -r pkg/sdk/wordpress /path/to/wp-content/plugins/cognatu-ads

        
Activate the plugin, then configure under Settings → Cognatu Ads (publisher ID, gateway URL, timeout, wallet toggle). Add [cognatu_ad] to any post, page, or widget. No code required.

      

    

  









  

    
Under the hood

    
What "on-device" actually means

    
Identical pipeline across all seven SDKs, only the runtime changes.

    

      

        
STEP 01

        
Classify locally

        
A tiny word-vector model, fetched and cached once, embeds and classifies the conversation/page text into topic scores, in-process, on text you already have in memory.

      

      

        
STEP 02

        
Match locally

        
Topic scores (with decay across turns) match against a cached catalog, producing an opaque line-item shortlist (never a relevance score, never the raw text) sent to the gateway.

      

      

        
STEP 03

        
Prove locally (optional)

        
Line items that require a verified attribute are checked on-device. Only the yes/no result ever reaches the gateway, never the attribute, never the underlying value. On by default, and degrades gracefully when the optional native library isn't present.

      

    

  









  

    
Reference

    
Common config fields

    
Field names vary slightly by language convention (camelCase vs. snake_case vs. PascalCase); the shape is identical everywhere.

    

      
FieldRequiredNotes

      
        
publisherIDYesIdentifies your account in the ad auction.

        
gatewayURLYesDefaults to https://api.cognatu.com in every SDK.

        
gatewayAPIKey / apiKeyServer-side SDKs onlyAuthenticates auction calls, server-side secret, never shipped to a client/device.

        
persistWalletNoPersists the on-device privacy layer across app restarts (Keychain on iOS, EncryptedSharedPreferences on Android).

        
disableZkpWalletNoOpts out of the on-device privacy layer, on by default everywhere.