React Native (TypeScript)

npm install @react-native-async-storage/async-storage react-native-keychain \
  react-native-device-info react-native-get-random-values uuid
cd ios && pod install

import AsyncStorage from "@react-native-async-storage/async-storage";
import { Platform } from "react-native";
import * as Keychain from "react-native-keychain";
import { v4 as uuidv4 } from "uuid";

const SERVICE = "online.appmetrica.install-id";
const STORAGE_KEY = "am_install_id";

let cached: Promise<string> | null = null;

// Reads install_id or creates it on first launch. The promise is cached per process.
export function installId(): Promise<string> {
  cached ??= Platform.OS === "ios" ? fromKeychain() : fromStorage();
  return cached;
}

async function fromKeychain(): Promise<string> {
  const saved = await Keychain.getGenericPassword({ service: SERVICE });
  if (saved) return saved.password;
  const id = uuidv4();
  await Keychain.setGenericPassword("install_id", id, {
    service: SERVICE,
    // As in the iOS recipe: readable on background launches, never moves to a new device.
    accessible: Keychain.ACCESSIBLE.AFTER_FIRST_UNLOCK_THIS_DEVICE_ONLY,
  });
  return id;
}

async function fromStorage(): Promise<string> {
  const saved = await AsyncStorage.getItem(STORAGE_KEY);
  if (saved) return saved;
  const id = uuidv4();
  await AsyncStorage.setItem(STORAGE_KEY, id);
  return id;
}

import AsyncStorage from "@react-native-async-storage/async-storage";
import { Platform } from "react-native";

const ENDPOINT = "https://i.analytics.example.com/v1/events";
// Each platform of the app has its own key: the code picks it by OS at runtime.
const WRITE_KEY = Platform.select({
  ios: "pk_…", // iOS platform key from the Integration tab
  android: "pk_…", // Android platform key from the Integration tab
  default: "",
});
const QUEUE_KEY = "am_queue";
const MAX_BATCH = 500;
const MAX_AGE_MS = 7 * 24 * 3600 * 1000;
const TIMEOUT_MS = 15_000;

export type AnalyticsEvent = {
  insert_id: string;
  name: "session_start" | "session_end";
  timestamp: string;
  install_id: string;
  session_id: string;
  user_id?: string;
  duration_ms?: number;
  context: Record<string, string>;
};

type IngestResult = { rejected: { insert_id: string | null; retryable: boolean }[] };

let events: AnalyticsEvent[] = [];
let sending = false;
let stopped = false;
let retryAt = 0;
let backoffMs = 1000;

// The queue from previous launches is read once; every operation waits for it first.
const loaded = AsyncStorage.getItem(QUEUE_KEY)
  .then((saved) => {
    events = saved ? JSON.parse(saved) : [];
  })
  .catch(() => {});

function save(): Promise<void> {
  return AsyncStorage.setItem(QUEUE_KEY, JSON.stringify(events));
}

export async function enqueue(event: AnalyticsEvent): Promise<void> {
  await loaded;
  events.push(event);
  await save(); // disk first: the event survives the app being closed
  await flush();
}

export async function flush(): Promise<void> {
  await loaded;
  const minTime = Date.now() - MAX_AGE_MS;
  events = events.filter((e) => Date.parse(e.timestamp) >= minTime);
  if (sending || stopped || events.length === 0 || Date.now() < retryAt) return;
  sending = true;

  const batch = events.slice(0, MAX_BATCH);
  const sent = new Set(batch.map((e) => e.insert_id));
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
  try {
    const res = await fetch(ENDPOINT, {
      method: "POST",
      headers: { "Content-Type": "application/json", "X-App-Key": WRITE_KEY },
      // sent_at is this attempt's time: the server uses it to correct a skewed device clock.
      body: JSON.stringify({ sent_at: new Date().toISOString(), events: batch }),
      signal: controller.signal,
    });
    if (res.status === 200) {
      const result: IngestResult = await res.json();
      const retry = new Set(result.rejected.filter((r) => r.retryable).map((r) => r.insert_id));
      events = events.filter((e) => !sent.has(e.insert_id) || retry.has(e.insert_id));
      backoffMs = 1000;
      if (retry.size > 0) retryLater(60_000);
    } else if ([400, 413, 415].includes(res.status)) {
      events = events.filter((e) => !sent.has(e.insert_id)); // retrying won't help
    } else if (res.status === 401 || res.status === 403) {
      stopped = true; // key revoked or app archived
    } else if (res.status === 429 || res.status === 503) {
      retryLater((Number(res.headers.get("Retry-After")) || 5) * 1000);
    } else {
      backoff();
    }
  } catch {
    backoff(); // network error, timeout, unexpected response
  } finally {
    clearTimeout(timer);
    sending = false;
    await save();
  }
}

function backoff() {
  retryLater(backoffMs * (0.8 + Math.random() * 0.4));
  backoffMs = Math.min(backoffMs * 2, 300_000);
}

function retryLater(delayMs: number) {
  retryAt = Date.now() + delayMs;
  setTimeout(() => void flush(), delayMs);
}

import { Platform } from "react-native";
import DeviceInfo from "react-native-device-info";
import { v4 as uuidv4 } from "uuid";
import { installId } from "./installId";
import { type AnalyticsEvent, enqueue, flush } from "./queue";

let session: { id: string; startedAt: number } | null = null;
let userId: string | null = null;

function context(): Record<string, string> {
  const ios = Platform.OS === "ios";
  return {
    platform: ios ? "ios" : "android",
    os_name: DeviceInfo.getSystemName(),
    os_version: DeviceInfo.getSystemVersion(),
    app_version: DeviceInfo.getVersion(),
    app_build: DeviceInfo.getBuildNumber(),
    // On iOS, a machine name like iPhone17,3: the device name often contains the owner's name.
    device_model: ios
      ? DeviceInfo.getDeviceId()
      : `${DeviceInfo.getBrand()} ${DeviceInfo.getModel()}`,
    device_type: DeviceInfo.isTablet() ? "tablet" : "phone",
    locale: Intl.DateTimeFormat().resolvedOptions().locale,
    environment: __DEV__ ? "development" : "production",
  };
}

async function track(name: AnalyticsEvent["name"], sessionId: string, durationMs?: number) {
  // Time, user_id and context are captured when the event happens, not once install_id is read.
  const event = {
    insert_id: uuidv4(),
    name,
    timestamp: new Date().toISOString(),
    session_id: sessionId,
    user_id: userId ?? undefined, // undefined is left out of the JSON
    duration_ms: durationMs,
    context: context(),
  };
  await enqueue({ ...event, install_id: await installId() });
}

export const analytics = {
  start() {
    if (session) return;
    session = { id: uuidv4(), startedAt: performance.now() };
    void track("session_start", session.id);
  },

  end() {
    if (!session) return;
    const elapsed = Math.round(performance.now() - session.startedAt);
    void track("session_end", session.id, Math.min(Math.max(elapsed, 0), 86_400_000));
    session = null;
  },

  // Account ID from your backend, null after sign-out. Not an email or phone number.
  setUserId(id: string | null) {
    userId = id;
  },

  flush,
};

import { useEffect } from "react";
import { AppState } from "react-native";
import { analytics } from "./analytics";
import { RootNavigator } from "./navigation";

export default function App() {
  useEffect(() => {
    if (AppState.currentState === "active") analytics.start();
    const subscription = AppState.addEventListener("change", (state) => {
      if (state === "active") analytics.start();
      else if (state === "background") analytics.end();
    });
    return () => subscription.remove();
  }, []);

  return <RootNavigator />;
}