Mobile and desktop apps

This is the wire contract between any Analisa SDK (web, React Native/Expo, Electron/Tauri, Flutter, Swift, Kotlin, or your own HTTP client) and the ingestor. One app in the dashboard has one site key, and that same key receives events from the website and from the mobile and desktop apps. The dashboard then filters and groups everything by platform.

The key words MUST, SHOULD and MAY are used as in RFC 2119.

• Status: v1, stable. New optional fields may be added; nothing here will change meaning.

1. Endpoint

POST {endpoint}/v1/i

{endpoint} defaults to https://function-bun-production-3339.up.railway.app, so the full default URL is https://function-bun-production-3339.up.railway.app/v1/i. SDKs MUST let the developer override the full URL (self-hosting, proxies).

There is a single endpoint for every event type. There is no separate identify, screen or batch endpoint.

2. Request

2.1 Headers

No cookies are used or set.

2.2 Body

{
  "site_key": "pk_live_abc123",
  "sent_at": 1767225600123,
  "context": { "...": "context shared by every event in the batch (§3)" },
  "batch": [ { "...": "event (§2.3)" } ]
}

2.3 Event

{
  "id": "7d1f8a0e-4b5c-4c1e-9d0b-2f3a4b5c6d7e",
  "event": "page_view",
  "ts": 1767225599000,
  "anon_id": "c0a8012e-5f4b-4d4e-8f7a-1b2c3d4e5f60",
  "session_id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a9f8e7d6c",
  "user_id": "user_123",
  "path": "/product/detail",
  "url": "shopapp://product/42",
  "referrer": "",
  "props": { "screen_name": "ProductDetail", "product_id": "42" },
  "context": { "...": "optional per-event overrides (§3)" }
}

Legacy web fields (lang, tz, viewport, screen, ua_string) are still accepted; native SDKs use context instead.

2.4 Limits

SDKs SHOULD send at most 50 events per request and split larger queues.

3. Context

context describes where the event came from. Every field is optional; send everything you can read cheaply. The server validates and normalizes it: unknown keys are dropped, enum values are lower-cased and checked, strings are trimmed and truncated, numbers out of range are dropped. A bad field never rejects the event.

{
  "platform": "ios",
  "app": { "version": "2.3.0", "build": "451", "id": "com.shop.app" },
  "os": { "name": "iOS", "version": "17.4.1" },
  "device": { "model": "iPhone15,2", "manufacturer": "Apple", "type": "phone" },
  "locale": "pt-BR",
  "tz": "America/Sao_Paulo",
  "screen": { "w": 393, "h": 852, "density": 3 },
  "sdk": { "name": "analisa-swift", "version": "0.1.0" },
  "framework": "swift"
}

How the server derives what it stores:

• No context.platform: browser requests (allowed Origin) and server requests (Bearer) are web — this keeps every existing web integration working unchanged. Native requests (no Origin) without a platform are stored as other. Native SDKs MUST always send platform.
• The web SDK sends {"platform":"web","sdk":{...},"framework":"web"} as batch context.
• For native events the stored OS name is canonicalized to the same names the web UA parser uses (iOS, Android, Windows, macOS, Linux), so web and app traffic group together in the Devices report. The User-Agent header is only a fallback for missing fields.

4. Authentication and abuse control

Be honest about what this protects. A site key inside a mobile or desktop binary is public: anyone can extract it and the app id, and replay requests without an Origin. allow_native and allowed_app_ids are spam mitigation of the same strength as the Origin check on the web (which curl also bypasses): they stop drive-by junk and other apps reusing your key by accident, not a determined attacker. Keep allow_native off for apps that are web-only.

Error responses (JSON, ok: false):

Success: 200 {"ok":true,"received":N}. N can be lower than the batch size (duplicates removed); that is still success — remove the whole batch from the queue.

5. Event catalog

All names below are reserved. Anything else is a custom event (track(name, props)).

5.1 Screen views — page_view

Apps record screens as page_view so Pages ("Pages and screens"), Page flow, Funnels and Goals work the same for web and apps:

{ "id": "…", "event": "page_view", "ts": 1767225599000, "anon_id": "…", "session_id": "…",
  "path": "/product/detail", "props": { "screen_name": "ProductDetail" } }

• path MUST be route-like: starts with /, lower-case, - between words, no ids (/product/detail, not /product/42). If the app has a router with paths (Expo Router, React Navigation linking, go_router, Compose Navigation routes), send the route pattern; otherwise derive it from the screen name: ProductDetail → /product-detail.
• props.screen_name SHOULD carry the human screen name.
• Put ids in props (product_id), never in path, to keep the Pages report aggregated.
• Send one page_view per screen appearance. Do not resend when the same screen re-renders or when the app returns from background to the same screen.

Shortcut: {"event":"screen_view","screen_name":"ProductDetail"} (or props.screen / props.screen_name) is accepted and stored as a page_view with path derived as above when path is absent. New SDKs SHOULD send page_view directly.

5.2 Lifecycle (apps)

Order on a cold start after an update: app_update → app_open {launch:"cold"} → first page_view. On the first ever launch: app_open {launch:"cold", first_launch:true} (no app_update). Desktop SDKs map "background" to all windows hidden/minimized (or app deactivated on macOS) and MAY skip app_foreground/app_background when that is not observable.

5.3 Errors and crashes — error

Same shape as the web SDK, so the Errors report groups them:

{ "event": "error", "props": {
    "error_type": "NSInvalidArgumentException",
    "error_message": "unrecognized selector sent to instance",
    "error_stack": "0 CoreFoundation …\n1 libobjc.A.dylib …",
    "error_kind": "crash",
    "error_handled": false,
    "error_fingerprint": "a1b2c3d4"
} }

Crashes are usually sent on the next launch: persist the crash report to disk in the crash handler (do no network I/O there), and on the next launch enqueue it with the crash's own ts, session_id and context (the version that crashed), before app_open. The dashboard computes crash-free sessions per app version from error_kind = "crash".

5.4 Identify — identify

{ "id": "…", "event": "identify", "user_id": "user_123",
  "props": { "email": "ana@shop.com", "plan": "pro", "id_prop": "email" } }

• user_id (top level) is required. props are traits; id_prop (optional) names the trait the dashboard uses as the person's label.
• After identify, every following event MUST carry the same user_id (persist it across launches) until reset().
• reset() (logout): clear user_id, start a new session and keep anon_id.
• Do not send identify again for the same user_id within 5 minutes.

5.5 Custom events

Any other name: { "event": "add_to_cart", "props": { "product_id": "42", "price": 99.9 } }. The web SDK's helpers (purchase, signup, login, search, …) define recommended names and props; native SDKs SHOULD expose the same helpers with the same names.

6. Identity and sessions

6.1 anon_id

• UUID v4, generated on first launch, persisted in app storage (UserDefaults, SharedPreferences / DataStore, localStorage in Electron/Tauri, a file in the app data dir).
• Never derived from hardware ids, advertising ids (IDFA/GAID) or anything that survives reinstall. A reinstall produces a new anon_id — that is intended.
• Sent on every event.

6.2 session_id

• UUID v4. A session ends after 30 minutes without events.
• Before stamping any event, the SDK checks now - last_event_at > 30 min (wall clock); if so (or if there is no session yet) it creates a new session_id. last_event_at is updated for every event and persisted together with session_id, so a process restart within 30 minutes continues the same session.
• Background → foreground: if the app was in background for more than 30 minutes, the next event starts a new session, and the SDK emits app_open {launch:"warm"} as its first event. Otherwise it emits only app_foreground and the session continues.
• reset() always starts a new session.
• Lifecycle events count as activity (an app_background updates last_event_at).

6.3 user_id

Set by identify, persisted, cleared by reset() (§5.4).

6.4 Consent and opt-out

SDKs MUST offer setConsent('denied') / optOut() that stops collection, clears the queue and the persisted user_id, and survives restarts. Respect platform tracking settings where they apply. Do not collect IDFA/GAID, IP-derived precise location, contacts or any personal data by default.

7. Delivery: queue, batching, retry

• Persistent queue. Events are appended to an on-disk queue (file, SQLite, MMKV, localStorage…) so they survive app kills. Cap it at 1000 events; when full, drop the oldest. Drop events older than 7 days at send time.
• Flush triggers. Flush when the queue reaches 20 events, every 10 s while the app is in the foreground, on app_background (iOS: inside beginBackgroundTask; Android: from ProcessLifecycleOwner ON_STOP, using WorkManager if the send cannot finish), and at launch for anything left from the previous run. Only one request in flight at a time.
• Batch. Up to 50 events per request (§2.4). Set sent_at on every attempt.
• Retry. On network error, timeout (use 10 s), 429 or 5xx: keep the batch, retry with exponential backoff min(2^attempt × 1 s, 5 min) with ±20 % jitter. Honor Retry-After when present. Reset the backoff after a success. Because every event has an id, retrying a batch that was in fact stored is harmless.
• Do not retry other 4xx (§4 table). On 413, split the batch.
• Offline. Do not attempt sends while the OS reports no connectivity; flush when it returns.
• Never block the UI thread and never throw into the host app.

8. Privacy guarantees the server applies

• The client IP is used only for country lookup and stored anonymized (last IPv4 octet / last 80 bits of IPv6 zeroed). Do not send IPs in props.
• No fingerprinting: the server never combines IP/UA into an identifier.
• Delete requests (GDPR) work by anon_id / user_id through the dashboard.

9. Example: plain HTTP

curl -X POST https://function-bun-production-3339.up.railway.app/v1/i \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: ShopApp/2.3.0 (Android 14; SM-S918B)' \
  -H 'X-Analisa-App-Id: com.shop.app' \
  -d '{
    "site_key": "pk_live_abc123",
    "sent_at": 1767225600123,
    "context": {
      "platform": "android",
      "app": { "version": "2.3.0", "build": "451", "id": "com.shop.app" },
      "os": { "name": "Android", "version": "14" },
      "device": { "model": "SM-S918B", "manufacturer": "samsung", "type": "phone" },
      "locale": "pt-BR", "tz": "America/Sao_Paulo",
      "screen": { "w": 384, "h": 854, "density": 2.8125 },
      "sdk": { "name": "curl", "version": "1" }, "framework": "kotlin"
    },
    "batch": [
      { "id": "b6f1c9a4-0d0e-4f57-9a3b-6a5f3f7f2b10", "event": "app_open", "ts": 1767225599000,
        "anon_id": "c0a8012e-5f4b-4d4e-8f7a-1b2c3d4e5f60", "session_id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a9f8e7d6c",
        "props": { "launch": "cold" } },
      { "id": "0b8e7c4f-2a6d-4c51-8f0b-9d3e2a1c5b77", "event": "page_view", "ts": 1767225599500,
        "anon_id": "c0a8012e-5f4b-4d4e-8f7a-1b2c3d4e5f60", "session_id": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a9f8e7d6c",
        "path": "/home", "props": { "screen_name": "Home" } }
    ]
  }'
# → {"ok":true,"received":2}

10. Minimal contract for a new SDK (checklist)

1. init(siteKey, { endpoint?, debug? }); never throws, never blocks the UI thread.
2. Persist anon_id; manage session_id with the 30-minute rule and foreground handling (§6).
3. Build context once per launch (platform, app, os, device, locale, tz, screen, sdk, framework) and send it as batch context; refresh locale/tz/screen on change.
4. Every event: id (UUID), event, ts, anon_id, session_id, user_id when identified.
5. API: track(name, props), screen(name, props?) → page_view (§5.1), `identify(userId, traits?, idProp?), reset(), captureException(error, props?), setConsent(...), flush()`.
6. Automatic: app_open, app_update, app_foreground, app_background (§5.2) and crash capture (§5.3), each switchable off in the config.
7. Persistent queue, batching, backoff and the response handling table (§4, §7).
8. No Origin header, no secret key, no personal data by default.
9. Test against a real ingestor: events appear in the dashboard under the right platform, versions show in "App versions", a forced crash appears in Errors with error_kind: "crash".