<!-- Source: https://developer.retainza.com/ · Markdown: https://developer.retainza.com/index.md -->

Developer docs

# Build with Retainza

Add push, in-app messages, email and deep links to your app with a small SDK or plain HTTP. Pick your platform's guide, or go straight to the reference.

[Choose your SDK](https://developer.retainza.com/#sdks) · [HTTP API reference](https://developer.retainza.com/#api)

## SDK guides

- [React Native & Expo Available — npm, from release tarballs](https://developer.retainza.com/react-native/)
- [iOS (Swift) Available — Swift Package Manager](https://developer.retainza.com/ios/)
- [Android (Kotlin) Unpublished — Gradle](https://developer.retainza.com/android/)
- [Flutter (Dart) Unpublished — pub](https://developer.retainza.com/flutter/)
- [Server (Node) Unpublished — HTTP API · Node SDK not distributed yet](https://developer.retainza.com/server/)
- [HTTP API — Any language, no SDK](https://developer.retainza.com/#api)

## How an integration goes

1. [Get your public key — Copy the **pk_…** key from **API keys** in the dashboard. It is safe to ship in an app.](https://developer.retainza.com/#concepts)
2. [Install and start the SDK — Open your platform's guide, add the package and start it once at launch.](https://developer.retainza.com/#sdks)
3. [Identify and track — Send who the user is and what they do. Users appear in the dashboard.](https://developer.retainza.com/#usage)
4. [Push and in-app — Register push tokens and let the SDK render in-app messages.](https://developer.retainza.com/#push)

Already integrating? [Signed identity](https://developer.retainza.com/#identity) [SDK method list](https://developer.retainza.com/#usage) [Troubleshooting](https://developer.retainza.com/react-native/#troubleshooting) [Integration checklist](https://developer.retainza.com/react-native/#checklist) [Use with AI tools](https://developer.retainza.com/ai/) [SDK downloads](https://dashboard.retainza.com/dashboard/sdk)

<!-- section: overview -->

## Overview

Retainza is a customer engagement platform — Email, Push, In-App messages, deep-link navigation and conditional sends. You integrate it into your app with a small SDK (or by calling the HTTP API directly).

Every integration is the same two steps:

1. **Install** the SDK with your platform's package manager.
2. **Initialize** it with `baseUrl` (your Retainza server) and a `publicKey`.

> **Tip:** Find your project's **public key** and server URL under **Connections** / **API Keys**. The public key is safe to ship in a mobile or web app — it is write-only.

> **Note:** Each platform has a step-by-step guide — install, start, track, push and in-app, in the order you actually do them: [React Native & Expo](https://developer.retainza.com/react-native/), [iOS (Swift)](https://developer.retainza.com/ios/), [Android (Kotlin)](https://developer.retainza.com/android/), [Flutter (Dart)](https://developer.retainza.com/flutter/) and [Server (Node)](https://developer.retainza.com/server/). This page stays the reference for the whole surface.

<!-- section: concepts -->

## Keys & base URL

### Two kinds of keys

| Key | Prefix | Use it in |
| --- | --- | --- |
| Public key | `pk_…` | Client apps (mobile, web) — identify, track, register push. Safe to ship. |

### Why you always pass a base URL

The SDK is just *code* — it knows *how* to talk to Retainza, but not *where* your server lives. Every company runs Retainza at a different address, so the address can never be baked into a shared package. You pass it in when you initialize the SDK.

> **Note:** Think of the SDK as a phone and the base URL as the number you dial. You don't ship a phone with one number burned in — you dial it at call time. That's why `baseUrl` is always configuration, never part of the package.

<!-- section: platforms -->

## Platform support

The **JavaScript/TypeScript** SDK covers React Native/Expo, web and Node. Native Swift and Kotlin SDKs and a Flutter (Dart) SDK are built and tested but not yet published to their package registries — install them from the repository as their guides describe. Any platform can also call the [HTTP API](https://developer.retainza.com/#api) directly — an SDK is only a convenience wrapper.

| Platform | Language | Package manager | SDK |
| --- | --- | --- | --- |
| [React Native / Expo, Web, Node](https://developer.retainza.com/react-native/) | JavaScript / TypeScript | npm, from release tarballs (not on the npm registry yet) | Available |
| [iOS (native)](https://developer.retainza.com/ios/) | Swift | SPM (CocoaPods coming soon) | Available |
| [Android (native)](https://developer.retainza.com/android/) | Kotlin | Gradle (Maven Central) | Unpublished |
| [Flutter](https://developer.retainza.com/flutter/) | Dart | pub (git dependency) | Unpublished |

<!-- section: install -->

## Install & configure

Pick your platform. Every one is the same two steps — install, then initialize with your base URL and key.

#### npm

> **Warning:** The JavaScript packages are **not on the npm registry yet**, so `npm install @retainza/…` from the registry will not resolve. Install the release tarballs as the [React Native guide](https://developer.retainza.com/react-native/#install) describes, or use the [HTTP API](https://developer.retainza.com/#api).

**Step 1:** Install

```bash
# React Native / Expo
npm install @retainza/react-native
# Web:   npm install @retainza/sdk-core

# Not publishing to a registry? Build local tarballs instead:
#   cd sdk && ./scripts/pack-local.sh /path/to/your-app --install
```

**Step 2:** Initialize

```ts
// App.tsx
import AsyncStorage from "@react-native-async-storage/async-storage";
import Constants from "expo-constants";
import { Retainza } from "@retainza/react-native";

Retainza.init({
  publicKey: process.env.EXPO_PUBLIC_ENGAGE_PUBLIC_KEY, // "pk_..."
  userProvider: () => currentUser?.id,                  // optional
  appVersion: Constants.expoConfig?.version,            // → app_version attribute
  storage: AsyncStorage,                                // offline queue + install_date
  debug: __DEV__,                                       // silent in production
});
```

Next: the [React Native guide](https://developer.retainza.com/react-native/#install) takes it from here — identify, track, push and in-app, in order.

#### Swift PM

**Step 1:** Install

```swift
// Xcode → File → Add Package Dependencies… → paste:
https://github.com/appunik-retainza/ios-sdk

// or Package.swift:
.package(url: "https://github.com/appunik-retainza/ios-sdk.git", from: "1.0.0")
```

**Step 2:** Initialize

```swift
// App / AppDelegate — the module is RetainzaSDK
import RetainzaSDK

try? Retainza.start(with: RetainzaConfig(
    publicKey: "pk_test_…",               // pk_live_… in release builds
    userProvider: { AuthStore.shared.userId }
))
```

Next: the [iOS guide](https://developer.retainza.com/ios/#install) takes it from here — identify, track, push and in-app, in order.

#### CocoaPods

> **Warning:** The CocoaPods SDK is **built but not yet published** to its package registry. The snippets are the real API; install it as the [iOS guide](https://developer.retainza.com/ios/#install) describes, or use the [HTTP API](https://developer.retainza.com/#api).

**Step 1:** Install

```ruby
# Podfile
pod 'RetainzaSDK', '~> 1.0'

# then
pod install
```

**Step 2:** Initialize

```swift
import RetainzaSDK

try? Retainza.start(with: RetainzaConfig(
    publicKey: "pk_test_…",
    userProvider: { AuthStore.shared.userId }
))
```

Next: the [iOS guide](https://developer.retainza.com/ios/#install) takes it from here — identify, track, push and in-app, in order.

#### Gradle (Kotlin)

> **Warning:** The Gradle (Kotlin) SDK is **built but not yet published** to its package registry. The snippets are the real API; install it as the [Android guide](https://developer.retainza.com/android/#install) describes, or use the [HTTP API](https://developer.retainza.com/#api).

**Step 1:** Install

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("com.retainza:retainza-android:1.0.0")
}
// Until 1.0.0 is on Maven Central: ./scripts/release-sdk-android.sh --local
// and add mavenLocal() to your repositories.
```

**Step 2:** Initialize

```kotlin
// Application.onCreate()
import com.retainza.sdk.Retainza
import com.retainza.sdk.RetainzaConfig

Retainza.start(
    this,
    RetainzaConfig(
        publicKey = BuildConfig.RETAINZA_KEY, // pk_test_… / pk_live_… per build type
        userProvider = { AuthStore.userId },
    ),
)
```

Next: the [Android guide](https://developer.retainza.com/android/#install) takes it from here — identify, track, push and in-app, in order.

#### Flutter (Dart)

> **Warning:** The Flutter (Dart) SDK is **built but not yet published** to its package registry. The snippets are the real API; install it as the [Flutter guide](https://developer.retainza.com/flutter/#install) describes, or use the [HTTP API](https://developer.retainza.com/#api).

**Step 1:** Install

```yaml
# pubspec.yaml
dependencies:
  retainza_flutter: ^1.0.0

# then
flutter pub get
# Not on pub.dev yet — inside the monorepo, use
#   retainza_flutter: { path: ../sdk/flutter/retainza_flutter }
```

**Step 2:** Initialize

```dart
// main.dart
import 'package:flutter/widgets.dart';
import 'package:retainza_flutter/retainza_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  Retainza.init(
    publicKey: const String.fromEnvironment('RETAINZA_PK'), // pk_test_… / pk_live_…
  );
  runApp(const MyApp());
}
// then Retainza.instance.identify(...), .track(...)
```

Next: the [Flutter guide](https://developer.retainza.com/flutter/#install) takes it from here — identify, track, push and in-app, in order.

<!-- section: usage -->

## Using the SDK

Once initialized, the client exposes a small surface (shown here in JS/TS — native SDKs mirror it):

### Identify a user

```ts
await Retainza.get().identify("user-123", {
  plan: "pro",
  signupSource: "web",
}, { email: "sam@acme.com", locale: "en" });
```

### Track an event

```ts
await Retainza.get().track("workout_completed", { minutes: 32 });
```

### Register for push

```ts
// obtain the device token from your push provider (e.g. FCM), then:
await Retainza.get().registerPush(fcmToken, "android"); // or "ios"
```

### Update a few attributes

`setAttributes` is a patch: it sends only the keys you pass and the server merges them, so unrelated attributes (`country`, `tz`, anything your app set earlier) are left alone.

```ts
await Retainza.get().setAttributes({ plan: "pro" });
// optionally for another user:
await Retainza.get().setAttributes({ plan: "pro" }, "user-123");
```

### In-app messages

Mount one component near your app root. That is the entire in-app integration — the SDK ships the renderer, so your app carries no layout, styling or ack code for it, and a template you design in the dashboard looks the same in every app that installs the SDK.

```ts
// app/_layout.tsx
import { RetainzaInApp } from "@retainza/react-native/ui";
import { usePathname } from "expo-router";

<RetainzaInApp
  currentScreen={usePathname()}                       // optional "where to show" gate
  blockedScreenPrefixes={["/(auth)", "/onboarding"]}  // never interrupt these
/>
```

It owns polling, the message queue (one at a time, the rest stay pending), the `shown` / `clicked` / `dismissed` acks that feed Analytics, and CTA deep links. A blocked screen leaves a message pending rather than consuming it, so nothing is lost.

### Layouts

A native message is a list of **slots** — image/video, header, title, body and up to three buttons — arranged in whatever order the layout names. The catalog in the builder (“Image, Text & Button”, “Image only”, “Image & 2 Buttons”…) is just preset slot lists, so a new layout never needs an app release. Your app renders all of them with the one component above.

Each button carries its own action: give it a screen and it deep-links there and reports `clicked`; leave the screen blank and it closes the message and reports `dismissed`.

> **Note:** Images and background images must be **https** — iOS blocks plain http, so an http URL is a blank box on those devices. Video needs `expo-video` (or `expo-av`) in your app; without it the message still shows, minus the video.

### Overriding the look

Adopting the renderer is not all-or-nothing. Replace one presentation and keep the machinery, or take over rendering entirely:

```ts
<RetainzaInApp presentations={{ banner: MyBanner }} />   // just the banner

<RetainzaInApp render={(msg, { onCta, onDismiss }) => (
  <MyOwnSheet message={msg} onPrimary={onCta} onClose={onDismiss} />
)} />
```

### Deep links from a CTA

```ts
Retainza.get().onNavigate((route) => router.push(route.screen));
```

> **Note:** `@retainza/react-native/ui` is a separate entry point on purpose: importing the package root never pulls React in, so your FCM background handler stays headless.

### Full method list

| Method | Notes |
| --- | --- |
| `identify(userId, attrs?, profile?)` | Upsert a profile. The third argument is reserved identity — firstName, lastName, email, phone, gender, birthdate, locale — mapped to snake_case attributes for you. Default attributes ride along on every call. |
| `setPushPermission(status, userId?)` | "authorized" \| "denied" \| "provisional" \| "undetermined". The SDK never prompts; report what your app already knows. A denied user keeps a valid token and receives nothing. |
| `setDeviceInfo(info)` | Device model/manufacturer from whichever device library you use. The React Native wrapper calls this from the `device` init option. |
| `startSession() / endSession()` | Foreground / background. Wired to AppState automatically unless autoSession is false. 30-minute timeout: a quick return resumes rather than counting again. |
| `setConsent({ analytics, marketing })` | With requireConsent, nothing is sent until analytics is true. marketing does not gate transport — it is stored for campaign targeting. |
| `optOut() / optIn()` | Hard stop, clears the queue. Deliberately not persisted — your app owns the consent UI, so re-assert on each launch. |
| `setAttributes(attrs, userId?)` | Partial update — sends only what you pass; the server merges. |
| `track(event, props?, userId?)` | Stamps the event time client-side, so a queued event keeps its real timestamp. |
| `addToCollection(collection, item, userId?)` | One-to-many data — a user's challenges, badges, saved searches. Takes either a bare id string (`"lagos_10k"`) or an object with fields (`{ id, status, progress }`); the two interoperate, so a later write with fields patches the same item. `id` is yours and is the merge key: writing it twice updates in place, which is what makes a replayed offline write safe. Fields you omit are preserved. Items are flat — strings, numbers, booleans, null. |
| `removeFromCollection(collection, id, userId?)` | Remove one item. An id that is not there is a no-op, not an error. |
| `setCollection(collection, items, userId?)` | Replace the whole list; `[]` clears it. Accepts id strings or objects. Use it when your app already holds the full list; use addToCollection for incremental changes. |
| `registerPush(token, platform, userId?)` | Never queued — a stale token is worse than a missing one. |
| `ackInApp(msgId, action, userId?)` | "shown" \| "clicked" \| "dismissed". |
| `ackPush(msgId, action, userId?)` | "delivered" \| "opened" — the only source of push delivery data. |
| `reset()` | Call on logout. Clears identity, session counters, the offline queue and in-app polling. |
| `flushQueue() / queueSize()` | Drain or inspect the offline queue. |
| `getBaseUrl() / setBaseUrl(url) / clearBaseUrl()` | Runtime backend switching in dev builds. |
| `testConnection()` | GET /health — for a “test connection” button on a dev screen. |
| `onNavigate(h)` | Register your router, for CTA deep links. |
| `onSelfHandledInApp(h)` | Receive selfhandled campaigns and render them yourself. The handle carries markShown/markClicked/markDismissed — send them or the campaign's funnel stays empty. |
| `onInApp(h)` | Low-level — <RetainzaInApp /> registers this for you. Only one handler exists, so setting it yourself takes delivery away from the component. |
| `fetchPendingInApp(userId?)` | One poll for queued in-app messages. Handled for you by <RetainzaInApp />. |
| `startInAppPolling({ intervalMs, userId })` | Low-level polling loop; returns a stop function. |
| `deliverInApp(msg) / resolveRoute(route)` | Hand a message to the renderer / a route to the router. |
| `parseRetainzaPush(data)` | Standalone function: is this FCM payload ours? Returns null if not. |

<!-- section: identity -->

## Signed identity

Your public key is compiled into your app, so anyone who unpacks the app has it. By itself that is enough to act as **any** of your users: overwrite their profile and the email your campaigns go to, register a device for their pushes, or read their pending in-app messages. Signed identity closes that. Your server vouches for each user id, and Retainza refuses calls that claim an id without that proof.

> **Note:** Optional and off by default. Until you turn it on for an environment, nothing here changes how the SDK or the API behaves. It needs an SDK version that supports it: check the changelog of the SDK you use.

### How it works

1. In the dashboard, open **API keys** and create an **identity secret** for the environment. It is shown once. Keep it with your other server secrets.
2. When a user signs in, your server computes a signature of their user id with that secret and returns it to the app with the rest of the session.
3. The app passes it to `identify`. The SDK sends it with every call it makes for that user.

### 1. Sign the user id on your server

The signature is `hex(HMAC-SHA256(identitySecret, userId))`: 64 lowercase hex characters. With the Node SDK:

```ts
import { signUserId } from "@retainza/sdk-node";

const userHash = signUserId(process.env.RETAINZA_IDENTITY_SECRET, user.id);
// return userHash to the app with the rest of the session
```

Any language with an HMAC function produces the same value:

**Python**

```python
import hmac, hashlib
user_hash = hmac.new(secret.encode(), user_id.encode(), hashlib.sha256).hexdigest()
```

**PHP**

```php
$userHash = hash_hmac('sha256', $userId, $secret);
```

**Go**

```go
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(userID))
userHash := hex.EncodeToString(mac.Sum(nil))
```

> **Warning:** The identity secret never goes in the app. An app that holds the secret can sign any user id, which is exactly what this is meant to prevent. Sign on your server, send the result.

### 2. Pass it to the SDK

On every launch, alongside the user id:

**React Native / JS**

```ts
await Retainza.get().identify(user.id, attributes, profile, { userHash });
```

**iOS**

```swift
try await Retainza.shared?.identify(user.id, userHash: userHash)
```

**Android**

```kotlin
Retainza.client?.identify(user.id, userHash = userHash)
```

**Flutter**

```dart
await Retainza.instance.identify(user.id, userHash: userHash);
```

If you do not call `identify` at that point (for example you use a `userProvider`), set it directly with `setUserHash(userHash)`.

- The signature is sent with every call for that user id, and never with any other id.
- It is kept in memory, not written to device storage on its own, so pass it again on each launch. Events queued while offline keep the signature they were made with and still verify when they are sent later.
- `reset()` clears it. Identifying a different user without a signature clears it too.
- An app that passes no signature behaves exactly as before.

### 3. Turn it on in stages

| Mode | What the API does |
| --- | --- |
| Off | Takes the user id on trust. The default. |
| Monitor | Checks signatures and counts signed, unsigned and wrongly signed calls. Refuses nothing. |
| Enforce | Answers `401` to a call made with the public key that has no valid signature for the user id it names. |

Ship an app version that sends the signature, switch the environment to **Monitor**, and watch the unsigned count fall as your users update. Switch to **Enforce** when it is at or near zero. Going back to Monitor is immediate if you need to.

> **Warning:** Enforce stops app versions that do not send a signature from identifying users, tracking events and receiving in-app messages. Old versions stay installed for a long time: decide what share of your users you are willing to cut off before you enforce.

### What is checked, and what is not

- Checked: calls made with a **public key** to identify, track, collections, push token registration and removal, in-app pending and both ack routes.
- Not checked: calls made with a **secret key**. That is your server, which is the party doing the vouching.
- Each environment has its own secret and its own mode. Sandbox and Production are independent.
- A signature is tied to one user id. Someone who obtains a user's signature can act as that user only, until you replace the secret.
- It does not cover people who are not signed in (there is no server to vouch for them), and it does not stop a signed-in user sending made-up events about themselves.

### Replacing the secret

Replace it from the same screen. The previous secret keeps working for 7 days, so signatures your apps already hold stay valid while your server moves to the new one. If a secret has leaked, replace it with no grace period: every signature made with the old one stops working at once, and users get a new one at their next sign-in.

### Without the SDK

Send the signature in the `X-Engage-User-Hash` header. A refused call answers `401 identity_required` (no header) or `401 identity_invalid` (wrong signature for that user id).

```bash
curl -X POST https://api.retainza.com/v1/identify \
  -H "authorization: Bearer pk_..." \
  -H "x-engage-user-hash: 5ef80dc2a802d7fc..." \
  -H "content-type: application/json" \
  -d '{"userId":"user-123","attributes":{"plan":"pro"}}'
```

<!-- section: htmlinapp -->

## Custom HTML messages

The four native templates cover most sends and should stay your default — they render as real native views, cost nothing to show, and match your app's look. When the *layout itself* is the point, pick the **Custom HTML** presentation instead and design the whole message in the dashboard.

Your document renders in a sandboxed WebView inside a native shell (popup, bottom sheet or full screen), so it keeps the backdrop, safe-area padding and dismiss behaviour of a normal message. **No app code is needed** — the same `<RetainzaInApp />` renders it.

### Talking to the app

A document gets exactly three verbs. They run the same code path as a native template's buttons, so the funnel in Analytics reads identically whichever presentation a campaign uses.

```html
<button onclick="engage.cta({ screen: '/(tabs)/shop', kv: { id: '42' } })">Shop</button>
<button onclick="engage.dismiss()">Not now</button>
<button onclick="engage.track('variant_b_tapped')">Tell me more</button>
```

- `engage.cta(route?)` — reports **clicked**, then deep-links if you pass a route.
- `engage.dismiss()` — reports **dismissed** and closes.
- `engage.track(event, props?)` — a custom event, e.g. which variant was tapped.

> **Warning:** A plain `<a href>` does nothing: navigating the WebView away is blocked. Use `engage.cta` so the click is measured and the app routes properly.

### What a document may and may not do

- **Allowed:** inline `<style>` and `<script>`, https images, data URIs, `{{variables}}`.
- **Blocked on the device:** remote scripts, `fetch`/XHR, `<iframe>`, `<object>`, `<embed>`, `<base>` and meta-refresh — a strict CSP and an opaque origin see to it.
- **Rejected on save:** anything over 64 KB, and the tags above. The document is sent on every in-app poll, so size is bandwidth for every user.

> **Note:** Personalization inside HTML is escaped, so a profile attribute containing markup renders as text. Campaign authoring is a privileged action — anyone who can author a campaign can run script inside this sandbox.

### Falling back

`react-native-webview` is an optional peer. If it is not installed, or a document fails to render, the SDK shows the native popup built from the campaign's title, body and CTA instead. That is why those fields stay required for an HTML message — without them the campaign would simply vanish on those devices.

```bash
npx expo install react-native-webview   # enables HTML in-app messages
```

<!-- section: selfhandled -->

## Self-handled messages

The escape hatch: pick the **Self-handled** presentation and Retainza delivers the payload without drawing anything. Your app renders it with its own design system, and keeps the targeting, scheduling and analytics that every other campaign gets.

It is the last resort, not the first. A native layout needs no app code and no release; this needs both. Reach for it when the message has to be part of your own UI — a card inside a feed, a themed sheet — rather than an overlay on top of it.

```ts
Retainza.get().onSelfHandledInApp((msg) => {
  setPromo(msg);            // your own component draws it
});

// in that component:
useEffect(() => promo.markShown(), []);       // counts as delivered
<Button onPress={() => promo.markClicked()} />  // acks clicked, then deep-links
<Close onPress={() => promo.markDismissed()} />
```

> **Warning:** The acks are yours to send. Retainza cannot see your view, so a self-handled campaign that never calls `markShown` reports zero deliveries no matter how many people saw it.

> **Note:** With **no handler registered** the message stays queued rather than being consumed — a half-finished integration looks like “not shown yet”, never like a campaign that vanished. Watch for the warning in `debug` mode.

<!-- section: attributes -->

## Default attributes

The SDK attaches these to **every** `identify`, so they never go stale. Anything you pass yourself wins — if your app sets `country` from a billing address, the SDK will not overwrite it.

| Attribute | Set by | Notes |
| --- | --- | --- |
| `language` | SDK (Intl) | ISO-639-1, e.g. "en". |
| `country` | SDK (Intl) | ISO-3166-1 alpha-2 from the device locale, e.g. "IN". Powers geo targeting. Locale, not GPS — no permission involved. |
| `tz` | SDK (Intl) | IANA, e.g. "Asia/Kolkata". Powers user-local scheduling. |
| `sdk_version` | SDK | The SDK build, for debugging an integration. |
| `platform` | React Native SDK | "ios" \| "android" \| "web", from Platform.OS. |
| `os_name / os_version` | React Native SDK | From React Native itself. |
| `device_model / device_manufacturer` | Your app | Only when you pass `device` at init — the SDK takes no dependency on a device library. |
| `app_version` | React Native SDK | Whatever you pass as appVersion to init. |
| `install_date` | React Native SDK | Stamped once into your storage adapter on first run. |
| `session_count` | SDK sessions | Lifetime sessions. Also first_session_at, last_session_at and session_duration_total. |
| `push_permission` | Your app | setPushPermission(). The difference between having a token and being reachable. |
| `first_name, last_name, email, phone, gender, birthdate` | Your app | Reserved identity. Only ever what you pass to identify — the SDK never collects PII on its own. |
| `consent_marketing / consent_analytics` | Your app | setConsent(). |
| `last_active` | Backend | Refreshed on every identify and track. |

```ts
import AsyncStorage from "@react-native-async-storage/async-storage";
import Constants from "expo-constants";
import { Retainza } from "@retainza/react-native";

Retainza.init({
  publicKey: process.env.EXPO_PUBLIC_ENGAGE_PUBLIC_KEY,
  appVersion: Constants.expoConfig?.version,   // → app_version
  storage: AsyncStorage,                       // → install_date + offline queue
});

// platform and install_date resolve asynchronously; await this before the
// very first identify if you need them on that call.
await Retainza.ready();
```

> **Note:** `tz` decides *when* a user-local campaign sends and `country` decides *who* a geo campaign reaches. A missing one silently changes the audience, which is why the SDK collects them rather than leaving it to each app.

<!-- section: offline -->

## Offline & logout

### The offline queue

`track` and `identify` are queued when a request fails with a network error or a 5xx, then replayed oldest-first. A 4xx is **not** queued — it would fail forever and block everything behind it.

- Capacity 100 (`maxQueuedEvents`); the **oldest** events are dropped on overflow.
- Order is preserved — a flush stops at the first failure rather than skipping ahead.
- Each event carries its **original timestamp**, so a delayed flush does not distort analytics or misfire a time-based condition.
- With a `storage` adapter the queue survives an app restart. Without one it is memory-only: it survives a network blip, not a relaunch.
- `registerPush` is never queued.

### Reset on logout

> **Warning:** Call `reset()` when a user signs out. Without it the next person to use the device inherits the previous user's identity — their events, and their messages.

```ts
export async function signOut() {
  await auth().signOut();
  await Retainza.get().reset();   // clears identity, queue and polling
}
```

`reset()` is a client-side identity clear, not a data deletion — the server-side profile is untouched. It also clears the user's [signed identity](https://developer.retainza.com/#identity). For a GDPR erasure use `DELETE /v1/users/:id`. If you supplied a `userProvider`, remember it belongs to your app: the SDK will keep using whatever it returns.

<!-- section: debugging -->

## Debug & troubleshooting

### Debug mode

`debug: true` logs every request, poll, ack and swallowed error. With `debug` off the SDK writes **nothing** to the console. Values are never logged — only attribute and property *key names*, and only a prefix of the public key.

```ts
Retainza.init({
  publicKey: "pk_…",
  debug: __DEV__,                       // silent in production
  logger: (level, msg, meta) => Sentry.addBreadcrumb({ level, message: msg, data: meta }),
});
```

### Changing the backend URL without a rebuild

The base URL is normally inlined into your bundle at build time, so a backend hostname change disconnects every installed build until you ship a new one. In dev builds the SDK can be pointed somewhere else at runtime, highest priority first: **stored override → config.baseUrl → EXPO_PUBLIC_ENGAGE_BASE_URL**.

```ts
const client = Retainza.get();
await client.setBaseUrl("https://your-tunnel.example.dev/v1");
const { ok, status } = await client.testConnection();   // GET /health
await client.clearBaseUrl();                            // back to the built-in URL
```

> **Note:** Overrides are refused unless `debug` or `allowRuntimeBaseUrl` is set — stored state must never be able to redirect a production app's telemetry to another host.

### Changing EXPO_PUBLIC_* does not invalidate a release build

> **Warning:** Editing `.env` and rebuilding is **not enough**. Gradle's `createBundleReleaseJsAndAssets` sees unchanged JS sources and skips re-bundling, and Metro's transform cache still holds the previously inlined value — so the build succeeds, installs, and silently runs with the **old** URL. This applies to every `EXPO_PUBLIC_*` variable, not just the base URL.

Clear both caches and rebuild:

```bash
rm -rf android/app/build/generated/assets/createBundleReleaseJsAndAssets \
       android/app/build/intermediates/assets/release
rm -rf "$TMPDIR"/metro-*
npx expo run:android --variant release
```

Then verify the value actually made it into the bundle before trusting the build:

```bash
grep -a -c 'api.retainza.com' \
  android/app/build/generated/assets/createBundleReleaseJsAndAssets/index.android.bundle
# 0 means the old bundle is still in place — clear the caches again.
```

<!-- section: push -->

## Push notifications

1. In the dashboard, add an **FCM** (Android) or **APNs** (iOS) connection under **Connections**.
2. In your app, get the device push token and call `registerPush(token, platform)`.
3. Send a push from **Campaigns**; watch delivery in **Notifications**.

> **Warning:** Android **release** builds block plain `http://`. For a release build your Retainza server must be reachable over **HTTPS** — put the API behind a reverse proxy (nginx/Caddy) with a TLS certificate, or a company domain, and use `https://api.retainza.com/v1` as the base URL.

<!-- section: deeplinks -->

## Deep links & screens

A campaign's **screen** is an [expo-router](https://docs.expo.dev/router/introduction/) path in *your* app. Retainza does not know your navigation — it carries the path and any parameters, and your app resolves them.

### What Retainza puts in the push

Alongside the usual notification block, every Retainza push carries a data block. Every key is prefixed `engage_` so it cannot collide with another push SDK in the same app (a third-party SDK, your own notifications), and every value is a string — that is an FCM requirement.

```json
{
  "notification": { "title": "…", "body": "…" },
  "data": {
    "engage_msg_id":   "<campaignId>:<runId>:push:<userId>",
    "engage_campaign": "<campaignId>",
    "engage_route":    "/(tabs)/challenges",   // optional
    "engage_params":   "{"id":"42"}"        // optional, JSON string
  }
}
```

### Handling it

Use `parseRetainzaPush(data)` from the SDK in every Firebase handler. It returns `null` for anything that is not an Retainza push, so other SDKs pass through untouched.

```ts
import messaging from "@react-native-firebase/messaging";
import { parseRetainzaPush } from "@retainza/sdk-core";

// Tapped while backgrounded → report the open, then navigate.
messaging().onNotificationOpenedApp(async (remote) => {
  const push = parseRetainzaPush(remote?.data);
  if (!push) return;                       // not ours — leave it alone
  await engage.ackPush(push.msgId, "opened");
  if (push.route) router.push({ pathname: push.route.screen, params: push.route.kv ?? {} });
});

// Foreground → report delivery, but do NOT navigate: nobody tapped anything.
messaging().onMessage(async (remote) => {
  const push = parseRetainzaPush(remote?.data);
  if (push) await engage.ackPush(push.msgId, "delivered");
});
```

> **Warning:** **Cold start ordering.** `getInitialNotification()` resolves before your router has mounted, so navigating immediately does nothing at all. Queue the route and flush it once navigation is ready — Retainza's reference integration keeps a `pendingRoute` and flushes it from the same effect that tells the rest of the app the router is up.

### Why acks matter

FCM gives no delivery receipt. `delivered` and `opened` for push exist only because the device reports them via `POST /v1/push/ack`. Without those calls the funnel stops at **sent**. Status is monotonic, so acks arriving out of order never move a delivery backwards, and an unknown message id is accepted silently — telemetry must never break the app.

### The screen catalog

The campaign builder offers a dropdown of known screens instead of a free-text path. That list lives in one constant, `dashboard/src/lib/screenCatalog.ts` — it is your app's config, not platform truth. Add a screen there and it appears for every campaign; a **Custom…** option always remains for anything not yet listed.

```ts
export const SCREEN_CATALOG: ScreenTarget[] = [
  { label: "Home",      path: "/(tabs)/home" },
  { label: "Challenge", path: "/challenge/[id]", params: ["id"] },
  // …add your own
];
```

<!-- section: api -->

## HTTP API reference

No SDK required — the backend is plain HTTP + JSON. Authenticate the ingest routes with your **public key** from the app, or with your **secret key** from your own backend: they accept either, so your server and your app are co-equal write paths. Use that when the truth lives on your server — plan tier, entitlements, anything the app never sees. Management routes below are driven from this portal.

**Never ship a secret key in an app.** It reaches campaigns, segments and billing, and anyone who unzips your binary has it.

```bash
curl -X POST https://api.retainza.com/v1/identify \
  -H "authorization: Bearer pk_..." \
  -H "content-type: application/json" \
  -d '{"userId":"user-123","attributes":{"plan":"pro"}}'
```

If an environment enforces [signed identity](https://developer.retainza.com/#identity), calls made with the public key must also carry `X-Engage-User-Hash`. Calls made with a secret key never need it.

### Ingest routes (public key from the app, or secret key from your backend)

- POST · `/v1/identify` · identify
- POST · `/v1/track` · track
- POST · `/v1/collections` · collections
- POST · `/v1/token` · token
- DELETE · `/v1/token` · tokenDelete
- POST · `/v1/inapp/ack` · inappAck
- GET · `/v1/inapp/pending` · inappPending
- POST · `/v1/push/ack` · pushAck

### Management routes (this portal only)

- GET · `/v1/projects` · projectsList
- POST · `/v1/projects` · projectsCreate
- POST · `/v1/campaigns` · campaignsUpsert
- GET · `/v1/campaigns` · campaignsList
- POST · `/v1/campaigns/:id/activate` · campaignActivate
- POST · `/v1/campaigns/:id/pause` · campaignPause
- POST · `/v1/send` · send
- POST · `/v1/segments` · segmentsUpsert
- GET · `/v1/segments/:id/count` · segmentCount
- POST · `/v1/connections` · connectionsUpsert
- GET · `/v1/connections` · connectionsList
- GET · `/v1/usage` · usage
- GET · `/v1/billing` · billing
- POST · `/v1/billing/checkout` · billingCheckout
- POST · `/v1/billing/upgrade-checkout` · billingUpgradeCheckout
- POST · `/v1/billing/preview` · billingPreview
- POST · `/v1/billing/change` · billingChange
- POST · `/v1/billing/portal` · billingPortal
- GET · `/v1/analytics/campaigns/:id` · analytics
- POST · `/v1/scheduler/tick` · schedulerTick
- GET · `/v1/users/:id` · userView
- GET · `/v1/users/:id/export` · userExport
- DELETE · `/v1/users/:id` · userErase

---

<!-- Source: https://developer.retainza.com/react-native/ · Markdown: https://developer.retainza.com/react-native.md -->

Available · npm, from release tarballs

# Getting started with the React Native SDK

Install to first delivered push, in order.

<!-- section: overview -->

## Overview

`@retainza/react-native` integrates Retainza into an iOS and Android app built with React Native or Expo: user profiles, events, push notifications, in-app messages and deep-link navigation. It wraps `@retainza/sdk-core` (plain `fetch`, no native modules) and adds what only a platform can collect — `platform`, `os_version`, `app_version`, `install_date` and AppState session tracking — plus the in-app renderer and the Expo config plugin.

The whole integration is ten steps, and the first four are enough to see users and events in the dashboard:

1. Install the package.
2. Initialize it with your base URL and public key.
3. Apply the Expo config plugin (or edit the native projects yourself).
4. Identify users and track events.
5. Wire push on Android, then iOS, then the handlers that report delivery.
6. Mount one component for in-app messages, and one handler for deep links.

> **Tip:** This page is the ordered path. The [Developer docs](https://developer.retainza.com/) page is the full reference — every method, the HTTP API and the other platforms.

<!-- section: prerequisites -->

## Before you start

- A running Retainza server and its `/v1` base URL, e.g. `https://api.retainza.com/v1`.
- Your project's **public key** (`pk_…`) from **API keys**. Never put an `sk_` key in an app — the SDK throws if you try.
- React Native 0.70+ and React 18+ (the package's peer range). Expo SDK 50+ if you use Expo.
- For push: a verified **FCM** connection in the dashboard — Retainza sends to both Android and iOS through FCM — plus `@react-native-firebase/messaging` in the app.

> **Warning:** Android **release** builds block plain `http://`. If your base URL is not HTTPS, everything works in debug and silently fails in release. Put the API behind TLS before you ship.

<!-- section: install -->

## 1. Install

The SDK is not on a public registry. It ships as three tarballs — `@retainza/core`, `@retainza/sdk-core` and `@retainza/react-native` — and you need all three, at the same version.

**Step 1:** Download a release (no repo checkout)

Open [SDKs](https://dashboard.retainza.com/dashboard/sdk), click **Download all**, unzip into `retainza-sdk/` at your app root, then point the dependencies at the files:

```json
"@retainza/core": "file:retainza-sdk/retainza-core-1.1.1.tgz",
"@retainza/sdk-core": "file:retainza-sdk/retainza-sdk-core-1.1.1.tgz",
"@retainza/react-native": "file:retainza-sdk/retainza-react-native-1.1.1.tgz"
```

Then `npm install` and `npx expo start -c`. The bundle's `INSTALL.md` carries the exact lines for its version.

**Step 2:** Or build the tarballs from this repo

```bash
cd sdk
./scripts/pack-local.sh /path/to/your-app --install
```

The script builds the three packages, stages the tarballs into `<app>/retainza-sdk/`, rewrites the three dependencies your app **already declares** (add them to `package.json` first) and installs. It exists because packing a pnpm workspace for npm needs two fixes that fail confusingly otherwise: `workspace:*` left in a packed manifest (npm refuses it), and stale `integrity` hashes in the app's lockfile (`EINTEGRITY`).

**Step 3:** Optional peers

```bash
npx expo install react-native-safe-area-context   # banners/sheets avoid the notch
npx expo install react-native-webview             # enables Custom HTML in-app messages
npx expo install expo-video                       # video slot in in-app messages
npx expo install @react-native-async-storage/async-storage   # offline queue + install_date
```

> **Note:** All four are optional and degrade quietly: without `safe-area-context` a banner can sit under the notch, without `webview` an HTML message falls back to the native popup, without `expo-video` the message shows minus the video, and without `AsyncStorage` the offline queue is memory-only.

<!-- section: initialize -->

## 2. Initialize

Call this once, as early as possible in app startup — before the first screen renders.

```ts
// app/_layout.tsx (or index.js)
import AsyncStorage from "@react-native-async-storage/async-storage";
import Constants from "expo-constants";
import * as Device from "expo-device";                  // optional, see below
import { Retainza } from "@retainza/react-native";

Retainza.init({
  publicKey: process.env.EXPO_PUBLIC_ENGAGE_PUBLIC_KEY, // "pk_..."
  storage: AsyncStorage,                 // offline queue + install_date + sessions
  appVersion: Constants.expoConfig?.version,
  userProvider: () => auth().currentUser?.uid,          // optional: no userId per call
  autoSession: true,                                    // default — sessions off AppState
  device: {                                             // optional, see below
    device_model: Device.modelName ?? undefined,
    device_manufacturer: Device.manufacturer ?? undefined,
  },
  debug: __DEV__,                                       // silent in production
});

// platform and install_date resolve asynchronously. Await this before the very
// first identify if you need them on that call; they ride along on every later one.
await Retainza.ready();
```

### Device model and manufacturer

The SDK collects `os_name` and `os_version` from React Native itself, but not the hardware model — that needs a device library, and the SDK deliberately depends on none. Metro resolves every import statically, so a `try/catch` around `expo-device` does not make it optional; it makes an app without it fail to bundle. Pass the values instead, from whichever library you already have:

```ts
import * as Device from "expo-device";   // or react-native-device-info

device: {
  device_model: Device.modelName ?? undefined,          // "Pixel 8"
  device_manufacturer: Device.manufacturer ?? undefined, // "Google"
}
```

> **Note:** Omit it entirely and everything still works — the Users list simply shows no hardware model. Anything you pass here wins over what the SDK detected.

### You do not need to set a base URL

The SDK ships with Retainza's address built in, so a standard integration never configures one — leave it out and the client talks to the right backend. Override it only if you run Retainza yourself or need to point a build at a staging host. Resolution order, highest priority first: stored runtime override → `config.baseUrl` → `EXPO_PUBLIC_ENGAGE_BASE_URL` → the built-in default (`https://api.retainza.com/v1`). A custom URL must end in `/v1`.

> **Note:** Setting this is not a privacy measure either way. Whatever address the app talks to is visible in its network traffic and readable from the shipped bundle, so the built-in default reveals nothing that configuring the value would have hidden. The reason to leave it unset is that it is one less thing to get wrong.

> **Warning:** Changing an `EXPO_PUBLIC_*` value and rebuilding is **not** enough for a release build — Gradle skips re-bundling and Metro's cache still holds the old inlined value, so the app runs with the old URL. See [Debug & troubleshooting](https://developer.retainza.com/#debugging) for the cache-clearing commands.

<!-- section: expo-plugin -->

## 3. Expo config plugin

`withRetainza` applies push's native prerequisites to your Expo config so you do not edit `Info.plist`, entitlements or the Android manifest by hand. It is idempotent — Expo evaluates the config on every build.

```ts
// app.config.ts
import { withRetainza } from "@retainza/react-native";

export default ({ config }) =>
  withRetainza(config, {
    publicKey: process.env.EXPO_PUBLIC_ENGAGE_PUBLIC_KEY!,
    apnsEnvironment: "development",   // "production" for App Store / TestFlight builds
  });
```

What it changes:

- iOS: `aps-environment` entitlement, and `remote-notification` added to `UIBackgroundModes`.
- Android: the `POST_NOTIFICATIONS` permission (required from Android 13).
- Stashes `publicKey` (and `baseUrl`) under `extra.engage` so they are readable at runtime.

> **Warning:** Ship a store build with `apnsEnvironment: "development"` and every iOS push is rejected by APNs. Drive it from the build profile rather than hard-coding it.

> **Note:** Bare React Native, or an app that does not use Expo config plugins? Make the same three changes in the native projects directly — the plugin is convenience, not a requirement.

<!-- section: tracking -->

## 4. Identify & track

### Identify — on login and on profile changes

Three arguments: the id, **your** attributes, and the **reserved identity** Retainza renders with real labels in the dashboard and groups in the segment builder.

```ts
await Retainza.get().identify(
  "user-123",
  { plan: "pro", lifetime_value: 248.5 },        // your own attributes
  {                                              // reserved identity
    firstName: "Sam",
    lastName: "Lee",
    email: "sam@acme.com",
    phone: "+919876543210",                      // E.164 recommended
    gender: "female",
    birthdate: "1994-07-21",                     // ISO-8601
    locale: "en-IN",
  },
);
```

> **Note:** You write `firstName`; filters, personalization tokens and the CSV export read `first_name`. The SDK owns that mapping so every integration agrees — without it, one app writes `firstName`, another `first_name`, and a segment silently misses half your users.

`identify` upserts the profile. The SDK's default attributes ride along on every call, so `language`, `country`, `tz`, `platform`, `app_version`, `install_date` and `sdk_version` never go stale. Anything you pass yourself wins.

> **Note:** `tz` decides *when* a user-local campaign sends and `country` decides *who* a geo campaign reaches — which is why the SDK collects them rather than leaving it to each app.

### Track — user actions

```ts
await Retainza.get().track("workout_completed", { minutes: 32 });
```

The event time is stamped client-side, so an event that sat in the offline queue keeps its real timestamp instead of the flush time.

### Signed identity (optional)

Your public key ships inside the app, so by itself it lets anyone who extracts it act as any of your users. If you turn on identity verification for an environment, your server signs each user id and you pass that signature as a fourth argument. The SDK then sends it with every call for that user.

```ts
// userHash comes from YOUR server, with the rest of the session
await Retainza.get().identify("user-123", attributes, profile, { userHash });
```

Pass it on every launch: it is kept in memory, and `reset()` clears it. Without it the SDK behaves exactly as before. How to sign on your server, and how to roll it out without locking out old app versions, is in [Signed identity](https://developer.retainza.com/#identity).

### Update a few attributes

`setAttributes` is a patch: only the keys you pass are sent and the server merges them, so attributes set elsewhere are left alone.

```ts
await Retainza.get().setAttributes({ plan: "pro" });
```

> **Tip:** Use snake_case attribute and event names consistently — they become the operands of every segment filter, and `signupSource` and `signup_source` are two different attributes forever.

<!-- section: sessions -->

## 5. Sessions

A session starts when the app comes to the foreground and ends after 30 minutes in the background. Returning inside that window **resumes** the same session rather than counting a new one — so a user who taps a push, reads it and comes back is one session, not two.

With `autoSession` (the default) this is wired to React Native's `AppState` for you, including the first foreground — which `AppState` never fires an event for, and which is exactly the session an onboarding campaign cares about.

```ts
Retainza.init({ …, autoSession: true, sessionTimeoutMs: 30 * 60_000 });

// Driving it yourself instead (autoSession: false):
AppState.addEventListener("change", (next) => {
  if (next === "active") void Retainza.get().startSession();
  else void Retainza.get().endSession();
});
```

These four attributes are maintained for you, and every one of them is filterable in Segments:

- `session_count` — lifetime sessions. “Opened the app 10+ times” is a segment.
- `first_session_at` / `last_session_at` — epoch millis.
- `session_duration_total` — total foreground time in ms.

A `session_start` event is tracked for genuinely new sessions only, so it is safe to trigger a campaign on it without firing every time the user glances at a notification.

> **Warning:** Without a `storage` adapter the counters live in memory and reset on every relaunch. That undercounts rather than double-counts, which is the safer failure — but pass `AsyncStorage` and it is simply correct.

<!-- section: push-android -->

## 6. Push — Android

1. In the dashboard, add an **FCM** connection under **Connections** and paste the Firebase **service-account JSON**. Retainza verifies it on save and stores only a secret reference.
2. Put `google-services.json` for the same Firebase project in your app and install `@react-native-firebase/app` + `@react-native-firebase/messaging`.
3. Request the runtime notification permission (Android 13+) and register the token.

```ts
import messaging from "@react-native-firebase/messaging";
import { Retainza } from "@retainza/react-native";
import { PermissionsAndroid, Platform } from "react-native";

export async function registerForPush(userId: string) {
  if (Platform.OS === "android" && Platform.Version >= 33) {
    const granted = await PermissionsAndroid.request(
      PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS,
    );
    if (granted !== PermissionsAndroid.RESULTS.GRANTED) return;
  }

  const token = await messaging().getToken();
  await Retainza.get().registerPush(token, Platform.OS as "ios" | "android", userId);

  // A token can rotate at any time; a stale token is a silently undelivered push.
  messaging().onTokenRefresh((next) =>
    Retainza.get().registerPush(next, Platform.OS as "ios" | "android", userId),
  );
}
```

> **Note:** `registerPush` is deliberately **never** queued offline — replaying an old token later is worse than having no token now. It is safe to call on every launch: an unchanged token is re-sent at most once every 24 hours (pass `{ force: true }` as the fourth argument to skip that).

<!-- section: push-ios -->

## 7. Push — iOS

1. Retainza sends iOS push through **FCM**, using the same FCM connection as Android. Upload your APNs key (**.p8**, key ID + team ID) to Firebase → Project Settings → Cloud Messaging, and add `GoogleService-Info.plist` to the app. Prefer the .p8 over a .p12 certificate — one key covers all your apps and does not expire yearly.
2. Make sure the config plugin ran with the right `apnsEnvironment`, then request permission and register the same way as Android — `messaging().requestPermission()` replaces the Android permission call. Register the **FCM** token from `messaging().getToken()`, not a raw APNs device token.

### Images need a Notification Service Extension

Retainza sets `mutable-content` and `apns.fcmOptions.imageUrl` when a campaign has an image, but iOS only downloads and attaches the media if your app ships an NSE target. Without one, an image push arrives on iPhone as plain text.

> **Warning:** Image URLs must be **https**. App Transport Security drops http media on iOS, so an http image works on Android and silently vanishes on iPhone — Retainza rejects http image URLs on save for exactly this reason.

### Sending to one platform only

A campaign's **Send to** setting (Message → Push) restricts delivery to iOS, Android or web devices. It filters *tokens*, not the audience: someone with an iPhone and an Android tablet gets the push on exactly the matching device, and someone with no matching device is skipped rather than counted as a failure.

> **Note:** Prefer this over a segment on the `platform` attribute for delivery. That attribute records the last device that called `identify`, so on a multi-device user it will pick the wrong one. A `platform` segment is still the right tool for a question about *who* your audience is.

### Sound and badge

A campaign's **sound** maps to `aps.sound` on iOS and `android.notification.sound` on Android; a custom sound must be bundled in the app under that name. **Badge** sets `aps.badge` on iOS (`0` clears it); Android has no badge in FCM, so Retainza maps it to `notificationCount`, which only some launchers honour.

<!-- section: push-handlers -->

## 8. Push handlers & acks

FCM gives no delivery receipt. Push **delivered** and **opened** exist in Analytics only because the device reports them. Skip this step and every push campaign's funnel stops at **sent**.

```ts
import messaging from "@react-native-firebase/messaging";
import { parseRetainzaPush, Retainza } from "@retainza/react-native";

const engage = Retainza.get();

// Foreground: report delivery. Do NOT navigate — nobody tapped anything.
messaging().onMessage(async (remote) => {
  const push = parseRetainzaPush(remote?.data);
  if (push) await engage.ackPush(push.msgId, "delivered");
});

// Tapped while backgrounded: report the open, then navigate.
messaging().onNotificationOpenedApp(async (remote) => {
  const push = parseRetainzaPush(remote?.data);
  if (!push) return;                        // not ours — leave it alone
  await engage.ackPush(push.msgId, "opened");
  if (push.route) router.push({ pathname: push.route.screen, params: push.route.kv ?? {} });
});

// Cold start from a tap.
const initial = await messaging().getInitialNotification();
const push = parseRetainzaPush(initial?.data);
if (push) {
  await engage.ackPush(push.msgId, "opened");
  if (push.route) queuePendingRoute(push.route);   // see the warning below
}
```

> **Warning:** **Cold-start ordering.** `getInitialNotification()` resolves before your router has mounted, so navigating immediately does nothing at all. Keep a `pendingRoute` and flush it once navigation is ready.

`parseRetainzaPush` returns `null` for anything that is not an Retainza push, so other push SDKs in the same app pass through untouched. Every key Retainza sends is prefixed `engage_` for the same reason. Import it from the package root — `/ui` is a separate entry point so a background handler never pulls React in.

<!-- section: inapp -->

## 9. In-app messages

Mount one component near your app root. That is the entire in-app integration.

```ts
// app/_layout.tsx
import { RetainzaInApp } from "@retainza/react-native/ui";
import { usePathname } from "expo-router";

<RetainzaInApp
  currentScreen={usePathname()}                       // optional "where to show" gate
  blockedScreenPrefixes={["/(auth)", "/onboarding"]}  // never interrupt these
  intervalMs={15000}                                  // default
/>
```

It owns polling, the queue (one message at a time, the rest stay pending), the `shown` / `clicked` / `dismissed` acks that feed Analytics, and CTA deep links. A blocked screen leaves a message pending rather than consuming it, so nothing is lost.

Layouts are slot lists chosen in the dashboard — image/video, header, title, body and up to three buttons — so a new layout never needs an app release. The same component renders native layouts, Custom HTML messages (in a sandboxed WebView), popups, bottom sheets, banners and full screens.

### Overriding the look

```ts
<RetainzaInApp presentations={{ banner: MyBanner }} />   // just the banner

<RetainzaInApp render={(msg, { onCta, onDismiss }) => (
  <MyOwnSheet message={msg} onPrimary={onCta} onClose={onDismiss} />
)} />

// Your own analytics, after the SDK's ack:
<RetainzaInApp onCta={(msg) => log("cta", msg.msgId)} onDismiss={(msg) => log("close", msg.msgId)} />
```

`presentations` accepts `banner`, `modal`, `bottomsheet`, `fullscreen` and `html`; each receives `{ message, onCta, onDismiss, onButton }`.

### Self-handled messages

The escape hatch: the **Self-handled** presentation delivers the payload and draws nothing, so a message can live inside your own UI — a card in a feed, a themed sheet — and still get Retainza's targeting, scheduling and analytics.

```ts
Retainza.get().onSelfHandledInApp((msg) => setPromo(msg));

useEffect(() => promo.markShown(), []);             // counts as delivered
<Button onPress={() => promo.markClicked()} />      // acks, then deep-links
<Close  onPress={() => promo.markDismissed()} />
```

> **Warning:** Those acks are yours to send. Retainza cannot see your view, so a self-handled campaign that never calls `markShown` reports zero deliveries however many people saw it.

<!-- section: deeplinks -->

## 10. Deep links

A campaign's **screen** is a path in *your* app. Retainza carries the path and its parameters; your app resolves them. Register the router once and both push CTAs and in-app CTAs route through it.

```ts
import { router } from "expo-router";

Retainza.get().onNavigate((route) =>
  router.push({ pathname: route.screen, params: route.kv ?? {} }),
);
```

The campaign builder offers a dropdown of known screens rather than a free-text path. That list is your app's config, in `dashboard/src/lib/screenCatalog.ts` — add a screen there and it appears for every campaign; a **Custom…** option always remains.

<!-- section: consent -->

## 11. Consent & privacy

### What the SDK collects on its own

Everything automatic is device and app context — no permission prompt, no PII, nothing that identifies a person: platform, OS, app version, SDK version, install date, language, country, timezone, session counters. The `country` comes from the device *locale*, not from GPS.

Identity is the opposite: `first_name`, `last_name`, `email`, `phone`, `gender`, `birthdate` are only ever what your app passes to `identify`. The SDK cannot invent them, and a unit test asserts the two lists never overlap.

### Gating collection on consent

```ts
Retainza.init({ …, requireConsent: true });   // nothing leaves the device yet

// after your consent UI:
await Retainza.get().setConsent({ analytics: true, marketing: false });
```

With `requireConsent` on, **every** call is suppressed until `analytics` is true — enforced at the transport, not per method, so a method added later cannot leak. Suppressed calls are dropped, never queued: replaying them after the fact is the thing consent forbids. `identify`, `track`, `setAttributes` and collection writes resolve quietly; `registerPush`, `ackPush`, `ackInApp` and `fetchPendingInApp` reject with a `ConsentError`.

> **Note:** `analytics` and `marketing` are separate on purpose. Someone can accept product analytics and refuse promotions; collapsing them into one switch makes that unrepresentable. `marketing` does not gate transport — it is stored as `consent_marketing` so campaigns can exclude on it.

### Opting out entirely

```ts
await Retainza.get().optOut();   // stops everything, clears the queue
Retainza.get().optIn();          // resume
```

> **Warning:** `optOut` is deliberately **not** persisted. An opt-out the SDK remembers is one your app cannot see, and your app owns the consent UI — re-assert it on each launch from your own stored preference.

### Erasure

`reset()` is an identity clear, not a deletion. For a GDPR erasure use `DELETE /v1/users/:id`, or the **Erase** button on the user's profile in the dashboard — both remove the profile, attributes, events, deliveries and tokens.

<!-- section: logout -->

## 12. Logout & offline

> **Warning:** Call `reset()` when a user signs out. Without it the next person to use the device inherits the previous user's identity — their events, and their messages.

```ts
export async function signOut() {
  await Retainza.reset();   // BEFORE signOut, while the user id is still known
  await auth().signOut();
}
```

`reset()` first unregisters this device's push token from the profile being left (`DELETE /v1/token`, best-effort), then clears the cached user id, the offline queue, the session counters and `startInAppPolling`. It is not a data deletion — the server profile is untouched (use `DELETE /v1/users/:id` for an erasure). `install_date` and the install id deliberately survive: they describe the device, not the user, so an install-date campaign does not re-fire for the next person who signs in.

### The offline queue

`track` and `identify` are queued on a network error or a 5xx and replayed oldest-first, carrying their original timestamps. A 4xx is not queued — it would fail forever and block everything behind it. Capacity is 100; the oldest are dropped on overflow. With a `storage` adapter the queue survives a restart; without one it survives a network blip but not a relaunch.

<!-- section: attributes -->

## Attribute reference

Reserved attribute names. The dashboard gives these real labels, formats dates and durations, and groups them on the profile; anything else your app sends is a custom attribute and appears alongside them, equally filterable.

### Collected automatically

| Attribute | Notes |
| --- | --- |
| `platform` | ios \| android \| web |
| `os_name / os_version` | From React Native |
| `device_model / device_manufacturer` | Only if you pass `device` at init |
| `app_version` | Whatever you pass as appVersion |
| `sdk_version` | The SDK build — the first thing to check on a bug report |
| `install_date` | Stamped once into your storage adapter |
| `language / country / tz` | From Intl. tz drives user-local scheduling |
| `session_count, first_session_at, last_session_at, session_duration_total` | Session tracking |
| `last_active` | Backend — refreshed on every identify and track |
| `push_permission` | You report it; see below |

### Only from your app

| Attribute | Notes |
| --- | --- |
| `first_name / last_name` | identify(…, { firstName, lastName }) |
| `email` | Also stored as a column so the Users list can show it |
| `phone` | E.164 recommended |
| `gender` | Free text — your app's vocabulary |
| `birthdate` | ISO-8601, e.g. 1994-07-21 |
| `consent_marketing / consent_analytics` | setConsent() |

### Push permission

The SDK never asks for notification permission — prompting is a product decision with one shot per install, so it belongs to your app. Report what you already know:

```ts
const status = await messaging().requestPermission();
await Retainza.get().setPushPermission(
  status === messaging.AuthorizationStatus.AUTHORIZED ? "authorized"
  : status === messaging.AuthorizationStatus.PROVISIONAL ? "provisional"
  : status === messaging.AuthorizationStatus.DENIED ? "denied"
  : "undetermined",
);
```

> **Warning:** Report the **denied** case too, and report it before any early return. A denied user keeps a perfectly valid token and silently receives nothing — without this attribute the dashboard cannot tell them apart from a reachable one, and “the push never arrived” has no answer.

<!-- section: checklist -->

## Integration checklist

Before you call the integration done:

- Retainza.init runs before the first screen, with an https base URL and a pk_ key.
- identify() passes firstName/lastName/email/phone, not just the id.
- setPushPermission() is reported on every branch — including denied.
- track() covers the events your campaigns will target.
- registerPush() is called after permission is granted, and again from onTokenRefresh.
- ackPush() is wired in all three handlers — foreground, background tap, cold start.
- <RetainzaInApp /> is mounted near the app root, with auth/onboarding screens blocked.
- onNavigate() is registered and cold-start routes are queued until the router mounts.
- reset() runs on logout — it clears the session counters too.
- If identity verification is on: identify() passes the userHash from your server on every launch.
- apnsEnvironment is 'production' in store builds.

<!-- section: troubleshooting -->

## Troubleshooting

Start with `debug: __DEV__` — it logs every request, poll, ack and swallowed error. Values are never logged, only key names and a prefix of the public key. With `debug` off the SDK writes nothing to the console.

| Symptom | Usual cause |
| --- | --- |
| No users appear in the dashboard | identify() never ran, or the base URL is wrong. Turn on debug and call testConnection() — it hits GET /health. |
| Works in debug, dead in release | A plain http:// base URL (blocked by Android release builds), or a stale bundle still holding the old EXPO_PUBLIC_ value. |
| Push sends but never arrives | No token registered (permission denied, or onTokenRefresh not wired), the FCM connection belongs to a different Firebase project than the one in the build, or (iOS) no APNs key uploaded to Firebase. |
| Push arrives, Analytics shows only 'sent' | ackPush() is not wired. FCM gives no delivery receipt — the device is the only source of delivered/opened. |
| Image push is plain text on iPhone | No Notification Service Extension in the app, or an http image URL. |
| In-app message never shows | The current screen matches a blockedScreenPrefixes entry, or a Self-handled campaign has no onSelfHandledInApp handler — the message stays pending rather than being consumed. |
| CTA does nothing | onNavigate() was never registered, or the screen path is not a route in this app. |
| The dashboard shows the user id but no name or email | identify() is being called with only an id. Pass the third argument — see Identify & track. |
| Sessions stay at 0 | autoSession is off, or no storage adapter was passed so the counters reset every launch. |
| A user looks reachable but receives nothing | push_permission is denied: a valid token with notifications switched off at the OS level. Check the Reachability column in Users. |
| An iOS-only campaign reached nobody | Nobody in the audience has an iOS token. The campaign's Send-to setting filters devices, not people — the Users list shows the platform split. |

<!-- section: not-yet -->

## Not supported yet

So you do not go looking for them: these exist in some other engagement SDKs but not in Retainza today. Everything above is shipped and testable.

- **Cards / notification inbox** — no persistent message feed or notification-centre history API.
- **Location-triggered and device-triggered notifications** — no geofence entry/exit or on-device trigger evaluation.
- **Push amplification / OEM push kits** (HMS and similar) — delivery is FCM only (iOS via FCM's APNs bridge).

Not a React Native app? There are guides for [iOS (Swift)](https://developer.retainza.com/ios/), [Android (Kotlin)](https://developer.retainza.com/android/) and [Flutter](https://developer.retainza.com/flutter/), and for writing from your [backend](https://developer.retainza.com/server/). Anything else can call the [HTTP API](https://developer.retainza.com/#api) directly.

---

<!-- Source: https://developer.retainza.com/ios/ · Markdown: https://developer.retainza.com/ios.md -->

Available · Swift Package Manager

# Retainza iOS SDK

Identify users, track events, receive push and show in-app messages from a native Swift app.

<!-- section: overview -->

## Overview

`RetainzaSDK` is the native Swift client for Retainza. It identifies users, tracks events, registers the device for push and displays in-app messages — talking only to Retainza's public-key-scoped ingest API.

- Requires **iOS 15+** and **Xcode 15+**.
- The SDK itself has no third-party dependencies. Receiving push also needs Firebase Messaging in your app (see [Push](https://developer.retainza.com/ios/#push)).
- Available through Swift Package Manager. CocoaPods is not available yet — see [Platform support](https://developer.retainza.com/#platforms).

> **Note:** The behaviour described here is shared with the [React Native SDK](https://developer.retainza.com/react-native/) — attribute rules, the offline queue, sessions and consent are identical by design, and that guide is the longer prose version. This page covers what is different on iOS.

<!-- section: install -->

## 1. Install

**Step 1:** Swift Package Manager (primary)

In Xcode choose **File ▸ Add Package Dependencies** and paste the repository URL, or declare it in `Package.swift`:

**Xcode**

```
https://github.com/appunik-retainza/ios-sdk
```

**Package.swift**

```swift
.package(url: "https://github.com/appunik-retainza/ios-sdk.git", from: "1.0.0")
```

> **Warning:** **CocoaPods is not available yet.** The SDK ships a podspec, but `RetainzaSDK` is not published to the CocoaPods trunk, so `pod 'RetainzaSDK'` will not resolve. Use Swift Package Manager.

### Import the module, not the product

Either way, the import is the **module** name:

```swift
import RetainzaSDK
```

> **Warning:** With SPM you add the *product* `Retainza` to your target, but Swift imports modules, not products, and the module is `RetainzaSDK`. `import Retainza` will not compile.

<!-- section: initialize -->

## 2. Start the SDK

In your `App` or `AppDelegate`, as early as possible:

```swift
import RetainzaSDK

try? Retainza.start(with: RetainzaConfig(
    // Debug builds: pk_test_… (Sandbox). Release builds: pk_live_… (Production).
    // Set it per build configuration with an xcconfig.
    publicKey: "pk_test_…",
    userProvider: { AuthStore.shared.userId }
))
```

> **Warning:** **The key decides the environment.** A build carrying `pk_live_…` reaches your real users, whatever else it is configured with. Note also that the `aps-environment` entitlement is **Apple's** push environment and is independent of the Retainza one — both must be set, consistently. See [Keys & base URL](https://developer.retainza.com/#concepts).

`publicKey` **must** start with `pk_`. The client refuses to initialise with a secret (`sk_`) key — those reach the campaign and send APIs, and anyone can extract a string from a shipped IPA.

`userProvider` is called on every request, so the SDK always uses your current user without you re-telling it. It is authoritative: the id cached by `identify` is only a fallback.

### Configuration worth knowing about

| Option | Default | Why you would change it |
| --- | --- | --- |
| `baseURL` | `https://api.retainza.com/v1` | Self-hosted backend. Must end in /v1. |
| `storage` | `UserDefaultsStorage()` | Supply your own store, or `InMemoryStorage()` in tests. `nil` makes the queue, session and install id memory-only. |
| `defaultAttributes` | `nil` | A closure whose attributes ride along on every `identify`. |
| `allowRuntimeBaseURL` | same as `debug` | Lets `setBaseURL(_:)` / a stored override redirect traffic. Keep off in release builds. |
| `requireConsent` | `false` | GDPR/CCPA — see [Consent](https://developer.retainza.com/ios/#consent). |
| `sessionTimeoutMs` | 30 min | How long in the background ends a session. |
| `maxQueuedEvents` | 100 | Offline queue capacity. |
| `debug` | `false` | Logs every request. **Off in production** — when off the SDK prints nothing. |
| `logger` | `nil` | Route SDK warnings into your crash reporter. Receives warn/error even when `debug` is off. |

With the default storage the SDK keeps its state in `UserDefaults.standard` under `engage.queue.v1`, `engage.session.v1`, `engage.install.v1`, `engage.push.v1` and `engage.baseUrl.v1`. Consent and opt-out are **not** stored (see [Consent](https://developer.retainza.com/ios/#consent)).

<!-- section: tracking -->

## 3. Identify & track

```swift
// Full profile upsert. Auto attributes ride along on every call.
try await Retainza.shared?.identify(
    "user-123",
    attributes: ["plan": "pro", "seats": 4],
    profile: RetainzaProfile(firstName: "Ada", email: "ada@example.com")
)

// A patch — sends only what you pass.
try await Retainza.shared?.setAttributes(["plan": "enterprise"])

// An event.
try await Retainza.shared?.track("order_placed", properties: ["total": 42.5])
```

Attribute values are `String`, `Double`, `Bool` or `nil` — nothing nested. Literals work directly: `["plan": "pro", "seats": 4, "trial": true]`.

### Collections — one-to-many data

When a user can have several of something (challenges, badges, saved searches), that is a *collection*, not a pile of numbered attributes.

```swift
// Id only, when the list is identifiers and nothing else:
try await Retainza.shared?.addToCollection("challenges", id: "lagos_10k")

// With fields, when a campaign has to FIND things in the list:
try await Retainza.shared?.addToCollection(
    "challenges",
    item: CollectionItem("lagos_10k", ["status": "done", "progress": 100])
)

try await Retainza.shared?.removeFromCollection("challenges", id: "lagos_10k")
try await Retainza.shared?.setCollection("challenges", items: ["a", "b"])  // replaces; empty clears
```

The `id` is **yours** and is the merge key: writing the same id twice updates that item instead of appending, which is what makes a write replayed from the offline queue safe. Fields you omit are preserved.

Item fields are flat `AttrValue`s — same four cases as attributes, no nesting. `updated_at` is stamped by the server. A `CollectionItem` is `ExpressibleByStringLiteral`, so `["a", "b"]` is a list of id-only items. The [React Native guide](https://developer.retainza.com/react-native/) covers the caps and a worked “challenge finished → send a message” example.

### On logout, call reset()

Without it the next person on the device inherits the previous user's identity, queued events, session counters — and the previous user's **push notifications**, because nothing else takes a token off a profile.

```swift
await Retainza.shared?.reset()
```

`reset()` unregisters this device from the profile being left (best-effort: an offline logout still succeeds). It deliberately keeps the **install id**, which describes the device rather than the person — it is what tells the server a rotated push token is the same handset, so clearing it would make every sign-in look like a new phone.

> **Note:** `userProvider` is yours: if it still returns the old id after logout, the SDK will use it.

### Attributes the SDK sets for you

`platform`, `sdk_version`, `app_version`, `language`, `country`, `tz`, `device_model`, `device_manufacturer`, `os_name`, `os_version`, `session_count`, `first_session_at`, `last_session_at`, `session_duration_total`, `push_permission`.

The `session_*` values only exist once you drive sessions (see [Sessions](https://developer.retainza.com/ios/#sessions)), and `push_permission` only once `RetainzaPush` reports it (see [Push](https://developer.retainza.com/ios/#push)).

Precedence is **SDK-collected → `config.defaultAttributes` → the values you pass at the call site**. Your value always wins: if you set `country` from a billing address, the SDK will not overwrite it.

> **Tip:** Event names are matched by exact string in segments, so pick a convention and keep it — lowercase snake_case past-tense (`order_placed`) is what the docs and dashboard assume.

<!-- section: push -->

## 4. Push

### Xcode setup the SDK cannot do for you

The SDK cannot edit your project file, and these are silent failures if missed:

1. **Signing & Capabilities ▸ + Capability ▸ Push Notifications.** Without the `aps-environment` entitlement iOS never issues a token at all, and nothing reports an error.
2. **Background Modes ▸ Remote notifications**, if you send silent pushes.
3. Upload your **APNs key (`.p8`)** to Firebase Cloud Messaging, since Retainza sends via FCM. This is a console step, not a code one.
4. **Add Firebase Messaging to the app** (`FirebaseMessaging` via SPM, plus your `GoogleService-Info.plist`). See the next section.

### The token Retainza needs is the FCM token, not the APNs token

Retainza sends every push through **FCM** (`firebase-admin`, addressed by registration token). FCM cannot deliver to a raw APNs device token: sent one, it answers `invalid-registration-token` and the server prunes the device as dead.

So in an app using Retainza push, let Firebase turn the APNs token into an FCM token, and register **that** with `RetainzaPush.handleFCMToken(_:)`.

> **Warning:** `RetainzaPush.handleDeviceToken(_:)` is **deprecated**. It used to register the raw APNs token, which gave you a device in the dashboard that never received a push; it now only logs a warning and registers nothing. If you still call it, replace it with the code below.

### Code

```swift title="AppDelegate.swift"
import FirebaseCore
import FirebaseMessaging
import RetainzaSDK

// In didFinishLaunchingWithOptions:
FirebaseApp.configure()
Messaging.messaging().delegate = self
UNUserNotificationCenter.current().delegate = self
Task { await RetainzaPush.handleLaunchOptions(launchOptions) }
Task {
    // Returning users who already answered the prompt: fetch a fresh token and
    // refresh push_permission. First-time prompting happens elsewhere (below).
    if await RetainzaPush.currentPermission() != .undetermined {
        await RetainzaPush.registerForRemoteNotifications()
    }
    await RetainzaPush.syncPermission()
}

func application(_: UIApplication,
                 didRegisterForRemoteNotificationsWithDeviceToken token: Data) {
    // Hand the APNs token to Firebase — it produces the FCM token below.
    Messaging.messaging().apnsToken = token
}

// MessagingDelegate — fires on first launch and whenever FCM rotates the token.
func messaging(_: Messaging, didReceiveRegistrationToken fcmToken: String?) {
    guard let fcmToken else { return }
    Task { try? await RetainzaPush.handleFCMToken(fcmToken) }
}

func application(_: UIApplication,
                 didFailToRegisterForRemoteNotificationsWithError error: Error) {
    RetainzaPush.handleRegistrationFailure(error)
}
```

And in your `UNUserNotificationCenterDelegate`:

```swift
func userNotificationCenter(_: UNUserNotificationCenter,
                            willPresent notification: UNNotification) async
                            -> UNNotificationPresentationOptions {
    await RetainzaPush.handleForeground(notification)
    return [.banner, .sound]
}

func userNotificationCenter(_: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse) async {
    await RetainzaPush.handleOpen(response)
}
```

Each handler returns `true` if the notification was a Retainza one, so an app running a second push SDK can tell whether to keep processing.

For silent pushes, call `await RetainzaPush.handleBackground(userInfo)` from `application(_:didReceiveRemoteNotification:fetchCompletionHandler:)`.

`handleFCMToken` (a wrapper over `registerPush(token:)`) needs a user: it resolves the id from `userProvider` or the last `identify`, and throws `.missingUserId` otherwise. If the token can arrive before sign-in, call it again after `identify` with the current token from `try await Messaging.messaging().token()`. An unchanged token is re-sent at most once every 24 hours; pass `force: true` to override that.

> **Tip:** `handleLaunchOptions` is easy to skip and worth not skipping: a tap that *launches* the app never reaches the delegate, so without it every cold-start open goes uncounted.

### When to prompt

`requestAuthorization()` triggers the system prompt. iOS allows **one per install** — if the user denies it, nothing can ask again and only a trip to Settings recovers it. Call it when your app has explained why, not at launch. The SDK deliberately never calls it for you.

```swift
try? await RetainzaPush.requestAuthorization()  // registers with APNs if granted
```

Permission can also be revoked in Settings at any time with no callback, so call `await RetainzaPush.syncPermission()` on launch (the launch snippet above does). Otherwise Retainza keeps targeting a device that stopped being reachable months ago.

<!-- section: inapp -->

## 5. In-app messages

One mount point, at the root of your view hierarchy:

```swift
WindowGroup {
    ContentView()
        .engageInApp()
}
```

That is the whole integration (it polls every 15 s; pass `.engageInApp(intervalMs:)` to change that). It owns the poll loop, shows one message at a time, and sends the `shown` / `clicked` / `dismissed` acks every campaign's funnel is built from.

> **Warning:** Apply it **once**. Messages arrive on a timer, not on navigation, so a per-screen mount would poll N times over and race to show the same campaign twice.

### Navigation

Campaigns route by *screen name*, not URL — marketers author against your screens, not a deep-link scheme:

```swift
await Retainza.shared?.onNavigate { route in
    Task { @MainActor in router.go(to: route.screen, params: route.kv ?? [:]) }
}
```

Without this a tap still acks correctly but goes nowhere. The SDK logs a warning naming the missing call. The handler (like `onSelfHandledInApp`) is called off the main thread, so hop to the main actor before touching UI.

### Not now, thanks

Some screens must not be interrupted:

```swift
await Retainza.shared?.setBlockedScreenPrefixes(["checkout", "video"])
await Retainza.shared?.setCurrentScreen("checkout/payment")
```

A blocked message stays **pending** rather than being consumed, so the campaign shows on the next poll once the user moves on.

### Rendering it yourself

For a `selfhandled` campaign the SDK draws nothing and hands you the payload. In exchange **you own the acks** — skipping them does not break rendering, it silently empties that campaign's funnel:

```swift
await Retainza.shared?.onSelfHandledInApp { message in
    myPresenter.show(message.content) {
        message.markShown()
    } onTap: {
        message.markClicked(nil)
    } onClose: {
        message.markDismissed()
    }
}
```

`markClicked(nil)` also navigates to the message's own route through your `onNavigate` handler; pass a `Route` to go somewhere else.

> **Note:** A `selfhandled` message with no handler registered stays pending rather than disappearing — a half-finished integration should look like a campaign that has not shown yet, not one that vanished.

<!-- section: offline -->

## 6. Offline queue

`track`, `identify`, `setAttributes` and the collection calls are queued when a call fails with a network error or a 5xx, and retried with exponential backoff (1 s doubling to a 5-minute ceiling).

- **4xx is never queued.** A malformed body or a revoked key fails the same way forever, and queueing it would block every event behind it.
- **Ordering is preserved.** A flush stops at the first failure rather than skipping ahead.
- **Timestamps are stamped at call time**, so an event that waits an hour still records when it actually happened.
- **The oldest is dropped** past `maxQueuedEvents` (100). A device offline for a week should send this morning's events, not last week's.
- The queue survives restarts (it lives in `storage`).
- `registerPush` and the acks are **never** queued — a stale token is worse than a missing one, and a replayed ack lands in the wrong reporting window.

Inspect it with `queueSize()`; drain it manually with `flushQueue()`.

<!-- section: consent -->

## 7. Consent

Off by default, because turning it on silently would drop every existing integration's data.

```swift
RetainzaConfig(publicKey: "pk_…", requireConsent: true)
```

With it on **nothing** leaves the device — not even an identify — until:

```swift
await Retainza.shared?.setConsent(analytics: true, marketing: false)
```

Pre-consent calls are **dropped, not queued**: replaying them afterwards is exactly what consent forbids.

> **Warning:** Consent is **not persisted** by the SDK: with `requireConsent` on, call `setConsent` on every launch from your own stored answer, or nothing is sent.

`marketing` does not gate transport. It is stored as `consent_marketing` (and `analytics` as `consent_analytics`) so campaigns can target or exclude on it — someone can accept product analytics and refuse promotions, and collapsing the two makes that unrepresentable.

`optOut()` is a harder switch: it stops everything and clears the queue. It is deliberately **not persisted** — an opt-out the SDK remembers is one your app cannot see, and your app owns the consent UI. Re-assert it each launch from your own stored preference; `await Retainza.shared?.optIn()` lifts it.

<!-- section: sessions -->

## 8. Sessions

> **Warning:** **Not automatic on iOS** — the SDK does not observe the app lifecycle, so you call these from your foreground/background hooks. Without them no `session_start` events and no `session_*` attributes are ever sent.

```swift
await Retainza.shared?.startSession()   // app became active
await Retainza.shared?.endSession()     // app entered the background
```

In SwiftUI, drive them from `scenePhase` (`.active` → `startSession`, `.background` → `endSession`). A new session starts on foreground unless the app returns within `sessionTimeoutMs` (30 minutes) of the last `endSession`; then it **resumes** the same session rather than inflating the count — so a user who checks a push and comes back is not counted twice.

<!-- section: troubleshooting -->

## 9. Troubleshooting

| Symptom | Cause |
| --- | --- |
| `import Retainza` | Import the module: `import RetainzaSDK`. `Retainza` is only the SPM product name. |
| Init throws `.configuration` | You passed an `sk_` key. Only `pk_` keys belong in an app. |
| No push token, no error | Missing Push Notifications capability (`aps-environment`). |
| Device registered, pushes never arrive | An older build registered the raw APNs token. Register the FCM token with `RetainzaPush.handleFCMToken(_:)` — see [Push](https://developer.retainza.com/ios/#push). |
| Warning: “handleDeviceToken no longer registers” | Replace that call with `Messaging.messaging().apnsToken = token` plus `handleFCMToken` in `MessagingDelegate` — see [Push](https://developer.retainza.com/ios/#push). |
| Token never registers | No user yet (`.missingUserId`). Call `registerPush` again after `identify`. |
| Pushes arrive, opens are zero | `handleOpen` not wired, or `handleLaunchOptions` missing for cold starts. |
| In-app messages never appear | `.engageInApp()` not mounted, the current screen is blocked, or there is no user id yet. |
| Tapping a message goes nowhere | No `onNavigate` handler. Check the logs. |
| Events vanish offline | You passed `storage: nil`, so the queue is memory-only. |
| No sessions in the dashboard | `startSession()` / `endSession()` never called — see [Sessions](https://developer.retainza.com/ios/#sessions). |
| Nothing sends at all | `requireConsent` is on and `setConsent(analytics: true)` was not called this launch. |

Turn on `debug: true` in a dev build to log every request, poll and swallowed error. Check connectivity with `await Retainza.shared?.testConnection()`.

---

<!-- Source: https://developer.retainza.com/android/ · Markdown: https://developer.retainza.com/android.md -->

Built, not yet published · Gradle

# Retainza Android SDK

Native Kotlin client: identify users, track events, receive FCM push and show in-app messages.

<!-- section: overview -->

## Overview

`com.retainza:retainza-android` is the native Kotlin client for Retainza. Identify users, track events, receive push, and display in-app messages. It requires **Android 7.0 (API 24)+** and **JDK 17**.

The behaviour is shared with the React Native SDK — attribute rules, the offline queue, sessions and consent are identical by design, and the [React Native guide](https://developer.retainza.com/react-native/) is the longer prose version. This page covers what is different on Android.

> **Warning:** **Not on Maven Central yet.** Version `1.0.0` is built but has not been released — the Sonatype namespace setup is still outstanding. Until it is, install it into your local Maven repository as described in [Install](https://developer.retainza.com/android/#install).

<!-- section: install -->

## 1. Install

```kotlin title="app/build.gradle.kts"
implementation("com.retainza:retainza-android:1.0.0")
```

Once released, it resolves from Maven Central — no extra repository declaration needed.

> **Warning:** **Not on Maven Central yet.** `1.0.0` has not been released. Until it is, publish it to your local Maven repository from the Retainza SDK repo with `./scripts/release-sdk-android.sh --local` (it publishes to `~/.m2`), and add `mavenLocal()` to the repositories in `settings.gradle.kts` — and remove it again before committing.

**Step 1:** Local install, until the release

```bash
./scripts/release-sdk-android.sh --local
```

```kotlin title="settings.gradle.kts"
dependencyResolutionManagement {
    repositories {
        mavenLocal() // temporary — remove before committing
        google()
        mavenCentral()
    }
}
```

### What it pulls in

The published artifact brings **three** dependencies: coroutines, `androidx.core`, and the Kotlin stdlib. Firebase and Compose are deliberately *not* among them — add them yourself only for the features that need them:

```kotlin title="app/build.gradle.kts"
// Only if you use Retainza push — you need this for your own
// FirebaseMessagingService anyway.
implementation("com.google.firebase:firebase-messaging:24.1.0")

// Only if you display in-app messages. Your app's Compose version wins.
implementation(platform("androidx.compose:compose-bom:2024.09.03"))
implementation("androidx.compose.material3:material3")
```

> **Note:** An app using Retainza purely for analytics should not inherit Firebase, the google-services plugin, and a `google-services.json` it has no use for. The SDK checks for these at runtime and degrades to a logged warning.

<!-- section: initialize -->

## 2. Start the SDK

In `Application.onCreate`:

```kotlin title="MyApp.kt"
import com.retainza.sdk.Retainza
import com.retainza.sdk.RetainzaConfig

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Retainza.start(
            this,
            RetainzaConfig(
                // Debug builds: pk_test_… (Sandbox). Release: pk_live_…
                // Set it per build variant with buildConfigField — see below.
                publicKey = "pk_test_…",
                userProvider = { AuthStore.userId },
            ),
        )
    }
}
```

> **Tip:** **The key decides the environment.** Set it per build variant so debug builds carry `pk_test_…` and release builds carry `pk_live_…`, then use `publicKey = BuildConfig.RETAINZA_KEY`. Your `google-services.json` must also belong to the Firebase project configured on **that environment's** FCM connection (Sandbox and Production are independent).

```kotlin title="app/build.gradle.kts"
android {
    buildTypes {
        debug   { buildConfigField("String", "RETAINZA_KEY", "\"pk_test_xxxxxxxxxxxx\"") }
        release { buildConfigField("String", "RETAINZA_KEY", "\"pk_live_xxxxxxxxxxxx\"") }
    }
}
```

`publicKey` **must** start with `pk_`. The client throws on a secret (`sk_`) key — those reach the campaign and send APIs, and anyone can unzip an APK.

`Retainza.start` fills in the two things that need a `Context`: a private SharedPreferences store, and the device/app facts (`Build.MODEL`, `Build.MANUFACTURER`, your `versionName`). `RetainzaClient` itself holds no Android types, which is why it is unit-testable with no Robolectric.

`userProvider` is called on every request, so the SDK always uses your current user. It is authoritative: the id cached by `identify` is only a fallback.

### Configuration worth knowing about

| Option | Default | Why you would change it |
| --- | --- | --- |
| `baseUrl` | https://api.retainza.com/v1 | Self-hosted backend. Must end in /v1. |
| `storage` | SharedPreferences (set by Retainza.start) | Supply your own, or InMemoryStorage() in tests. A RetainzaClient built directly with no storage is memory-only. |
| `requireConsent` | false | GDPR/CCPA — see Consent. |
| `sessionTimeoutMs` | 30 min | How long in the background ends a session. |
| `maxQueuedEvents` | 100 | Offline queue capacity. |
| `debug` | false | Logs every request. Off in production — when off the SDK writes nothing to Logcat. |
| `logger` | null | Route SDK warnings into your crash reporter. Receives WARN/ERROR even when debug is off. |
| `defaultAttributes` | null | A lambda of extra attributes merged into every identify. |
| `allowRuntimeBaseUrl` | same as debug | Lets setBaseUrl() override baseUrl at runtime (stored). setBaseUrl throws when this is off. |

The default store is a private SharedPreferences file, `com.retainza.sdk.storage`, holding `engage.queue.v1`, `engage.session.v1`, `engage.install.v1`, `engage.push.v1` and `engage.baseUrl.v1` — the same keys every Retainza SDK uses.

<!-- section: tracking -->

## 3. Identify & track

Every ingest call is a `suspend` function — call it from a coroutine.

```kotlin
// Full profile upsert. Auto attributes ride along on every call.
Retainza.client?.identify(
    "user-123",
    mapOf("plan" to "pro".attr, "seats" to 4.attr),
    RetainzaProfile(firstName = "Ada", email = "ada@example.com"),
)

// A patch — sends only what you pass.
Retainza.client?.setAttributes(mapOf("plan" to "enterprise".attr))

// An event.
Retainza.client?.track("order_placed", mapOf("total" to 42.5.attr))
```

The `.attr` extension builds an `AttrValue` from a `String`, `Int`, `Long`, `Double` or `Boolean`; use `AttrValue.Null` to clear a value. Numbers travel as `Double` — nothing nested.

Calls other than `identify` need a user id: pass `userId =`, have `userProvider` return one, or call `identify` first. Otherwise they throw `RetainzaException.MissingUserId`.

### Collections — one-to-many data

When a user can have several of something (challenges, badges, saved searches), that is a *collection*, not a pile of numbered attributes.

```kotlin
// Id only, when the list is identifiers and nothing else:
Retainza.client?.addToCollection("challenges", "lagos_10k")

// With fields, when a campaign has to FIND things in the list:
Retainza.client?.addToCollection(
    "challenges",
    CollectionItem("lagos_10k", mapOf("status" to "done".attr, "progress" to 100.attr)),
)

Retainza.client?.removeFromCollection("challenges", "lagos_10k")
Retainza.client?.setCollection("challenges", listOf("a".item, "b".item))  // replaces; empty list clears
```

The `id` is **yours** and is the merge key: writing the same id twice updates that item instead of appending, which is what makes a write replayed from the offline queue safe. Fields you omit are preserved.

Item fields are flat `AttrValue`s — same four types as attributes, no nesting. `updated_at` is stamped by the server. See the [main docs](https://developer.retainza.com/#concepts) for the caps and for the worked “challenge finished → send a message” example.

### Logout

> **Warning:** **On logout, call `reset()`.** Without it the next person on the device inherits the previous user's identity, queued events, session counters — and the previous user's **push notifications**, because nothing else takes a token off a profile.

```kotlin
Retainza.client?.reset()
```

`reset()` unregisters this device from the profile being left (best-effort: an offline logout still succeeds). It deliberately keeps the **install id**, which describes the device rather than the person — it is what tells the server a rotated FCM token is the same handset, so clearing it would make every sign-in look like a new phone.

Note that `userProvider` is yours: if it still returns the old id after logout, the SDK will use it.

### Attributes the SDK sets for you

`platform`, `sdk_version`, `app_version`, `language`, `country`, `tz`, `device_model`, `device_manufacturer`, `os_name`, `os_version`, `session_count`, `first_session_at`, `last_session_at`, `session_duration_total` (once you drive sessions — see [Sessions](https://developer.retainza.com/android/#sessions)), `push_permission` (once you call `syncPermission` — see [Push](https://developer.retainza.com/android/#push)).

Precedence is **SDK-collected → `config.defaultAttributes` → the values you pass at the call site**. Your value always wins.

> **Tip:** Event names are matched by exact string in segments — lowercase snake_case past-tense (`order_placed`) is what the docs and dashboard assume.

<!-- section: push -->

## 4. Push

### Manifest setup the SDK cannot do for you

A library manifest merges into every consuming app, so the SDK deliberately declares nothing — an app that does not use push must not inherit a notification permission, and unexplained permissions are a Play Store rejection reason.

```html title="AndroidManifest.xml"
<!-- Required on API 33+, or no notification is ever shown -->
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
```

Declare your messaging service (below) inside `<application>`:

```html title="AndroidManifest.xml"
<service
    android:name=".MyMessagingService"
    android:exported="false">
    <intent-filter>
        <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>
```

You also need `google-services.json` and the Google Services Gradle plugin, and your APNs key uploaded to Firebase if you also ship iOS.

### Code

Android delivers FCM callbacks to one service, and most apps already have their own — so the SDK does not ship one. Forward two calls from yours:

```kotlin title="MyMessagingService.kt"
import com.google.firebase.messaging.FirebaseMessagingService
import com.google.firebase.messaging.RemoteMessage
import com.retainza.sdk.push.RetainzaPush

class MyMessagingService : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        RetainzaPush.handleNewToken(token)
    }

    override fun onMessageReceived(message: RemoteMessage) {
        if (RetainzaPush.handleMessageReceived(message.data)) return
        // …your own push handling
    }
}
```

`handleMessageReceived` returns `true` if the message was a Retainza one, so an app running a second push SDK can return early rather than letting both process the same payload.

> **Note:** `handleMessageReceived` only acks `delivered`; it never draws anything. Retainza sends FCM *notification* messages, so in the background Android shows them itself and `onMessageReceived` is not called at all — `delivered` is only reported for pushes that arrive while the app is in the foreground, where Android shows nothing unless you post the notification yourself. The tap still acks `opened` either way.

> **Warning:** Forwarding `onNewToken` is not optional: FCM rotates tokens on reinstall and restore-from-backup, and a rotated token Retainza never learns about is a device that silently stops receiving campaigns.

In the Activity a notification tap opens — **both callbacks**, because an already-running Activity gets the second one:

```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    RetainzaPush.handleNotificationOpened(intent)
}

override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    RetainzaPush.handleNotificationOpened(intent)
}
```

Then register the token once you know who it belongs to — after login, not at launch, or it registers against nobody:

```kotlin
lifecycleScope.launch { RetainzaPush.fetchAndRegisterToken() }
```

Safe to repeat on every launch: an unchanged token registered less than 24 hours ago is not re-sent. Already have a token? `RetainzaPush.registerToken(token)`. Registration is never queued — if it fails offline, the next launch retries. `reset()` unregisters the device (`DELETE /v1/token`); `unregisterPush()` is public if you tear identity down your own way.

### Permission

The SDK never triggers the prompt — Android gives you one shot and when to spend it is a product decision. Request `POST_NOTIFICATIONS` yourself, then:

```kotlin
lifecycleScope.launch { RetainzaPush.syncPermission(this@MyActivity) }
```

Worth calling on every launch: permission can be revoked in Settings with no callback, and without a refresh Retainza keeps targeting an unreachable device.

> **Note:** Before API 33 there is no runtime permission, so the SDK reports `AUTHORIZED` — it cannot see a Settings-level block, and reporting denied would drop reachable devices out of every campaign.

<!-- section: inapp -->

## 5. In-app messages

One mount point, at the root of your Compose hierarchy, **inside** your theme:

```kotlin
import com.retainza.sdk.inapp.ui.RetainzaInAppHost

setContent {
    MyTheme {
        RetainzaInAppHost {
            AppNavHost()
        }
    }
}
```

That is the whole integration. It owns the poll loop, shows one message at a time, and sends the `shown` / `clicked` / `dismissed` acks every campaign's funnel is built from. Optional parameters: `client` (defaults to `Retainza.client`) and `intervalMs` (poll interval, default `15_000`).

It must be inside a `MaterialTheme` — the renderers read `MaterialTheme.colorScheme` for every colour a campaign did not specify.

> **Warning:** Apply it **once**. Messages arrive on a timer, not on navigation, so a per-screen mount would poll N times over and race to show the same campaign twice.

> **Note:** **Images are not rendered.** Compose has no built-in network image loader, and bundling Coil or Glide would force that dependency and its version on every consumer. The renderer reserves the correct aspect ratio so layout is stable, but the media slot draws a placeholder. Use a `selfhandled` campaign if a campaign genuinely needs imagery on Android. (iOS renders images natively via `AsyncImage`, which ships in the OS — this is the one place the two platforms differ.)

### Navigation

Campaigns route by *screen name*, not URL:

```kotlin
Retainza.client?.onNavigate { route ->
    navController.navigate(route.screen)
}
```

Without this a tap still acks correctly but goes nowhere. The SDK logs a warning naming the missing call (visible with `debug = true` or a `logger`).

### Not now, thanks

```kotlin
Retainza.client?.setBlockedScreenPrefixes(listOf("checkout", "video"))
Retainza.client?.setCurrentScreen("checkout/payment")
```

A blocked message stays **pending** rather than being consumed, so the campaign shows on the next poll once the user moves on.

### Rendering it yourself

For a `selfhandled` campaign the SDK draws nothing and hands you the payload. In exchange **you own the acks** — skipping them does not break rendering, it silently empties that campaign's funnel:

```kotlin
Retainza.client?.onSelfHandledInApp { message ->
    myPresenter.show(
        content = message.content,
        onShown = { message.markShown() },
        onTap = { message.markClicked(null) },
        onClose = { message.markDismissed() },
    )
}
```

A `selfhandled` message with no handler registered stays pending rather than disappearing — a half-finished integration should look like a campaign that has not shown yet, not one that vanished. A template this SDK version does not recognise is treated as `selfhandled` for the same reason.

<!-- section: offline -->

## 6. Offline queue

`track`, `identify`, `setAttributes` and the collection calls are queued when a call fails with a network error or a 5xx, and retried with exponential backoff (1s doubling to a 5-minute ceiling).

- **4xx is never queued.** A malformed body or a revoked key fails the same way forever, and queueing it would block every event behind it.
- **Ordering is preserved.** A flush stops at the first failure rather than skipping ahead.
- **Timestamps are stamped at call time**, so an event that waits an hour still records when it actually happened.
- **The oldest is dropped** past `maxQueuedEvents` (100).
- `registerPush` and the acks are **never** queued — a stale token is worse than a missing one, and a replayed ack lands in the wrong reporting window.

Inspect it with `queueSize()`; drain it manually with `flushQueue()`.

<!-- section: consent -->

## 7. Consent

Off by default, because turning it on silently would drop every existing integration's data.

```kotlin
RetainzaConfig(publicKey = "pk_…", requireConsent = true)
```

With it on **nothing** leaves the device — not even an identify — until:

```kotlin
Retainza.client?.setConsent(analytics = true, marketing = false)
```

> **Warning:** Pre-consent calls are **dropped, not queued**: replaying them afterwards is exactly what consent forbids.

`marketing` does not gate transport. It is stored as `consent_marketing` (and `analytics` as `consent_analytics`) so campaigns can target or exclude on it — someone can accept product analytics and refuse promotions.

`optOut()` is a harder switch: it stops everything and clears the queue. It is deliberately **not persisted** — an opt-out the SDK remembers is one your app cannot see, and your app owns the consent UI. Re-assert it each launch; `optIn()` lifts it.

<!-- section: sessions -->

## 8. Sessions

A session starts on foreground and ends after 30 minutes (`sessionTimeoutMs`) in the background; returning inside that window **resumes** the same session rather than inflating the count — so a user who checks a push and comes back is not counted twice.

Drive it from your process lifecycle:

```kotlin
ProcessLifecycleOwner.get().lifecycle.addObserver(
    LifecycleEventObserver { _, event ->
        scope.launch {
            when (event) {
                Lifecycle.Event.ON_START -> Retainza.client?.startSession()
                Lifecycle.Event.ON_STOP -> Retainza.client?.endSession()
                else -> Unit
            }
        }
    },
)
```

<!-- section: troubleshooting -->

## 9. Troubleshooting

| Symptom | Cause |
| --- | --- |
| Throws RetainzaException.ConfigurationError at start | You passed an sk_ key. Only pk_ keys belong in an app. |
| track throws RetainzaException.MissingUserId | No userId passed, userProvider returned null, and identify has not run. |
| setBaseUrl throws ConfigurationError | allowRuntimeBaseUrl (or debug) is off — by design in release builds. |
| fetchAndRegisterToken warns and returns null | firebase-messaging is not on the classpath. |
| No notification appears on API 33+ | POST_NOTIFICATIONS not declared, or not granted. |
| Pushes arrive, opens are zero | handleNotificationOpened not wired into both onCreate and onNewIntent. |
| Token stops working after a reinstall | onNewToken not forwarded. |
| In-app messages never appear | RetainzaInAppHost not mounted, or the current screen is blocked. |
| In-app messages look unstyled | Host mounted outside MaterialTheme. |
| Campaign images do not show | Expected — see In-app messages. |
| Tapping a message goes nowhere | No onNavigate handler. Check Logcat with debug = true. |
| Push delivered counts look low | Expected: background pushes never reach onMessageReceived — see Push. |
| Nothing sends at all | requireConsent is on and setConsent(analytics = true) was never called. |

Turn on `debug = true` in a dev build to log every request, poll and swallowed error. Check connectivity with `Retainza.client?.testConnection()` — a suspend call that hits `GET /health` and returns `ConnectionResult(ok, status)`.

---

<!-- Source: https://developer.retainza.com/flutter/ · Markdown: https://developer.retainza.com/flutter.md -->

Built, not yet published · pub

# Retainza Flutter SDK

Identify users, track events, register push and receive in-app messages from a Flutter app on iOS and Android.

<!-- section: overview -->

## Overview

`retainza_flutter` is the Dart client for Retainza. It identifies users, tracks events, keeps collections, registers push tokens and receives in-app messages from a Flutter app on iOS and Android.

- **Dart 3.4+** / **Flutter 3.22+**
- **iOS 15+** and **Android 7.0 (API 24)+**

Attribute rules, the offline queue, sessions and consent behave exactly as in the other client SDKs. The [concepts](https://developer.retainza.com/#concepts) section covers them at length; this page covers what is different in Flutter.

> **Warning:** **Not on pub.dev yet.** Version `1.0.0` has not been published, so a plain `retainza_flutter: ^1.0.0` dependency does not resolve today. See [Install](https://developer.retainza.com/flutter/#install) for what works now.

> **Note:** **Status.** Core tracking, push registration and in-app *delivery* are available. The built-in in-app UI (banner, modal, bottom sheet, fullscreen, HTML) is not yet — until it ships, render messages yourself ([In-app messages](https://developer.retainza.com/flutter/#inapp)).

<!-- section: install -->

## 1. Install

Once the package is published, the dependency will be:

```yaml title="pubspec.yaml"
dependencies:
  retainza_flutter: ^1.0.0
```

then `flutter pub get`.

> **Warning:** **Not on pub.dev yet.** `1.0.0` has not been published, so the line above does not resolve outside the Retainza repository today. The source repository is private, so a `git:` dependency does not work for external apps either. Inside the Retainza monorepo, depend on it by path:

```yaml title="pubspec.yaml"
dependencies:
  retainza_flutter:
    path: ../sdk/flutter/retainza_flutter
```

It brings in `http`, `shared_preferences`, `package_info_plus`, `device_info_plus` and `flutter_timezone`. Firebase is deliberately **not** a dependency — an app using Retainza only for analytics should not inherit it. Add it yourself if you use push ([Push](https://developer.retainza.com/flutter/#push)).

The SDK is pure Dart with no platform channels of its own: nothing to link, and no `pod install` steps beyond what the plugins above need.

<!-- section: initialize -->

## 2. Start the SDK

```dart title="lib/main.dart"
import 'package:flutter/foundation.dart';
import 'package:flutter/widgets.dart';
import 'package:retainza_flutter/retainza_flutter.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  Retainza.init(
    publicKey: const String.fromEnvironment('RETAINZA_PK'), // pk_test_… or pk_live_…
    debug: kDebugMode,
  );
  runApp(const MyApp());
}
```

Then use `Retainza.instance` anywhere. Call `init` once; calling it again replaces the client. `Retainza.instance` throws a `StateError` if `init` has not run.

Only a **public** key (`pk_…`) is accepted — a secret key throws `ArgumentError`. The key decides the environment, read back as `Retainza.instance.environment` (`RetainzaEnvironment.test` for `pk_test_`, `.live` for `pk_live_`, `.unknown` for any other `pk_` key). There is no runtime switch.

> **Warning:** A `pk_live_` key in a debug build (or with `debug: true`) logs a warning: its events and device tokens land in Production. Use a `pk_test_` key for development.

Platform facts (timezone, device, app version, install date) resolve asynchronously. Await them before the very first `identify` if it must carry them — every later call carries them regardless:

```dart
await Retainza.ready();
```

### Configuration worth knowing about

All of these are named parameters of `Retainza.init`:

| Parameter | Default | What it does |
| --- | --- | --- |
| `baseUrl` | `--dart-define=ENGAGE_BASE_URL`, else `https://api.retainza.com/v1` | Ingest API |
| `userProvider` | — | `() => currentUserId`; authoritative when non-null |
| `debug` | `false` | Logs requests and state. Off = no console output at all |
| `logger` | — | Receives lines instead of the console; gets warn/error even with debug off |
| `defaultAttributes` | — | Extra attributes on every identify. App values win |
| `storage` | `SharedPreferencesStorage()` | Queue, install id, session, base-URL override |
| `autoSession` | `true` | Sessions from the app lifecycle ([Sessions](https://developer.retainza.com/flutter/#sessions)) |
| `requireConsent` | `false` | Send nothing until analytics consent ([Consent](https://developer.retainza.com/flutter/#consent)) |
| `allowRuntimeBaseUrl` | value of `debug` | Lets `setBaseUrl` work. Keep off in release |
| `sessionTimeout` | 30 min | Background time before a new session |
| `maxQueuedEvents` | 100 | Offline queue capacity |
| `device` | detected | Override detected `DeviceInfo` fields |
| `httpClient` | — | Override the HTTP client (tests, proxies) |

A dev screen can repoint a debug build without rebuilding:

- `setBaseUrl(url)` — remembers an override; throws `StateError` unless `allowRuntimeBaseUrl` (or `debug`) is on, and the URL must start with `http://` or `https://`.
- `clearBaseUrl()` — forgets the override.
- `getBaseUrl()` — the URL requests actually go to (stored override > config > dart-define > default).
- `testConnection()` — hits `/health` (one level above `/v1`) and returns `(ok, status, error)`.

<!-- section: tracking -->

## 3. Identify & track

```dart
final r = Retainza.instance;

await r.identify(
  'user_42',
  attributes: {'plan': 'pro', 'trial_days_left': 3},
  profile: const RetainzaProfile(firstName: 'Asha', email: 'asha@example.com', locale: 'en-IN'),
);

await r.setAttributes({'plan': 'team'});          // patch — sends only this
await r.track('checkout_completed', properties: {'amount': 499, 'currency': 'INR'});
```

After `identify`, later calls use that user id; pass `userId:` to override, or configure `userProvider`. A call with no resolvable user throws `StateError`.

Attribute values are scalars: `String`, `num`, `bool` or `null`. `null` values in SDK/default layers are dropped rather than clearing server-side values.

`RetainzaProfile` fields become the reserved attributes `first_name`, `last_name`, `email`, `phone`, `gender`, `birthdate`; `email` and `locale` are also sent as top-level columns. Empty strings are ignored.

### Collections

One-to-many data such as challenges, badges or saved searches. The item id is the merge key, so an offline replay never duplicates an item:

```dart
await r.addToCollection('challenges', CollectionItem('lagos_10k', {'status': 'joined'}));
await r.removeFromCollection('challenges', 'lagos_10k');
await r.setCollection('badges', [CollectionItem('early_bird'), CollectionItem('streak_7')]); // [] clears
```

A `CollectionItem` id may not be empty (the constructor throws `ArgumentError`).

### Signed identity

Optional, and in the SDK's unreleased changes after `1.0.0`. With identity verification on for an environment, your server signs each user id (`hex(HMAC-SHA256(identitySecret, userId))`) and returns it with the session. Pass it on every launch:

```dart
await Retainza.instance.identify(user.id, userHash: userHash);
// or, without re-identifying:
Retainza.instance.setUserHash(userHash);
```

The hash is sent with every call for that user id and no other, is kept in memory only, and is cleared by `reset()`. Never put the identity secret in the app. See [Identity](https://developer.retainza.com/#identity).

### Logout

```dart
await Retainza.reset();
```

Unregisters this device's push token from the user being left, then clears the cached user id, the offline queue, session counters and in-app polling. The install id and `install_date` survive — they describe the device. If you use `userProvider`, make it return `null` after logout.

### Attributes the SDK sets for you

`platform`, `app_version`, `sdk_version`, `install_date`, `language`, `country`, `tz` (IANA, e.g. `Asia/Kolkata`), `device_model`, `device_manufacturer`, `os_name`, `os_version`, the session counters ([Sessions](https://developer.retainza.com/flutter/#sessions)) and `push_permission` once you report it. `country` is the locale region, not GPS — no permission prompt is involved.

<!-- section: push -->

## 4. Push

Retainza sends push through **Firebase Cloud Messaging** on both platforms, so register the **FCM token** — on iOS too, not the raw APNs device token.

**Step 1:** Set up Firebase

Set up Firebase for your app (`flutterfire configure`) and add `firebase_core` and `firebase_messaging`. On iOS, enable the Push Notifications capability and the *Remote notifications* background mode, and upload your APNs key in the Firebase console.

**Step 2:** Report permission and register the token

```dart
import 'package:firebase_messaging/firebase_messaging.dart';

Future<void> setUpPush() async {
  final r = Retainza.instance;
  final fm = FirebaseMessaging.instance;

  // The SDK never prompts — asking is your product decision.
  final settings = await fm.requestPermission();
  await r.setPushPermission(switch (settings.authorizationStatus) {
    AuthorizationStatus.authorized => PushPermission.authorized,
    AuthorizationStatus.provisional => PushPermission.provisional,
    AuthorizationStatus.denied => PushPermission.denied,
    AuthorizationStatus.notDetermined => PushPermission.undetermined,
  });

  final token = await fm.getToken();
  if (token != null) await r.registerPush(token, Retainza.pushPlatform);
  fm.onTokenRefresh.listen((t) => r.registerPush(t, Retainza.pushPlatform));
}
```

Call it after `identify`. `registerPush` is safe on every launch: an unchanged token is re-sent at most once a day (`force: true` overrides). It is never queued — a late token may already be stale — so it throws on network errors.

### Opens and deep links

Every Retainza push carries `engage_*` keys in its data block. `parseRetainzaPush` returns `null` for pushes that belong to another SDK:

```dart
void handleOpen(RemoteMessage m) {
  final push = parseRetainzaPush(m.data);
  if (push == null) return; // not ours
  Retainza.instance.ackPush(push.msgId, PushAction.opened).ignore();
  if (push.route != null) Retainza.instance.resolveRoute(push.route!);
}

FirebaseMessaging.onMessageOpenedApp.listen(handleOpen);
final initial = await FirebaseMessaging.instance.getInitialMessage();
if (initial != null) handleOpen(initial);
```

`resolveRoute` hands the route to the handler you register with `onNavigate` ([In-app messages](https://developer.retainza.com/flutter/#inapp)). Report `PushAction.delivered` from `FirebaseMessaging.onMessage` (foreground) if you want delivery counts — FCM has no delivery receipt of its own.

<!-- section: inapp -->

## 5. In-app messages

> **Note:** The built-in in-app UI has not shipped yet. The SDK delivers messages; your app renders them.

Poll for messages and hand each to your renderer:

```dart
final r = Retainza.instance;

r.onInApp((msg) {
  // msg.template: banner | modal | bottomsheet | fullscreen | html
  // msg.content: the full payload (title, body, buttons, media, style …)
  showMyDialog(title: msg.content['title'] as String?, body: msg.content['body'] as String?);
});

final stop = r.startInAppPolling(); // every 15 s; returns a stop function
```

`shown` is acked automatically when a message is delivered to `onInApp`. Report the rest yourself:

```dart
await r.ackInApp(msg.msgId, InAppAction.clicked);
await r.ackInApp(msg.msgId, InAppAction.dismissed);
```

`fetchPendingInApp()` does a single poll if you prefer to drive timing. The polling interval can be changed with `startInAppPolling(interval: …)`.

### Navigation

```dart
r.onNavigate((route) => navigatorKey.currentState?.pushNamed(route.screen, arguments: route.kv));
```

Push opens and in-app buttons both resolve through this handler. A route is a `screen` name plus a `kv` map of string params.

### Rendering it yourself (selfhandled)

Campaigns built with the *self-handled* template are never drawn by the SDK and never auto-acked. Your handler owns the acks — skipping them empties that campaign's funnel:

```dart
r.onSelfHandledInApp((h) {
  showMyCard(h.message.content, onVisible: h.markShown, onTap: () => h.markClicked(), onClose: h.markDismissed);
});
```

`markClicked([route])` acks `clicked` and then navigates (to the given route, else the message's own). A self-handled message that arrives with no handler registered stays queued and is logged as a warning.

<!-- section: offline -->

## 6. Offline queue

`identify`, `setAttributes`, `track` and the collection calls survive network failures. Network errors and 5xx responses are queued (100 items by default, oldest dropped first), persisted, and flushed in order with their original timestamps — backoff doubles from 1 s up to 5 min. A 4xx is thrown and never queued. Push registration and acks are never queued.

```dart
Retainza.instance.queueSize;          // pending calls
await Retainza.instance.flushQueue(); // drain now
```

<!-- section: consent -->

## 7. Consent

```dart
Retainza.init(publicKey: pk, requireConsent: true);
// … later, from your consent UI:
await Retainza.instance.setConsent(analytics: true, marketing: false);
```

With `requireConsent`, nothing leaves the device until `analytics: true`, and calls made before that are **dropped, not queued**. `marketing` never gates sending; it is stored as `consent_marketing` for targeting.

> **Warning:** `optOut()` stops everything and clears the queue until `optIn()` or the next launch. It is not persisted — re-apply it on each launch from your own stored preference.

<!-- section: sessions -->

## 8. Sessions

With `autoSession` on (default), the SDK starts a session at init and on each return to the foreground, and banks foreground time when the app goes to the background. Returning within 30 minutes (`sessionTimeout`) resumes the same session. A new session emits a `session_start` event and updates `session_count`, `first_session_at`, `last_session_at` and `session_duration_total`.

Turn it off (`autoSession: false`) and call `startSession()` / `endSession()` yourself if you need custom rules.

<!-- section: troubleshooting -->

## 9. Troubleshooting

| Symptom | Check |
| --- | --- |
| Nothing reaches the dashboard | `debug: true` and read the log; `testConnection()`; the key belongs to the environment you are looking at |
| `StateError: no userId` | Call `identify` first, pass `userId:`, or set `userProvider` |
| Events arrive late | Device was offline — they were queued; `queueSize` shows the backlog |
| Nothing sent at all with `requireConsent` | `setConsent(analytics: true)` has not been called |
| Push token registered, no pushes on iOS | You registered the APNs token instead of `FirebaseMessaging.instance.getToken()`, or no APNs key in Firebase |
| Self-handled campaign shows 0 impressions | Your handler never calls `markShown()` |
| First identify lacks device/timezone | `await Retainza.ready()` before it |

The SDK's example app exercises every call. With the SDK source checked out, run it from its `example/` directory:

```bash
flutter run --dart-define=RETAINZA_PK=pk_test_xxx
```

Other platforms: [React Native](https://developer.retainza.com/react-native/), [iOS](https://developer.retainza.com/ios/), [Android](https://developer.retainza.com/android/), [server](https://developer.retainza.com/server/). The HTTP API is in the [reference](https://developer.retainza.com/#api).

---

<!-- Source: https://developer.retainza.com/server/ · Markdown: https://developer.retainza.com/server.md -->

Built, not yet published · HTTP API · Node SDK not distributed yet

# Retainza from your backend

Write what only your server knows — plan, billing, entitlements — into the same profiles your app writes, with the secret key.

<!-- section: overview -->

## Who writes what

This guide is for a backend developer whose app already has Retainza in the mobile client, and whose server now needs to read and write the same data. That is possible, and always was: the ingest routes accept a secret key as well as a public one, by design.

```
   ┌─────────────────┐  pk_...  ┌──────────────┐  sk_...  ┌──────────────────┐
   │  MOBILE APP     │ ───────► │  RETAINZA    │ ◄─────── │  YOUR BACKEND    │
   │  identify/track │          │  API         │          │  identify/track  │
   │  device tokens  │          │              │          │  collections     │
   └─────────────────┘          └──────────────┘          │  read / delete   │
                                                          │  campaigns, send │
                                                          └──────────────────┘
```

The app and your backend are **co-equal write paths**. They write to the same profile, the same collections, the same event stream. Neither is a proxy for the other, and you do not have to choose — the usual split is:

| The app knows | Your backend knows |
| --- | --- |
| Screen views, taps, session counts | Plan tier, billing state, entitlements |
| Device model, OS, push token, timezone | Anything computed from your own database |
| What the user did just now | What happened in a webhook or a nightly job |

### The two keys

| Key | Where it may live | What it can do |
| --- | --- | --- |
| `pk_…` | Inside the app binary | `identify`, `track`, `collections`, `token` (register/unregister), in-app fetch/ack, push ack |
| `sk_…` | **Only on your server** | All of the above, plus campaigns, segments, audience, user read and delete |

> **Warning:** A secret key reaches billing and key rotation. Put it in an environment variable, never in a repository, never in an app, and never behind a route your frontend can call directly.

Each project has **Sandbox** and **Production**, with separate keys and completely separate data. The key decides which one you are writing to: `sk_test_…` writes Sandbox, `sk_live_…` writes Production. The only override is the raw `X-Engage-Environment` header (see [the REST API](https://developer.retainza.com/server/#api)), which the Node SDK never sends.

> **Note:** Your server also holds a third secret if you turn on identity verification: the environment's identity secret, which signs user ids for the client SDKs. `@retainza/sdk-node` exports `signUserId(identitySecret, userId)` for that — see [Signed identity](https://developer.retainza.com/#identity).

<!-- section: install -->

## 1. Install

> **Note:** `@retainza/sdk-node` is not on the public npm registry yet, and it is not part of the dashboard's SDK download (that bundle carries the React Native packages). Until it is published, every method on this page is a single HTTP call you can make yourself — the shapes are in [5. The REST API underneath](https://developer.retainza.com/server/#api).

Once the package is in your project, create one client and share it:

```ts title="retainza.ts"
import { createRetainzaServer } from "@retainza/sdk-node";

export const retainza = createRetainzaServer({
  secretKey: process.env.RETAINZA_SECRET_KEY!,  // sk_live_... or sk_test_...
  baseUrl: process.env.RETAINZA_API_URL,        // defaults to https://api.retainza.com/v1
});
```

| Option | Required | Notes |
| --- | --- | --- |
| `secretKey` | yes | Must start with `sk_`. The constructor throws on anything else — the mirror of the device SDKs refusing anything but `pk_`. |
| `baseUrl` | no | Defaults to `https://api.retainza.com/v1`. Must include the `/v1` prefix — every path the SDK calls is relative to it. |
| `fetch` | no | Inject your own implementation (tests, proxies, older Node). Defaults to the global `fetch`, so Node 18+. |

No SDK for your language? Every method below is one HTTP call with `Authorization: Bearer sk_…`:

**Node SDK**

```ts
await retainza.identify("user_123", { plan: "pro" });
```

**curl**

```bash
curl -X POST https://api.retainza.com/v1/identify \
  -H "Authorization: Bearer $RETAINZA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId":"user_123","attributes":{"plan":"pro"}}'
```

<!-- section: tracking -->

## 2. Write from your server

### Profile attributes

```ts
await retainza.identify("user_123", {
  plan: "pro",
  lifetime_value: 4820,
  trial_ends_at: 1767139200000,
}, { email: "ada@example.com" });
```

The third argument takes `email` and `locale`. Attributes **merge**: fields you omit keep their previous value, so a nightly sync that only computes `lifetime_value` cannot wipe what the app wrote.

> **Warning:** Keep names `lower_snake_case` and keep a value's **type** stable. Nothing pins an attribute to a type, and the segment engine compares strictly — a field sent as `"2"` by your backend and `2` by the app produces a segment that matches half your audience with no error anywhere.

### Events

```ts
await retainza.track("user_123", "subscription_renewed", { months: 12 });
```

This is the same endpoint the app calls, which means it also **fires event-triggered campaigns**. The response says how many triggered:

```ts
const { triggered } = await retainza.track("user_123", "challenge_completed", {
  challenge_id: "lagos_10k",
});
```

Replaying something historical? Pass the real timestamp (epoch milliseconds) as the fourth argument; it defaults to the server's clock:

```ts
await retainza.track("user_123", "order_placed", { total: 89.9 }, order.createdAt);
```

A backfill stamped “now” lands in the wrong reporting window, and can fire a campaign for something that happened last week.

### One-to-many data (challenges, badges, orders)

```ts
await retainza.collections.upsert("user_123", "challenges", {
  id: "lagos_10k",
  status: "done",
  progress: 100,
});
```

`id` is the merge key, so a retried call is safe. Fields you omit on an existing item are preserved, and a bare string is shorthand for `{ id }`. The caps are real and enforced:

| Limit | Value |
| --- | --- |
| Items per collection | 100 |
| Collections per profile | 20 |
| Fields per item | 25 |
| Size per item | 2 KB |
| Collections per profile, total size | 64 KB |
| Ops per request | 50 |

Item 101 is **rejected with a 400**, never silently truncated — see [When a collection is the wrong tool](https://developer.retainza.com/server/#collection-wrong-tool). The rest of the surface:

```ts
await retainza.collections.remove("user_123", "challenges", "lagos_10k"); // missing id is a no-op
await retainza.collections.set("user_123", "challenges", ["a", "b"]);     // replace; [] clears
await retainza.collections.apply("user_123", ops);                         // raw op list, one atomic write
```

Every call returns the profile's collections after the write. A request carries at most **50 ops**, and `set` spends one on the clear — so `set` takes at most 49 items per call; build a larger collection with `apply` over several calls.

### When a collection is the wrong tool

Collections are for **the things you segment on**, and the 100-item cap is a deliberate part of that. If a user can accumulate hundreds of anything — orders, sessions, completed lessons, a full challenge catalogue — do not put the list on the profile:

| Put this in | What goes there | Why |
| --- | --- | --- |
| **Events** (`track`) | Every occurrence: `challenge_completed`, `order_placed` | Unbounded, timestamped, queryable by count and recency |
| **Attributes** (`identify`) | The rollups: `challenges_done`, `orders_90d`, `last_order_total` | Cheap to filter, never hits a cap |
| **Collections** | The handful of *live* items a campaign has to look inside | Field-level filtering — “any challenge where status is done” |

A 400-challenge catalogue with 6 active ones is 6 items in a collection, plus events, plus two aggregate attributes. That shape has no cap problem and segments better than the full list ever would.

<!-- section: usage -->

## 3. Read profiles

```ts
const { profile, events } = await retainza.users.get("user_123");
profile.attributes.plan;         // what any source last wrote
profile.collections?.challenges; // the same items the dashboard shows
profile.pushTokens;              // the devices, newest registration last
```

| Need | Call |
| --- | --- |
| One person, with their last 50 events and deliveries | `users.get(userId)` — 404 if unknown |
| The GDPR subject-access payload | `users.export(userId)` |
| Erase someone, irreversibly (profile, events, deliveries and devices) | `users.delete(userId)` |
| A page of the audience | `audience({ limit, cursor })` — keyset; pass `nextCursor` back. `limit` defaults to 50, max 200 |
| How big a segment is | `segments.count(id)` |

`audience` returns everyone, newest first; its `total`, `reachable` and `byPlatform` describe the whole project, not the page, and `nextCursor` is absent on the last page.

> **Note:** There are no outbound webhooks today: your backend can push into Retainza and read from it, but it cannot yet be *notified* by it. Poll `users.get` or the analytics endpoints if you need to react to delivery state.

<!-- section: push -->

## 4. Devices from your server

Most apps register the push token from the device, and should — see the [React Native](https://developer.retainza.com/react-native/), [iOS](https://developer.retainza.com/ios/), [Android](https://developer.retainza.com/android/) and [Flutter](https://developer.retainza.com/flutter/) guides. Register from the server only when your backend is the thing that holds the token.

```ts
await retainza.devices.register("user_123", {
  token: fcmToken,
  platform: "android",
  installId: "inst_abc123",   // stable per install — see below
  appVersion: "4.2.1",
});
```

Also accepted: `deviceModel`, `osName`, `osVersion` and `tz`.

> **Tip:** **Always send `installId` if you have one.** It is what tells Retainza that a changed token is the same device rather than a new one. FCM and APNs rotate tokens on their own schedule; without an install id every rotation looks like another phone, the device list only grows, and a campaign fans out to tokens that have been dead for months. With one, a rotation replaces the entry in place and the dashboard shows the rotation count.

**On logout, unregister.** This one matters:

```ts
await retainza.devices.unregister("user_123", { installId: "inst_abc123" });
// or match by token: { token: fcmToken }
```

Without it the token stays on the profile the user just left, and the next person to sign in on that handset receives the previous user's campaigns. The server also takes a device off any other profile when it registers against a new user, so this is belt and braces — but that claim only runs when the next user registers, which may be days later.

<!-- section: api -->

## 5. The REST API underneath

Every method above is one call to `https://api.retainza.com/v1`. Authenticate with `Authorization: Bearer sk_…`. The full route reference is on the [API reference](https://developer.retainza.com/#api).

- POST · `/v1/identify` · Create or merge a profile identify
- POST · `/v1/track` · Record an event, fire matching triggers track
- POST · `/v1/collections` · Apply collection ops (up to 50 per request) collections.*
- POST · `/v1/token` · Register a device devices.register
- DELETE · `/v1/token?userId=&installId=` · Unregister a device (token= works instead of installId) devices.unregister
- GET · `/v1/users/:id` · One profile, with recent events and deliveries users.get
- GET · `/v1/users/:id/export` · GDPR export users.export
- DELETE · `/v1/users/:id` · Erase users.delete
- GET · `/v1/audience?limit=&cursor=` · A page of the audience (keyset) audience
- GET · `/v1/attributes` · Everything this project can be segmented on
- POST · `/v1/segments` · Create a segment from code segments.upsert
- GET · `/v1/segments/:id/count` · Audience size of a segment segments.count
- GET · `/v1/campaigns` · List campaigns campaigns.list
- POST · `/v1/campaigns` · Create a campaign from code campaigns.upsert
- POST · `/v1/campaigns/:id/activate` · Start a campaign campaigns.activate
- POST · `/v1/campaigns/:id/pause` · Stop a campaign campaigns.pause
- POST · `/v1/send` · Send now, by campaign id or inline send
- GET · `/v1/usage` · Current metered usage usage

### Optional headers (secret key only)

Both are ignored on a `pk_` key. The Node SDK sends neither.

- `X-Engage-Project: <projectId>` — act on another project in the same organization (`403 cross_org` otherwise).
- `X-Engage-Environment: test | live` — act on that environment of the project instead of the key's own. Any other value is a `400`; it is refused with `409` on an organization still on the legacy single-environment model.

### Errors

```json
{ "error": { "code": "...", "message": "..." } }
```

| Status | Codes | Meaning |
| --- | --- | --- |
| `401` | `no_key`, `malformed_key`, `unknown_key`, `revoked_key`, `key_revoked`, `insufficient_scope` | Auth failure. `insufficient_scope` is a `pk_` key on a secret-only route. |
| `400` | `bad_request` | Validation failure, including a collection cap |
| `429` | `rate_limited` | Over the rate limit |
| `429` | `quota_exceeded` | Over a plan quota; `error.meter` names the meter |

> **Note:** The Node SDK does not parse this body: any non-2xx throws an `Error` whose message is `Retainza <METHOD> <path>: <status> <body>`, and it never retries.

### Notes that save an afternoon

- **No batch endpoint yet.** A bulk sync is N calls; keep them sequential-ish and respect 429s. The rate limit is a token bucket of 50 requests/second sustained, bursting to 100, per project per key type — your `sk_` traffic shares a bucket with the dashboard, not with the app's `pk_` traffic. Over it you get `429 rate_limited`.
- **No idempotency key on `/v1/track`.** A retried job double-counts the event and can re-fire a trigger. Deduplicate on your side for now.
- **Quotas are per plan.** A quota 429 is `quota_exceeded` and carries the meter that was hit in `error.meter` (`mtu`, `apiCalls`, `pushSent`, `emailSent`). `apiCalls` counts only `identify`, `track`, `token`, `collections` and `send`; reads are free. Monthly tracked users (MTU) counts a user the first time they are written in a calendar month (UTC), from either the app or your backend, and is counted per environment. Sandbox traffic is recorded but not billed.

<!-- section: checklist -->

## Checklist before you ship

- `sk_` key in an environment variable, not in the repo — and never in an app
- Sandbox key in staging, Production key in production
- Attribute names `lower_snake_case`, types stable across app and backend
- Historical events pass their real `ts`
- Collections bounded, long lists modelled as events plus rollups
- `devices.unregister` on logout, if your backend owns the token
- Retries are safe: collection `id`s are merge keys, `identify` merges

---

<!-- Source: https://developer.retainza.com/ai/ · Markdown: https://developer.retainza.com/ai.md -->

# Use the docs with AI tools

Let your AI coding tool read these docs while it writes your Retainza integration.

<!-- section: overview -->

## Overview

An assistant that is integrating Retainza for you works best from the real docs, not from what it remembers. There are two ways to give it them:

- **The docs MCP server** — connect it once and the assistant can search the docs and read the section it needs, on its own, while it works.
- **Markdown** — every page is also published as plain Markdown, plus an `llms.txt` index, to paste into a chat or point a tool at.

Both serve exactly what this site shows, and update with it.

> **Note:** The MCP server is read-only and public. It needs no API key and never sees your project or your users — it only reads these docs.

<!-- section: install -->

## Connect your tool

The server speaks MCP over Streamable HTTP at `https://api.retainza.com/v1/mcp`. Add it to your tool under any name; the examples use `retainza-docs`.

**Claude Code**

```bash
claude mcp add --transport http retainza-docs https://api.retainza.com/v1/mcp
```

**Cursor**

```json
// .cursor/mcp.json (this project) or ~/.cursor/mcp.json (every project)
{
  "mcpServers": {
    "retainza-docs": {
      "url": "https://api.retainza.com/v1/mcp"
    }
  }
}
```

**VS Code**

```json
// .vscode/mcp.json
{
  "servers": {
    "retainza-docs": {
      "type": "http",
      "url": "https://api.retainza.com/v1/mcp"
    }
  }
}
```

Any other client that supports remote MCP servers over HTTP works the same way: give it the URL above, with no authentication.

### Check it works

Ask your assistant something only the docs know, for example:

```
Using the retainza-docs tools, how do I register a push token on Android?
```

It should call `search_docs`, then `get_docs_section`, and answer from the Android guide's push section.

<!-- section: usage -->

## What the tools do

| Tool | Does |
| --- | --- |
| `search_docs(query, limit?)` | Keyword search over every section. Naming a platform (ios, kotlin, flutter, expo, node…) favours that guide. Returns page and section ids. |
| `get_docs_section(page, section)` | One section as Markdown, code samples included. The usual next call after a search. |
| `get_docs_page(page)` | A whole page as Markdown. Pages run to 10–40 KB, so a section is usually enough. |
| `list_docs_pages()` | Every page with its sections' ids and titles. |

Page ids are `index` (the reference), `react-native`, `ios`, `android`, `flutter`, `server` and `ai`. Section ids are the anchors in each page's address — `/ios/#push` is page `ios`, section `push`.

### Limits

- Roughly two calls a second per IP address, with bursts of 60 — plenty for an assistant working through a task.
- Changes to these docs reach the server within about ten minutes.

<!-- section: concepts -->

## Markdown & llms.txt

Every page has a Markdown twin at the same address with `.md`:

| Page | Markdown |
| --- | --- |
| Reference | [https://developer.retainza.com/index.md](https://developer.retainza.com/index.md) |
| iOS guide | [https://developer.retainza.com/ios.md](https://developer.retainza.com/ios.md) |
| …and so on | `/react-native.md`, `/android.md`, `/flutter.md`, `/server.md`, `/ai.md` |

- [/llms.txt](https://developer.retainza.com/llms.txt) — an index of every page with a one-line description and its sections, in the [llms.txt](https://llmstxt.org) format.
- [/llms-full.txt](https://developer.retainza.com/llms-full.txt) — all pages in one file, for tools that take a single document.

On any page, **Copy page as Markdown** under the title puts that page on your clipboard, ready to paste into a chat.

> **Tip:** Pasting a whole page uses a lot of context. With the MCP server connected, the assistant fetches only the section it needs.