---
name: agenthog-integrate
description: Install AgentHog analytics into a web app, a React Native / Expo app, a Capacitor hybrid app, or a Unity game, send server-side events from a backend, name events the way the AgentHog contract requires, and verify data is arriving. Use when adding analytics to a project, instrumenting events or conversions, relaying webhooks or backfilling history into analytics, or when AgentHog, ah.js, @brightmotion/agenthog-react-native, @brightmotion/agenthog-capacitor, or com.brightmotion.agenthog is mentioned.
when_to_use: The user asks to "add analytics", "set up AgentHog", "track signups", "instrument this app/game", "track subscriptions/revenue", "send events from our backend", "why is AgentHog not receiving events", or names any AgentHog package (including a Capacitor/Ionic app).
---
# Integrate AgentHog
AgentHog is web + mobile analytics with an agent-readable CLI. Integrating it means:
picking the right SDK for the project, wiring it in once, and confirming events land.
Most of the value is in **autocapture** — you do not hand-instrument pageviews, clicks,
forms, or scroll depth. Add the SDK, then add custom events only for things autocapture
cannot see (server-side outcomes, purchases, feature usage).
## 1. Get a project key
Every install needs a project key shaped `ah_xxxxxxxx`. If the user has not given you one:
- Ask them to create a project at `http://agenthog.io/projects/new` and paste the key, or
- If the `ah` CLI is installed and authenticated, run `ah projects list` and use an existing key.
Project creation is capped by plan (Free: 1 project). If `/projects/new` shows an upgrade
notice instead of the create form, the account is at its cap — stop and let the user
either reuse an existing project's key or upgrade; there is nothing to integrate
without a key.
Do not invent a key and do not proceed without one — the tracker silently disables itself
when `data-project` is missing.
## 2. Pick the platform
Inspect the repo before choosing:
- `ProjectSettings/ProjectVersion.txt` or a `Packages/manifest.json` with `com.unity.*`
dependencies → it is a **Unity game** (§5)
- `package.json` with `react-native` or `expo` → **React Native install** (§4)
- `capacitor.config.ts` / `capacitor.config.json` (or `@capacitor/core` in package.json)
→ a **Capacitor hybrid app** (§6). Check this BEFORE the web rule — a Capacitor repo
serves HTML too, but the web tag inside its WebView misclassifies every session.
A `config.xml` with Cordova and NO Capacitor config is a **legacy Cordova app** the SDK
does not target; if it is mid-migration to Capacitor, instrument the Capacitor version.
- anything else that serves HTML (Next.js, Astro, Remix/React Router, Rails, plain HTML) → **web install** (§3)
A repo can need both (marketing site + mobile app/game). They are separate projects in
AgentHog — use a different project key for each, so their stats stay clean.
Events that no client can witness — a billing webhook, a queue worker, a backfill of
existing history — are not an SDK install at all; they go straight to the ingest endpoint
from the backend (§7).
## 3. Web install
One script tag, before ``, on every page:
```html
```
Put it wherever that framework renders `` site-wide — `app/layout.tsx` (Next.js App
Router), `pages/_document.tsx` (Pages Router), `app/root.tsx` (React Router / Remix),
`src/layouts/*.astro` (Astro), the shared layout template otherwise. Do not add it per-page.
Optional attributes:
| attribute | when you need it |
|---|---|
| `data-api="https://your-agenthog.example"` | self-hosted backend on a different origin than the script |
| `data-cookie-domain=".example.com"` | share one visitor id across subdomains (`www.` and `app.`) |
What you get with no further work: pageviews (including SPA route changes — `pushState`,
`replaceState`, and `popstate` are all hooked), clicks, form submits, input focus, scroll
depth at 25/50/75/90/100%, and a `leave` event carrying time-on-page and max scroll.
The global API for custom work is `window.agenthog`:
```js
window.agenthog.capture('checkout_completed', { plan: 'pro', cents: 4900 })
window.agenthog.identify('user@example.com', { plan: 'pro' }) // email = cross-device stitch key
window.agenthog.tag('beta_cohort', true)
window.agenthog.register({ app_version: '2.1.0' }) // merged into every later event
```
Guard these behind a `typeof window !== 'undefined' && window.agenthog` check in SSR
frameworks — the object only exists in the browser, after the script runs.
## 4. React Native / Expo install
```bash
npm i @brightmotion/agenthog-react-native
npx expo install @react-native-async-storage/async-storage # for persistent ids
```
**Always pass `storage`.** It is not auto-detected, and omitting it is silent data loss,
not a crash: ids and the queued event buffer stay in memory, so every app restart looks
like a brand-new visitor and returning-user metrics are wrong. Use `asyncStorage` from the
subpath, or any `{ getItem, setItem, removeItem }` adapter returning promises (MMKV,
SQLite). The subpath import is what pulls the optional peer into the bundle — importing it
without installing AsyncStorage fails the Metro build.
Wrap the app at its root — in Expo Router that is `app/_layout.tsx`, inside any gesture-handler
root and outside the navigator:
```tsx
import { AgentHogProvider } from '@brightmotion/agenthog-react-native'
import { asyncStorage } from '@brightmotion/agenthog-react-native/async-storage'
{children}
```
The `npm i` above installs the current SDK, which is what the `/async-storage` subpath
needs. Much older releases (before 0.2.1) had no such subpath and tried to locate
AsyncStorage themselves — a lazy require Metro cannot resolve statically, producing a fatal
redbox (`Requiring unknown module`) that no `try/catch` suppresses. Upgrade rather than work
around it; if a project is stuck on one of those, pass the peer straight through:
`import AsyncStorage from '@react-native-async-storage/async-storage'` → `storage: AsyncStorage`.
Put the key in `.env` as `EXPO_PUBLIC_AGENTHOG_KEY=ah_xxxxxxxx`. The `enabled` gate above is
the idiom for keeping analytics off in local dev and in forks that have no key.
Screen views are not automatic — the SDK cannot know your router. Feed it a pathname from
whatever router the app uses:
```tsx
import { usePathname } from 'expo-router'
import { useScreenTracking } from '@brightmotion/agenthog-react-native'
useScreenTracking(usePathname()) // emits `pageview: ` + a `leave` for the previous screen
```
React Navigation has no `usePathname`; derive it from the navigation state
(`useNavigationContainerRef().getCurrentRoute()?.name`) and pass that.
Then, anywhere inside the provider:
```tsx
const ah = useAgentHog()
ah.capture('photo_sent', { recipients: 3 })
ah.identify(email, { clerk_id: user.id })
ah.reset() // sign-out: new anon id + session
```
Tap autocapture is on by default (fiber walk → `click: