Rheo documentation
Developer Guide

Web SDK (React)

Embed Rheo flows in the browser with @getrheo/react. Resolve, prefetch, Engage identify, product analytics, Stripe Payment Links, and first-party attribution.

Purpose

Run the same Rheo flow construct in a host web app (quizzes, funnels, onboarding). There is no separate “web flow” type — authors use one canvas; pin warnings call out mobile-only or web-only steps.

Install

pnpm add @getrheo/react

Current coordinated version is 3.0.0 (same train as the React Native packages). Peer dependencies: react and react-dom ≥ 18.

How to

  1. Wrap your app with RheoProvider and mount Flow with a channel public id.
  2. In App settings → SDK, add the site origin (scheme, host, and port). The Next.js example at apps/example-web (pnpm dev:local:app:web) needs http://localhost:5173 added by you. Dashboard CORS is separate. A browser request from an origin this app did not list is rejected.
  3. For payments, turn Stripe on under App settings → Integrations, then add a Stripe Integration Node with a Payment Link on buy.stripe.com or another https://*.stripe.com host (see Stripe Payment Links). Paste the webhook URL and signing secret from that integration into Stripe. No Stripe adapter on RheoProvider. A return restores the session. The webhook writes the originating charge. The browser does not send a price.
  4. Optionally customize attribution (first-touch UTM capture is on by default and is not recaptured from the return URL).
import { RheoProvider, Flow } from '@getrheo/react';

export const App = () => (
  <RheoProvider
    config={{
      publishableKey: import.meta.env.VITE_RHEO_PUBLISHABLE_KEY,
      apiBaseUrl: import.meta.env.VITE_RHEO_API_BASE_URL,
    }}
    prefetch="all"
  >
    <Flow channelId="ch_…" />
  </RheoProvider>
);

prefetch: "all" | string[] | omit. Warms the resolve cache on mount. See Manifest prefetch.

Code channels

useChannel resolves the same channel id. Use it when the channel may serve code parameters. Flow still requires kind: "flow".

import { RheoProvider, useChannel, logChannelEvent } from '@getrheo/react';

const PaywallFlag = () => {
  const { loading, channel } = useChannel({ channelId: 'ch_…' });
  if (loading || !channel || channel.kind !== 'code') return null;
  const enabled = channel.get('showAnnual', false);
  return (
    <button type="button" onClick={() => logChannelEvent('ch_…', 'annual_tapped')}>
      {enabled ? 'Annual' : 'Monthly'}
    </button>
  );
};

channel.get returns the fallback when the key is missing or the JSON type does not match. A code experiment logs experiment_exposed from useChannel. A code pin does not.

Soft-degrades on web

FeatureWeb behavior
RevenueCat / Superwall / headlessSurface fails → Fallback edge
request_os_permission other than notificationsTreated as denied
notificationsBrowser permission prompt. A grant calls registerPush()
request_app_reviewNo-op (not_shown)
AppsFlyerNot supported — use first-party UTMs / host providers

Attribution

With attribution.enabled not set to false, the SDK writes canonical keys (acquisition.*, link.ext.*, attribution.isOrganic) from the page query string and document.referrer. Pass attribution.providers for host collectors.

When product analytics consent is pending or denied, those values stay in memory. setAnalyticsConsent('granted') writes them. See Consent.

Product analytics waits until consent is granted. An omitted analytics.consent is pending. In the EU and UK, call setAnalyticsConsent from your consent banner before the SDK stores an id or sends product events. Rheo does not ship a banner. Pass analytics.consent: 'granted' when the visitor has already accepted.

import { Flow, RheoProvider, setAnalyticsConsent } from '@getrheo/react';

export const App = () => (
  <RheoProvider
    config={{
      publishableKey: import.meta.env.VITE_RHEO_PUBLISHABLE_KEY,
      analytics: { consent: 'pending' },
    }}
  >
    <Flow channelId="ch_…" />
  </RheoProvider>
);

const onAccept = () => setAnalyticsConsent('granted');
const onReject = () => setAnalyticsConsent('denied');

granted starts sessions, page views, and custom events. denied stops collection and clears the analytics id, session, and first-touch attribution. If the banner already stored a grant before paint, pass consent: 'granted' instead of pending. analytics.enabled: false still turns collection off.

Details, including the storage keys, are in Product analytics.

Manifest prefetch

Resolve responses carry an ETag. Flow manifests cache per channel + locale in memory and localStorage. A later resolve sends If-None-Match and can receive 304.

Warm the cache before showing a flow:

<RheoProvider config={config} prefetch="all">
  <Flow channelId="ch_…" />
</RheoProvider>

<RheoProvider config={config} prefetch={['ch_test_paywall', 'ch_test_onboarding']}>
  …
</RheoProvider>
import { prefetch, prefetchAll, useRheoPrefetch } from '@getrheo/react';

await prefetch('ch_test_onboarding');
await prefetchAll();

const { prefetch: warm, prefetchAll: warmAll } = useRheoPrefetch();

Prefetch never records flow_started. A mounted <Flow /> still owns error/retry UI if prefetch failed silently. Full overview: SDK overview — Prefetch.

Engage identify

After the person opts into marketing messages, call identify with email and consent. Automations and segments use Analytics events (logEvent, page views) on POST /v1/sdk/analytics/events, Convert funnel events on POST /v1/sdk/events, and email open and click.

import { identify } from '@getrheo/react';

await identify(
  { email: 'user@example.com', marketingConsent: 'granted' },
  rheoConfig,
);

Full reference: SDK overview — Engage identify.

Engage push

registerPush() and unregisterPush() subscribe the browser for Engage push. Generate a VAPID keypair under App settings → Engage settings → Push settings first. The SDK reads the public key from Rheo. The private key stays in Rheo.

A flow button with permissionKey: "notifications" asks for browser notification permission and, on grant, calls registerPush(). Other request_os_permission keys stay denied on web.

registerPush() uses RheoConfig.push.serviceWorkerUrl when you set one, and otherwise waits for navigator.serviceWorker.ready. The service worker must already be able to receive a push. You can also pass a subscription you already created.

import { registerPush } from '@getrheo/react';

await registerPush();
<RheoProvider
  config={{
    publishableKey: import.meta.env.VITE_RHEO_PUBLISHABLE_KEY,
    push: { serviceWorkerUrl: '/rheo-push-sw.js' },
  }}
>
  <Flow channelId="ch_…" />
</RheoProvider>