Rheo documentation
Developer Guide

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

ConceptWhat it means
Publishable keyob_pk_test_* or ob_pk_live_* — identifies your app and environment. Create keys in App settings → API keys.
ChannelPublic id (ch_test_… / ch_live_…). Pass it to useChannel or <Flow channelId={…} />. Rheo decides the content kind.
ResolvePOST /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.
ManifestJSON flow definition — screens, layers, decisions, external surfaces.
EventsAutomatic analytics (flow_started, step_viewed, …) batched to POST /v1/sdk/events. See Event catalog.
Terminal snapshotVersioned FlowTerminalSnapshot on completion or abandonment — JSON.stringify for your API, CRM, or LLM.

How resolve works

  1. The SDK sends your publishable key and channel id (plus identity: userId, locale, etc.).
  2. Rheo returns the assignment. A flow or banner pin / experiment includes the manifest. A code pin or code experiment includes variantKey and parameters. An experiment sets experiment to { id, variantKey, variantId }. A pin sets experiment to null. Banner holdout control may set control: true (render nothing; still log exposure). An unassigned channel is HTTP 404 channel_unassigned, and useChannel returns channel: null.
  3. Flow responses include flowId, versionId, and assignmentVersion. 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.
  4. mediaMap on a flow or banner response maps mediaAssetId to 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:

  1. Provider prefetch on RheoProvider mount ("all" or specific channel ids).
  2. Imperative prefetch from navigation listeners or button handlers.
  3. 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:

logLevelEmits
silent (default)Nothing
warnEvent transport failures, RevenueCat / Superwall integration warnings
debugAbove 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:

SDKCompletedAbandoned
React NativeonFlowCompleted on <Flow /> / useFlowonFlowAbandoned

FlowTerminalSnapshot (schemaVersion: 1) fields:

FieldContents
terminalcompleted | abandoned
occurredAtISO timestamp
correlationchannelId, flowId, versionId, assignmentVersion, environment, experimentId, variantId
subjectappUserId, optional customUserId, sessionId
deviceplatform, locale, optional appVersion, customProperties
answersNormalized field map (auth secrets omitted)
traitsMerged 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:

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,
);
APIPlatformEndpointUse
identifyWeb, React Native (Expo / bare)POST /v1/sdk/identifyEmail, marketing consent, topics, profile attributes, timezone
logEvent / screenAll GA SDKsPOST /v1/sdk/analytics/eventsProduct events. An Engage rule with source Analytics can use the name
Convert funnel eventsAll GA SDKsPOST /v1/sdk/eventsFlow events. An Engage rule with source Convert can use the name
registerPushWeb and React Nativepush routes under /v1/sdk/pushDevice 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.

SDKHow the token is read
Expoexpo-notifications device token (APNs on iOS, FCM on Android)
Bare React NativeYou supply the token with registerPushTokenAdapter, or pass { token, platform, provider }
WebService 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. useFlow and <Flow> fail when the kind is code or banner. Use RheoBanner for banners; use useChannel and channel.get(key, fallback) for code.
  • Use a stable userId for experiment bucketing.
  • After publish, cached manifests persist until assignmentVersion changes.

Resolve errors

SituationMeaning
Channel missingNo X-Rheo-Channel header
Channel not foundUnknown id or key/channel environment mismatch
Channel unassignedNothing is pinned and no experiment is serving (channel_unassigned)
Channel archivedUnarchive 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:

codeWhenEndpoints
sdk_plan_usage_exceededIndie 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_suspendedPaid subscription past-due after the 72-hour grace windowSame 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

RuntimeHost loopback
iOS Simulatorhttp://localhost:4000
Android Emulatorhttp://10.0.2.2:4000

Set apiBaseUrl / apiBaseURL in provider config during local dev.

HTTP surface (SDK)

Common authenticated SDK routes (Bearer publishable key):

PathPurpose
POST /v1/sdk/resolveChannel assignment + manifest or code parameters
POST /v1/sdk/resolve-allBatch prefetch
POST /v1/sdk/eventsFlow funnel event batches
POST /v1/sdk/code-eventsHost events for code channels
POST /v1/sdk/analytics/eventsProduct analytics batches. A matching Analytics trigger can enroll
POST /v1/sdk/identifyCustomer identify (Engage)
Push routes under /v1/sdk/pushDevice register / unregister

Event name and payload reference: Event catalog.