Overview
Shared runtime model for Rheo mobile SDKs — channel resolve, events, terminal snapshots, and platform guides.
Purpose
Rheo ships two first-party React Native SDKs (Expo and bare) and a React web SDK. Each resolves a channel. A flow channel runs the same flow state machine from @getrheo/flow-runtime, renders dashboard-authored screens, batches analytics, and emits terminal snapshots when a run completes or is abandoned. A banner channel returns a single-frame manifest for RheoBanner. A code channel returns a variant key and parameters. SwiftUI and Flutter SDKs are coming soon (not customer-installable today).
Install exactly one React Native flavor — never both @getrheo/react-native-expo and @getrheo/react-native-bare. The web SDK is a separate package for browser funnels.
Mental model
| Concept | What it means |
|---|---|
| Publishable key | ob_pk_test_* or ob_pk_live_* — identifies your app and environment. Create keys in App settings → API keys. |
| Channel | Public id (ch_test_… / ch_live_…). Pass it to useChannel or <Flow channelId={…} />. Rheo decides the content kind. |
| Resolve | POST /v1/sdk/resolve with Authorization: Bearer <key> and X-Rheo-Channel: <channelId>. kind: "flow" includes the flow manifest. kind: "banner" includes the banner manifest. kind: "code" includes variantKey and parameters. experiment is null on a pin. |
| Manifest | JSON flow definition — screens, layers, decisions, external surfaces. |
| Events | Automatic analytics (flow_started, step_viewed, …) batched to POST /v1/sdk/events. See Event catalog. |
| Terminal snapshot | Versioned FlowTerminalSnapshot on completion or abandonment — JSON.stringify for your API, CRM, or LLM. |
How resolve works
- The SDK sends your publishable key and channel id (plus identity:
userId,locale, etc.). - Rheo returns the assignment. A flow or banner pin / experiment includes the manifest. A code pin or code experiment includes
variantKeyandparameters. An experiment setsexperimentto{ id, variantKey, variantId }. A pin setsexperimentto null. Banner holdout control may setcontrol: true(render nothing; still log exposure). An unassigned channel is HTTP 404channel_unassigned, anduseChannelreturnschannel: null. - Flow responses include
flowId,versionId, andassignmentVersion. Those ids are attached to flow analytics events. Banner responses include banner ids similarly. Code events are a separate upload and do not carry flow ids. mediaMapon a flow or banner response mapsmediaAssetIdto a CDN URL for image and Lottie layers.
Caching
Resolve responses carry an ETag. Flow responses cache the manifest per channel + locale (localStorage on web, AsyncStorage on React Native). Code responses use a separate in-memory cache and are never written into the manifest cache. If-None-Match can return 304 until the assignment or the served parameters change.
Prefetch
Warm the cache before showing a flow to skip the loading spinner. Web and React Native support:
- Provider prefetch on
RheoProvidermount ("all"or specific channel ids). - Imperative prefetch from navigation listeners or button handlers.
- On-demand resolve when a flow mounts — owns error and retry UI.
Prefetch is best-effort and silent. It never emits flow_started or experiment_exposed.
Platform-specific APIs: Web, Expo, bare React Native.
Code channels
useChannel is the shared primitive on web, Expo, and bare React Native. It returns { loading, error, channel }. channel is null when the channel is unassigned.
On kind: "code", call channel.get(key, fallback). A missing key, or a value whose JSON type differs from the fallback, returns the fallback. false and null are real values.
useChannel logs experiment_exposed once per app user, experiment, and variant while a code experiment is serving, until that channel's assignmentVersion changes. A code pin does not log it. Later host events go through logChannelEvent(channelId, name, properties). When a code experiment is active for that channel, the SDK stamps experimentId and variantId. Those events post to POST /v1/sdk/code-events, not the flow event batch.
<Flow> and useFlow accept only kind: "flow". Use RheoBanner for kind: "banner".
Banners
Mount RheoBanner with a channelId when the channel pins a published banner or serves a banner experiment. The component resolves the channel, renders the single root screen, and returns null while loading, when dismissed, or when the variant is a holdout control.
import { RheoBanner } from '@getrheo/react-native-expo';
// or: import { RheoBanner } from '@getrheo/react';
<RheoBanner channelId="ch_test_…" theme="light" />See Banners (User Guide). SwiftUI and Flutter banner install paths are coming soon.
Diagnostics and logging
All mobile SDKs default to silent console output in production. Opt in with the top-level logLevel prop on RheoProvider:
logLevel | Emits |
|---|---|
silent (default) | Nothing |
warn | Event transport failures, RevenueCat / Superwall integration warnings |
debug | Above plus dev-only diagnostics (manifest dump, prefetch misuse hints) — requires a dev build |
React Native: logLevel="warn" on <RheoProvider />. Kotlin will use the same levels from @getrheo/contracts.
Production apps should omit logLevel unless you are actively debugging transport issues.
Events and batching
Events queue in memory and POST to /v1/sdk/events every ~5 seconds, when the buffer hits 500 events, or immediately on flow_completed / flow_abandoned. Multi-channel batches split into separate POSTs (one X-Rheo-Channel per batch).
The queue is in-memory only — force-quit or offline periods can drop non-terminal events. Terminal events prioritize immediate flush.
Full event reference: Event catalog.
Product analytics (sessions, page and screen views, custom logEvent) is a separate batch to POST /v1/sdk/analytics/events. App SDKs start it when RheoProvider mounts, even if no flow is showing. On the web SDK, an omitted analytics.consent is pending, and setAnalyticsConsent('granted' | 'denied') from @getrheo/react starts or stops that collection. See Product analytics and Web SDK. Workspace members can read those views with rheo analytics product (CLI).
Terminal snapshot
Callbacks:
| SDK | Completed | Abandoned |
|---|---|---|
| React Native | onFlowCompleted on <Flow /> / useFlow | onFlowAbandoned |
FlowTerminalSnapshot (schemaVersion: 1) fields:
| Field | Contents |
|---|---|
terminal | completed | abandoned |
occurredAt | ISO timestamp |
correlation | channelId, flowId, versionId, assignmentVersion, environment, experimentId, variantId |
subject | appUserId, optional customUserId, sessionId |
device | platform, locale, optional appVersion, customProperties |
answers | Normalized field map (auth secrets omitted) |
traits | Merged sdkAttributes + attribution at terminal time |
Optional flags: includeManifestInTerminalPayload, includePathInTerminalPayload, includeAnswerDetailInTerminalPayload.
Call abandon() (RN useFlow) to transition to abandoned explicitly. Unmounting mid-flow also enqueues flow_abandoned when not already terminal.
Layer kinds
All SDKs render these manifest layer kinds:
stack, text, image, lottie, video, icon, button, back_button, progress, loader, counter, single_choice, multiple_choice, text_input, scale_input, wheel_picker, date_time_input, number_stepper, number_stepper_button, number_stepper_value, phone_input, address_input, oauth_provider, oauth_login, email_password_auth, email_password_field, email_password_submit, carousel, hyperlink, checkbox, conditional
Structural children (oauth_provider, email_password_*, number_stepper_button / number_stepper_value) are authored under their parent compound; they are not standalone palette items. Auth layers require host handlers — Authentication layers.
The advance_carousel button action (page a carousel from a Next button) runs on Expo / bare React Native.
Integration and External Surface Nodes are graph nodes, not layers:
- Stripe Payment Links — Integration Node on the web SDK. A verified Stripe webhook writes the purchase.
- RevenueCat paywall — Integration Node with modal paywall via host RevenueCat UI
- Superwall paywall — Integration Node that registers a Superwall placement via the host SDK
- Headless external surfaces — External Surface Node with host component registry via
externalSurfaces
Engage identify
Rheo Engage needs a Customer with marketing consent (and usually an email). Call identify after the person opts in — do not stuff email into event traits for consent.
import { identify } from '@getrheo/react';
// same export from @getrheo/react-native-expo and @getrheo/react-native-bare
await identify(
{
email: 'user@example.com',
marketingConsent: 'granted',
// topicConsents?: Record<string, 'granted' | 'denied' | 'unknown'>
timezone: 'America/New_York', // optional. Engage local send / quiet hours
},
rheoConfig,
);| API | Platform | Endpoint | Use |
|---|---|---|---|
identify | Web, React Native (Expo / bare) | POST /v1/sdk/identify | Email, marketing consent, topics, profile attributes, timezone |
logEvent / screen | All GA SDKs | POST /v1/sdk/analytics/events | Product events. An Engage rule with source Analytics can use the name |
| Convert funnel events | All GA SDKs | POST /v1/sdk/events | Flow events. An Engage rule with source Convert can use the name |
registerPush | Web and React Native | push routes under /v1/sdk/push | Device registration for Engage push |
Call identify after marketing opt-in on the same client that owns the appUserId. See Set up Engage and Web SDK. Email open and click are recorded by Rheo. They can be triggers. A custom event that should start a journey is logEvent on POST /v1/sdk/analytics/events.
Engage push
Push in Rheo Engage addresses devices you register with registerPush(). Save APNs, FCM, or Web Push credentials under App settings → Engage settings before a push broadcast can launch. The SDK upload uses the current appUserId and the publishable key's environment, so a test key registers a test-environment device.
A flow button with request_os_permission and permissionKey: "notifications" registers on grant and calls unregisterPush() when the person denies or blocks notifications. You can also call registerPush() yourself after your own permission prompt.
| SDK | How the token is read |
|---|---|
| Expo | expo-notifications device token (APNs on iOS, FCM on Android) |
| Bare React Native | You supply the token with registerPushTokenAdapter, or pass { token, platform, provider } |
| Web | Service worker subscription with the app VAPID public key |
unregisterPush() revokes the token this runtime last uploaded. Changing userId re-posts a cached token to the new id.
Production defaults
Default API host: https://api.getrheo.io (RHEO_DEFAULT_SDK_API_BASE_URL in @getrheo/contracts). Omit apiBaseUrl / apiBaseURL in production unless you self-host.
Match key environment to channel environment — ob_pk_test_* with ch_test_*, ob_pk_live_* with ch_live_*.
Troubleshooting
Blank or stale flow
- Validate publishable key, channel public id, and environment alignment.
- Confirm the channel is serving a flow pin or a flow experiment.
useFlowand<Flow>fail when the kind iscodeorbanner. UseRheoBannerfor banners; useuseChannelandchannel.get(key, fallback)for code. - Use a stable
userIdfor experiment bucketing. - After publish, cached manifests persist until
assignmentVersionchanges.
Resolve errors
| Situation | Meaning |
|---|---|
| Channel missing | No X-Rheo-Channel header |
| Channel not found | Unknown id or key/channel environment mismatch |
| Channel unassigned | Nothing is pinned and no experiment is serving (channel_unassigned) |
| Channel archived | Unarchive in dashboard or switch channel |
Use fallback on <Flow /> for host-owned recovery UI.
Rate limits and CORS
SDK routes are rate-limited per publishable key (resolve and events families). Retry with backoff on HTTP 429. Browser calls from @getrheo/react require the page origin under App settings → SDK; an origin that app did not list is rejected (CORS).
Indie MAU cap / billing suspension
When SDK traffic is paused, affected endpoints respond with HTTP 403 and a machine-readable code:
code | When | Endpoints |
|---|---|---|
sdk_plan_usage_exceeded | Indie live MAU is greater than the included 2,000 for the UTC month (exactly 2,000 still serves) | resolve, resolve-all, events, code-events, analytics/events, identify, push routes, billing-identity |
sdk_billing_suspended | Paid subscription past-due after the 72-hour grace window | Same set |
Indie traffic resumes on the next UTC month if you are under the cap, or immediately after upgrading. Paid workspaces resume when invoices are current. See Billing & subscriptions.
Local development API URL
| Runtime | Host loopback |
|---|---|
| iOS Simulator | http://localhost:4000 |
| Android Emulator | http://10.0.2.2:4000 |
Set apiBaseUrl / apiBaseURL in provider config during local dev.
HTTP surface (SDK)
Common authenticated SDK routes (Bearer publishable key):
| Path | Purpose |
|---|---|
POST /v1/sdk/resolve | Channel assignment + manifest or code parameters |
POST /v1/sdk/resolve-all | Batch prefetch |
POST /v1/sdk/events | Flow funnel event batches |
POST /v1/sdk/code-events | Host events for code channels |
POST /v1/sdk/analytics/events | Product analytics batches. A matching Analytics trigger can enroll |
POST /v1/sdk/identify | Customer identify (Engage) |
Push routes under /v1/sdk/push | Device register / unregister |
Event name and payload reference: Event catalog.