@tryappdata/react-native 0.1.0

package/README.md

@@ -0,0 +1,78 @@
+# @tryappdata/react-native
+
+Drop-in **Live Users** SDK for React Native. Your real users light up the
+appdata globe, live and worldwide — with **no location permission**, no
+cookies, and no PII unless you explicitly pass an avatar.
+
+## Install
+
+```bash
+npm i @tryappdata/react-native
+# recommended (persists the anon id across launches so appdata can tell
+# new vs returning users):
+npm i @react-native-async-storage/async-storage
+```
+
+## Use
+
+```ts
+import { appdata } from '@tryappdata/react-native'
+
+// once, at app root
+appdata.init({ key: 'pk_…', appVersion: '2.3.1' })
+```
+
+That's the whole required integration. The SDK creates an anonymous id,
+then heartbeats every 60s **only while the app is foregrounded** (it
+pauses in the background and resumes on return) — you write none of that.
+
+Optional:
+
+```ts
+// when the visible screen changes — founders see this verbatim
+appdata.screen('Paywall')
+
+// attach a logged-in user's avatar (pass only with consent)
+appdata.identify({ id: user.id, avatarUrl: user.photoURL })
+
+// back to anonymous, e.g. on logout
+appdata.reset()
+```
+
+## What's sent
+
+`{ key, anonId, platform, appVersion?, screen?, avatarUrl? }` to
+`POST <host>/api/ingest/presence`. Country/city are derived **server-side
+from the request IP and the IP is discarded** — the SDK never sends or
+sees a location, and never asks for a location permission.
+
+## Privacy & consent
+
+**You are the data controller for your end-users.** The SDK is anonymous
+by default — no IP, location, cookies, or device id ever leave the
+device, and it requests **no location permission** (country is derived
+server-side from the request IP, which is then discarded).
+
+If you call `identify`:
+
+- pass `avatarUrl` **only with the user's consent**;
+- **never** pass emails, names, or other PII in any field;
+- gate `init` behind your own consent flow where your jurisdiction
+  requires it.
+
+The `pk_…` key is **public by design** (like a Segment/PostHog write
+key): write-only presence for one app, no read access, no secrets.
+
+## Config
+
+| Field        | Required | Notes                                            |
+|--------------|----------|--------------------------------------------------|
+| `key`        | yes      | Public ingest key (`pk_…`) from the dashboard.   |
+| `appVersion` | no       | Your app version; shown to you as exact data.    |
+| `host`       | no       | Override the appdata origin (defaults to prod).  |
+| `debug`      | no       | Log heartbeat failures to the console.           |
+
+Pings are fire-and-forget and never throw into your app. ~1 tiny request
+per minute while foregrounded → negligible battery/data.
+
+Full wire spec: [`../LIVE-USERS-CONTRACT.md`](../LIVE-USERS-CONTRACT.md).

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+export interface AppdataConfig {
+    /** Public per-app ingest key (`pk_…`) from the appdata dashboard. */
+    key: string;
+    /** Your app's version, e.g. "2.3.1". Shown to founders as exact data. */
+    appVersion?: string;
+    /** Override the appdata origin (defaults to production). */
+    host?: string;
+    /** Log heartbeat failures to the console. Off by default. */
+    debug?: boolean;
+}
+export interface AppdataIdentify {
+    /** Your own user id — reserved for future cross-reference; not stored yet. */
+    id?: string;
+    /** Avatar URL for this logged-in user. Pass only with user consent. */
+    avatarUrl?: string;
+}
+declare class Appdata {
+    private key;
+    private host;
+    private appVersion;
+    private debug;
+    private anonId;
+    private screenName;
+    private avatarUrl;
+    private timer;
+    private started;
+    init(config: AppdataConfig): void;
+    identify(traits: AppdataIdentify): void;
+    /** Call when the visible screen changes — shown to founders verbatim. */
+    screen(name: string): void;
+    /** Back to anonymous (e.g. on logout). */
+    reset(): void;
+    private onAppState;
+    private startTimer;
+    private stopTimer;
+    private resolveAnonId;
+    private beat;
+}
+export declare const appdata: Appdata;
+export default appdata;

package/dist/index.js

@@ -0,0 +1,161 @@
+var _a;
+/**
+ * appdata Live Users SDK — React Native.
+ *
+ * One init call. The SDK then heartbeats the appdata ingest endpoint
+ * every 60s **while the app is foregrounded**, so the customer's real
+ * users light up the appdata globe live. No location permission (geo is
+ * derived server-side from IP and discarded), no cookies, no PII unless
+ * the customer explicitly passes an avatar via identify().
+ *
+ *   import { appdata } from '@tryappdata/react-native'
+ *   appdata.init({ key: 'pk_…', appVersion: '2.3.1' })
+ *   appdata.screen('Paywall')                 // optional, when it changes
+ *   appdata.identify({ avatarUrl })           // optional, logged-in users
+ *   appdata.reset()                           // optional, on logout
+ */
+import { Platform, AppState } from "react-native";
+/** The appdata production origin. Override per-call via `init({ host })`. */
+const DEFAULT_HOST = "https://tryappdata.com";
+const HEARTBEAT_MS = 60000;
+const STORAGE_KEY = "appdata_anon";
+// AsyncStorage is optional. With it, the anon id (and thus accurate
+// new-vs-returning) persists across launches; without it the id is
+// per-process — the SDK still works, it just can't tell "returning".
+let storage = null;
+try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const mod = require("@react-native-async-storage/async-storage");
+    storage = ((_a = mod === null || mod === void 0 ? void 0 : mod.default) !== null && _a !== void 0 ? _a : mod);
+}
+catch {
+    storage = null;
+}
+function uuid() {
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+function platform() {
+    if (Platform.OS === "ios")
+        return "ios";
+    if (Platform.OS === "android")
+        return "android";
+    return "web";
+}
+class Appdata {
+    constructor() {
+        this.key = null;
+        this.host = DEFAULT_HOST;
+        this.debug = false;
+        this.anonId = null;
+        this.timer = null;
+        this.started = false;
+        this.onAppState = (state) => {
+            if (state === "active") {
+                this.beat();
+                this.startTimer();
+            }
+            else {
+                this.stopTimer();
+            }
+        };
+    }
+    init(config) {
+        var _a;
+        if (this.started)
+            return;
+        if (!(config === null || config === void 0 ? void 0 : config.key)) {
+            if (config === null || config === void 0 ? void 0 : config.debug)
+                console.warn("[appdata] init: missing `key`");
+            return;
+        }
+        this.key = config.key;
+        this.host = ((_a = config.host) !== null && _a !== void 0 ? _a : DEFAULT_HOST).replace(/\/+$/, "");
+        this.appVersion = config.appVersion;
+        this.debug = !!config.debug;
+        this.started = true;
+        void this.resolveAnonId().then(() => {
+            this.beat();
+            this.startTimer();
+        });
+        AppState.addEventListener("change", this.onAppState);
+    }
+    identify(traits) {
+        if (traits.avatarUrl && /^https:\/\//.test(traits.avatarUrl)) {
+            this.avatarUrl = traits.avatarUrl;
+        }
+        this.beat();
+    }
+    /** Call when the visible screen changes — shown to founders verbatim. */
+    screen(name) {
+        this.screenName = name;
+        this.beat();
+    }
+    /** Back to anonymous (e.g. on logout). */
+    reset() {
+        this.avatarUrl = undefined;
+        this.beat();
+    }
+    startTimer() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.beat(), HEARTBEAT_MS);
+    }
+    stopTimer() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    async resolveAnonId() {
+        if (this.anonId)
+            return;
+        try {
+            const existing = storage ? await storage.getItem(STORAGE_KEY) : null;
+            if (existing) {
+                this.anonId = existing;
+                return;
+            }
+        }
+        catch {
+            /* fall through to fresh id */
+        }
+        this.anonId = uuid();
+        try {
+            if (storage)
+                await storage.setItem(STORAGE_KEY, this.anonId);
+        }
+        catch {
+            /* in-memory only this process — acceptable */
+        }
+    }
+    beat() {
+        if (!this.key || !this.anonId)
+            return;
+        const body = {
+            key: this.key,
+            anonId: this.anonId,
+            platform: platform(),
+        };
+        if (this.appVersion)
+            body.appVersion = this.appVersion;
+        if (this.screenName)
+            body.screen = this.screenName;
+        if (this.avatarUrl)
+            body.avatarUrl = this.avatarUrl;
+        // Fire-and-forget; a presence ping must never affect the host app.
+        fetch(`${this.host}/api/ingest/presence`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+        }).catch((err) => {
+            if (this.debug)
+                console.warn("[appdata] heartbeat failed", err);
+        });
+    }
+}
+export const appdata = new Appdata();
+export default appdata;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@tryappdata/react-native",
+  "version": "0.1.0",
+  "description": "appdata Live Users SDK for React Native — drop-in real-user presence for the appdata globe. No location permission, no PII.",
+  "license": "MIT",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "react-native": "src/index.ts",
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "appdata",
+    "react-native",
+    "presence",
+    "live-users",
+    "analytics"
+  ],
+  "peerDependencies": {
+    "react": ">=17",
+    "react-native": ">=0.64"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,185 @@
+/**
+ * appdata Live Users SDK — React Native.
+ *
+ * One init call. The SDK then heartbeats the appdata ingest endpoint
+ * every 60s **while the app is foregrounded**, so the customer's real
+ * users light up the appdata globe live. No location permission (geo is
+ * derived server-side from IP and discarded), no cookies, no PII unless
+ * the customer explicitly passes an avatar via identify().
+ *
+ *   import { appdata } from '@tryappdata/react-native'
+ *   appdata.init({ key: 'pk_…', appVersion: '2.3.1' })
+ *   appdata.screen('Paywall')                 // optional, when it changes
+ *   appdata.identify({ avatarUrl })           // optional, logged-in users
+ *   appdata.reset()                           // optional, on logout
+ */
+import { Platform, AppState, type AppStateStatus } from "react-native"
+
+/** The appdata production origin. Override per-call via `init({ host })`. */
+const DEFAULT_HOST = "https://tryappdata.com"
+const HEARTBEAT_MS = 60_000
+const STORAGE_KEY = "appdata_anon"
+
+export interface AppdataConfig {
+  /** Public per-app ingest key (`pk_…`) from the appdata dashboard. */
+  key: string
+  /** Your app's version, e.g. "2.3.1". Shown to founders as exact data. */
+  appVersion?: string
+  /** Override the appdata origin (defaults to production). */
+  host?: string
+  /** Log heartbeat failures to the console. Off by default. */
+  debug?: boolean
+}
+
+export interface AppdataIdentify {
+  /** Your own user id — reserved for future cross-reference; not stored yet. */
+  id?: string
+  /** Avatar URL for this logged-in user. Pass only with user consent. */
+  avatarUrl?: string
+}
+
+interface OptionalStorage {
+  getItem(k: string): Promise<string | null>
+  setItem(k: string, v: string): Promise<void>
+}
+
+// AsyncStorage is optional. With it, the anon id (and thus accurate
+// new-vs-returning) persists across launches; without it the id is
+// per-process — the SDK still works, it just can't tell "returning".
+let storage: OptionalStorage | null = null
+try {
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const mod = require("@react-native-async-storage/async-storage")
+  storage = (mod?.default ?? mod) as OptionalStorage
+} catch {
+  storage = null
+}
+
+function uuid(): string {
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0
+    const v = c === "x" ? r : (r & 0x3) | 0x8
+    return v.toString(16)
+  })
+}
+
+function platform(): "ios" | "android" | "web" {
+  if (Platform.OS === "ios") return "ios"
+  if (Platform.OS === "android") return "android"
+  return "web"
+}
+
+class Appdata {
+  private key: string | null = null
+  private host = DEFAULT_HOST
+  private appVersion: string | undefined
+  private debug = false
+  private anonId: string | null = null
+  private screenName: string | undefined
+  private avatarUrl: string | undefined
+  private timer: ReturnType<typeof setInterval> | null = null
+  private started = false
+
+  init(config: AppdataConfig): void {
+    if (this.started) return
+    if (!config?.key) {
+      if (config?.debug) console.warn("[appdata] init: missing `key`")
+      return
+    }
+    this.key = config.key
+    this.host = (config.host ?? DEFAULT_HOST).replace(/\/+$/, "")
+    this.appVersion = config.appVersion
+    this.debug = !!config.debug
+    this.started = true
+
+    void this.resolveAnonId().then(() => {
+      this.beat()
+      this.startTimer()
+    })
+
+    AppState.addEventListener("change", this.onAppState)
+  }
+
+  identify(traits: AppdataIdentify): void {
+    if (traits.avatarUrl && /^https:\/\//.test(traits.avatarUrl)) {
+      this.avatarUrl = traits.avatarUrl
+    }
+    this.beat()
+  }
+
+  /** Call when the visible screen changes — shown to founders verbatim. */
+  screen(name: string): void {
+    this.screenName = name
+    this.beat()
+  }
+
+  /** Back to anonymous (e.g. on logout). */
+  reset(): void {
+    this.avatarUrl = undefined
+    this.beat()
+  }
+
+  private onAppState = (state: AppStateStatus): void => {
+    if (state === "active") {
+      this.beat()
+      this.startTimer()
+    } else {
+      this.stopTimer()
+    }
+  }
+
+  private startTimer(): void {
+    if (this.timer) return
+    this.timer = setInterval(() => this.beat(), HEARTBEAT_MS)
+  }
+
+  private stopTimer(): void {
+    if (this.timer) {
+      clearInterval(this.timer)
+      this.timer = null
+    }
+  }
+
+  private async resolveAnonId(): Promise<void> {
+    if (this.anonId) return
+    try {
+      const existing = storage ? await storage.getItem(STORAGE_KEY) : null
+      if (existing) {
+        this.anonId = existing
+        return
+      }
+    } catch {
+      /* fall through to fresh id */
+    }
+    this.anonId = uuid()
+    try {
+      if (storage) await storage.setItem(STORAGE_KEY, this.anonId)
+    } catch {
+      /* in-memory only this process — acceptable */
+    }
+  }
+
+  private beat(): void {
+    if (!this.key || !this.anonId) return
+    const body: Record<string, string> = {
+      key: this.key,
+      anonId: this.anonId,
+      platform: platform(),
+    }
+    if (this.appVersion) body.appVersion = this.appVersion
+    if (this.screenName) body.screen = this.screenName
+    if (this.avatarUrl) body.avatarUrl = this.avatarUrl
+
+    // Fire-and-forget; a presence ping must never affect the host app.
+    fetch(`${this.host}/api/ingest/presence`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    }).catch((err) => {
+      if (this.debug) console.warn("[appdata] heartbeat failed", err)
+    })
+  }
+}
+
+export const appdata = new Appdata()
+export default appdata