# nohmo
Official analytics SDK for [Nohmo](https://www.nohmo.in) — device tracking, session journeys, UTM attribution, and real-time event streaming for React, Next.js, and plain HTML / Django templates.
## Install
```bash
# Web (React / Next.js)
npm install nohmo
# React Native (iOS & Android)
npm install nohmo
# Optional — recommended for persisting device identity across app restarts
npm install @react-native-async-storage/async-storage
```
## Quick start
### Next.js (App Router)
```tsx
// app/layout.tsx
import { NohmoNextProvider } from 'nohmo'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
Page views, time spent, scroll depth, and clicks are tracked automatically from this point.
```env
NEXT_PUBLIC_NOHMO_PROJECT_ID=proj_xxxx
NEXT_PUBLIC_NOHMO_API_KEY=pk_xxxx
```
### Next.js (Pages Router)
```tsx
// pages/_app.tsx
import { NohmoProvider } from 'nohmo'
import type { AppProps } from 'next/app'
export default function App({ Component, pageProps }: AppProps) {
return (
)
}
```
### Plain React (Vite, CRA)
```tsx
import { NohmoProvider } from 'nohmo'
function App() {
return (
)
}
```
No automatic route-change tracking — use `usePageView('/path')` in each page component or call `send('PAGE_VIEW', …)` manually on route changes.
### Plain HTML / Django templates (no build step)
Add one script tag. No npm, no bundler, no build step required.
```html
```
That's it. Page views, clicks, scroll depth, time spent, and rage-clicks are tracked automatically the moment the script loads.
**Track custom events from any inline script:**
```html
```
**Identify users (e.g. in a Django template after login):**
```html
{% if user.is_authenticated %}
{% endif %}
```
`window.nohmo` is available as soon as the script finishes loading (`defer` guarantees it runs after the DOM is ready). For inline scripts that run before the page finishes loading, use `window.addEventListener('load', () => { window.nohmo.send(...) })`.
---
## Track custom events
```tsx
import { useNohmo } from 'nohmo'
export default function BuyButton({ item }: { item: { id: string; price: number } }) {
const { send } = useNohmo()
return (
)
}
```
Events are queued in memory and flushed as a batch every `flushInterval` ms via `navigator.sendBeacon` (falling back to `fetch`). They survive page unload and never block the main thread.
## Identify users after login
```tsx
import { useNohmo } from 'nohmo'
export default function LoginForm() {
const { linkUser } = useNohmo()
const handleLogin = async () => {
const user = await loginAPI()
await linkUser(user.id, user.email, { plan: user.plan })
}
return
}
```
Every event fired before `linkUser()` — including across previous sessions — is retroactively attached to the user on the backend. Nothing is lost.
Once a user is linked, their identity persists. If they visit from a different device and call `linkUser()` again with the same ID, their profile and metadata are automatically merged.
## Manual page view hook
```tsx
import { usePageView } from 'nohmo'
export default function MyPage() {
usePageView('/my-page') // fires PAGE_VIEW once on mount
return
…
}
```
---
## React Native (iOS & Android)
Nohmo includes a first-party React Native SDK under `nohmo/react-native`. One package, two platforms.
### Setup
```bash
npm install nohmo
# Recommended — persists device identity across app restarts
npm install @react-native-async-storage/async-storage
```
The SDK works out of the box with no additional dependencies. Without `@react-native-async-storage/async-storage` a new device ID is generated on every cold start.
```tsx
// App.tsx
import { NohmoProvider } from 'nohmo/react-native'
import AsyncStorage from '@react-native-async-storage/async-storage'
export default function App() {
return (
)
}
```
If you skip `storage`, everything works — events are tracked, screens are recorded, users can be identified — you just won't get returning-device recognition after an app kill.
### What gets tracked automatically
| Event | Trigger |
|-------|---------|
| `APP_INSTALL` | First time the app ever opens |
| `APP_OPEN` | Every time the app becomes active |
| `APP_BACKGROUND` | When the app goes to background, with session duration |
| `TIME_SPENT` | When leaving a screen or backgrounding the app, with seconds on the screen |
| `JS_ERROR` | A non-fatal JS error caught by the global handler, with message + stack |
| `APP_CRASH` | A fatal JS crash — persisted and reported on the next app launch, attributed to the session it happened in |
| `INSTALL_ATTRIBUTED` | Attribution resolved on first open — Play Store referrer on Android, system pasteboard on iOS (built-in, no extra packages) |
### Track screens automatically
The Babel plugin handles this too — no prop changes needed. It detects `` in your JSX and injects `onStateChange` and `onReady` at compile time:
```jsx
// You write this (unchanged):
// Plugin compiles it to:
```
Everything is driven by the single `plugins: ['nohmo/babel-plugin']` line in `babel.config.js`. No manual prop wiring.
**Manual tracking** — if you prefer per-screen control without the plugin:
```tsx
import { useScreenView } from 'nohmo/react-native'
export default function HomeScreen() {
useScreenView('Home') // fires SCREEN_VIEW on mount
return …
}
```
### Custom events
```tsx
const { send } = useNohmo()
send('button_tapped', { buttonId: 'cta_signup' })
send('checkout_started', { cartValue: 49.99 })
```
### Identify users
```tsx
const { linkUser } = useNohmo()
// After login
await linkUser(user.id, user.email, { plan: user.plan })
```
### Track conversions
```tsx
const { trackConversion } = useNohmo()
trackConversion('user_created')
trackConversion('purchase', { amount: 29.99, currency: 'USD' })
```
### Uninstall detection
Nohmo detects app uninstalls using the same silent-push technique used by AppsFlyer and Adjust.
**1. Upload your Firebase Service Account JSON** in **Settings → App** in your Nohmo dashboard.
**2. Install Firebase Messaging:**
```bash
npm install @react-native-firebase/app @react-native-firebase/messaging
```
**3. Register the push token — one component, zero ongoing maintenance:**
```tsx
import { useNohmo } from 'nohmo/react-native'
import messaging from '@react-native-firebase/messaging'
function PushTokenRegistrar() {
const { registerPushToken } = useNohmo()
useEffect(() => {
messaging().getToken().then(registerPushToken)
return messaging().onTokenRefresh(registerPushToken) // handles token rotation
}, [])
return null
}
```
**How it works:**
- Every night at **03:00 UTC**, Nohmo sends a silent data-only FCM message to every device that hasn't opened the app in 24h
- If FCM returns `NotRegistered` → app was uninstalled → device is marked automatically
- No code needed after the one-time setup
- Results in **App Analytics → Uninstalls** with daily chart, uninstall rate, and D1/D7/D30 retention
**Accuracy:** ~85–90% — users with push notifications disabled cannot be detected (same limitation as every major analytics SDK).
### React Native options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `appVersion` | `string` | `''` | App version string sent with every event |
| `flushInterval` | `number` | `5000` | Milliseconds between batch event flushes |
| `debug` | `boolean` | `false` | Log all SDK activity to the console |
| `autoAppLifecycle` | `boolean` | `true` | Auto-track `APP_OPEN` and `APP_BACKGROUND` on foreground/background transitions |
| `autoErrors` | `boolean` | `true` | Capture JS errors (`JS_ERROR`) and crashes (`APP_CRASH`) — including native Android/iOS crashes |
| `storage` | `NohmoStorage` | in-memory | Provide an AsyncStorage-compatible object to persist device identity across app restarts. Pass `AsyncStorage` from `@react-native-async-storage/async-storage`. Without this, a new device ID is generated on every cold start. |
### Autocapture (press events)
Add one line to your Babel config and every `onPress` / `onLongPress` in your app is tracked automatically — no code changes per screen.
```js
// babel.config.js
module.exports = {
presets: ['module:@react-native/babel-preset'],
plugins: ['nohmo/babel-plugin'], // ← add this
}
```
That's it. The plugin rewrites this at build time:
```jsx
// What you write
Buy now
```
```jsx
// What gets compiled (you never see this)
Buy now
```
**What gets captured automatically:**
| Event | Trigger |
|-------|---------|
| `PRESS` | Any `onPress` tap |
| `LONG_PRESS` | Any `onLongPress` |
Each event includes `component` (e.g. `Pressable`), `text` (button label if it's a static string), `file`, and `line`.
**What it doesn't capture:** dynamic text from variables/state, `onPressIn`/`onPressOut` (intentionally excluded — too noisy), or press handlers inside `node_modules`.
### Install attribution (Android + iOS)
Nohmo uses the same deterministic attribution mechanism as AppsFlyer and Adjust. On Android, a click UUID is embedded in the Play Store referrer param. On iOS, the click-link interstitial writes the UUID to the system pasteboard, which the SDK reads on first open. No GAID or fingerprinting required on either platform.
**How it works end-to-end:**
1. **Build a tracking link** in **Settings → App → Attribution Link Builder** in your Nohmo dashboard. Fill in your UTM fields and copy the generated link:
```
https://www.nohmo.in/api/click//?utm_source=facebook&utm_medium=cpc&utm_campaign=summer
```
Click **Save & shorten** to store the link and get a tidy short URL (`https://www.nohmo.in/api/l/`) you can reuse from the **Saved links** list.
2. **Use the link in your ad.** When a user clicks it, Nohmo records the click and routes them to the correct store:
- **Android:** redirects to your Play Store URL with the click UUID in the referrer param — Google Play delivers this to the app on first open.
- **iOS:** serves a brief interstitial page that writes the click UUID to the system pasteboard, then redirects to your App Store URL — the SDK reads and clears it on first open.
3. **No extra setup needed.** Attribution is built into the Nohmo SDK — the SDK reads the Play Store referrer (Android) or system pasteboard (iOS) automatically on first open and sends it to the backend for matching. **Zero code needed in your app.**
4. **Results appear** in **App Analytics → Install Attribution** with a breakdown by source, campaign, and match type.
**Attribution priority:**
| Priority | Method | Accuracy |
|----------|--------|----------|
| 1 (Android) | `nohmo_click` UUID in Play Store referrer | 100% deterministic |
| 1 (iOS) | `nohmo_click` UUID in system pasteboard | 100% deterministic |
| 2 | GAID / IDFA match | Deterministic |
| 3 | UTMs in referrer (no click ID) | High |
| 4 | IP + platform within 24h | Probabilistic |
| 5 | No match | Organic |
> **iOS note:** The App Store has no referrer param, so iOS uses the system pasteboard — deterministic when the user taps through the click interstitial — with GAID/IDFA and probabilistic IP matching as fallbacks.
### Attribution via deep links
Pass UTM params in your deep link URL and the SDK captures them automatically:
```
yourapp://open?utm_source=meta&utm_medium=cpc&utm_campaign=summer
```
Attribution appears in **Traffic → Conversions** and is linked to every event in that session.
### Invite a friend (referral attribution)
Want installs from in-app sharing — "invite a friend" — attributed back to the user who shared? Share a Nohmo link instead of the raw store URL. `buildInviteLink()` returns a **short** link that carries the current user's id, so you can see exactly who referred whom.
```tsx
import { Share } from 'react-native'
import { useNohmo } from 'nohmo/react-native'
function InviteButton() {
const { buildInviteLink } = useNohmo()
const invite = async () => {
const link = await buildInviteLink({ channel: 'whatsapp' })
// → https://www.nohmo.in/api/l/aB3xK9q
await Share.share({ message: `Join me on the app! ${link}` })
}
return
}
```
- **Call `linkUser()` first** — the sharer's id is captured as `utm_content`. Without it the link is a generic referral link with no referrer.
- **Returns a short URL** (`/api/l/`). The same user + options always resolves to the same code, and it's cached, so repeated shares never create duplicate links. Offline, it falls back to the full click URL.
- **Options:** `channel` → `utm_medium` (e.g. `'whatsapp'`), `campaign` → `utm_campaign`, `source` → `utm_source` (defaults to `'referral'`).
When the invitee installs through the link, their device's attribution shows the sharer's id — **deterministic on Android** (Play Install Referrer), **best-effort on iOS** (pasteboard when they tap through the click interstitial, probabilistic otherwise). Requires your **iOS App Store URL** to be set in **Settings → App**. Results appear in **App Analytics → Install Attribution** and on each device's **Came from** card.
---
## Track conversions
Conversions let you measure what matters — signups, deposits, purchases — and see exactly which traffic source (Google Ads, Meta Ads, organic, etc.) drove each one.
### 1. Define goals in the dashboard
Go to **Settings → Conversions** and create a goal. Each goal has a human-readable name and a slug you reference in code:
| Name | Slug |
|------|------|
| User Created | `user_created` |
| Money Deposit | `money_deposit` |
| Subscription Started | `subscription_started` |
### 2. Call `trackConversion()` in your code
```tsx
import { useNohmo } from 'nohmo'
export default function SignupSuccess() {
const { trackConversion } = useNohmo()
useEffect(() => {
trackConversion('user_created')
}, [])
}
```
Pass optional properties for richer data:
```tsx
trackConversion('money_deposit', { amount: 500, currency: 'USD' })
```
**Plain HTML / Django templates:**
```html
```
### 3. See results in Traffic → Conversions
The **Traffic** page has a **Conversions** tab showing total conversions broken down by UTM source, medium, campaign, and custom attribution parameters. Filter by a specific goal to drill into which channels drive that conversion type.
Attribution is automatic — if the user arrived via `?utm_source=google&utm_medium=cpc`, that conversion is attributed to Google CPC with no extra code.
---
## What gets tracked automatically
| Event | Trigger | Data |
|-------|---------|------|
| `PAGE_VIEW` | Every route change (Next.js) or `usePageView()` | `page`, `referrer` |
| `TIME_SPENT` | When navigating away from a page | `seconds` |
| `SCROLL_DEPTH` | At 25 / 50 / 75 / 100% scroll milestones | `depth` |
| `CLICK` | Click on any interactive element | `tag`, `text`, `href` |
| `RAGE_CLICK` | Three or more rapid clicks in the same spot | `tag`, `text` |
| `FORM_SUBMIT` | Submission of any `