# Analytics Setup

Enable Native Notify analytics in your app — the analytics flags, what each one collects, and the privacy notes.

Analytics reporting is **opt-in**: every feature is off until you enable its flag. Set the flags once at module scope, or pass them to `registerNNPushToken` — the two merge.

## Enabling the flags

```js
import { NativeNotify } from "native-notify";

NativeNotify.init({
  appId: yourAppId,
  appToken: "yourAppToken",
  analytics: {
    screens: true,   // screen views ("which screens do users use most")
    sessions: true,  // foreground session length
    opens: true,     // push-notification open reporting
    deviceId: true,  // stable device id (see below)
  },
});
```

Or, if you prefer to keep everything on the registration call:

```js
import registerNNPushToken from "native-notify";

export default function App() {
  registerNNPushToken(yourAppId, "yourAppToken", {
    analytics: { screens: true, sessions: true, opens: true, deviceId: true },
  });
  // ...
}
```

Requires **native-notify v5.1+** (`npm install native-notify@latest`).

## What each flag does

| Flag       | Collected                                                          | Notes                                                                                                                                                               |
| ---------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `screens`  | Screen name + timestamp per view; device context                   | Only when you call `trackScreen()` or use `useNativeNotifyScreenTracking()`. See [Screen Tracking](/docs/analytics/screens).                                        |
| `sessions` | Session start/end, duration                                        | Wired automatically by `registerNNPushToken` — a session starts when the app opens, ends when it backgrounds.                                                       |
| `opens`    | Which notification was tapped                                      | Read from the server-injected `nn_notification_id` in the push payload; report is deduplicated so one tap counts once.                                              |
| `deviceId` | A stable device identifier with registrations and analytics events | Uses `expo-application` if installed: iOS `getIosIdForVendorAsync()` (IDFV) / Android `getAndroidId()`. Without it, unique counts fall back to the Expo push token. |

## What gets sent, and when

- **Registration enrichment** — with `deviceId` on, registrations also carry the device id, your app version (`expo-constants`), and the device timezone. App version and timezone are sent regardless of the flag; they are not identifiers.
- **Analytics events** are best-effort: requests have a 10-second timeout, are batched/throttled, and a failure never throws into your app. You can call `flushScreenQueue()` to force a flush (the SDK does this automatically when a session ends).
- **Device context** on events uses the stable device id when available, then the Expo push token. This is what makes "unique users" survive Expo-token rotation.

## Privacy notes

- No personal data is sent: screen names, event counts, a device identifier, app version, and timezone only.
- Everything is first-party — the data goes to your Native Notify app and shows on your dashboard.
- Retention: raw app-open activity is kept for 365 days; screen-view data for 365 days (per-device dedupe rows 90 days); session and open events for 365 days. Aggregated daily rollups keep the long-range charts working after that.
- Turning a flag off stops that collection on the next app run; already-collected counts remain until they age out of the retention windows.

## Custom API reporting

If you are not using the native-notify SDK (or want server-side reporting), the ingestion endpoints are plain HTTP — see the [Analytics API reference](/docs/analytics/api).