SDK React Native

Vue d'ensemble

Le SDK React Native connecte votre app à RedChurn via une seule clé API. Il enregistre votre App User ID RevenueCat, synchronise la configuration distante et affiche une UI native pour trois scénarios de rétention.

Tout ce que voit l'abonné (titres, messages, boutons, offres) se modifie dans le tableau de bord. Le SDK interroge les changements et se met à jour automatiquement. Vous ne publiez pas une nouvelle build pour modifier les textes.

• Cancel Save : intercepte les appuis sur annuler avec une feuille native
• Billing Recovery : relance in-app quand RevenueCat signale un problème de facturation
• Win back : invite de réactivation pour les abonnés churnés
• Config distante : flux, textes et offres pilotés depuis le tableau de bord

Prérequis

• React 18 ou ultérieur
• React Native 0.72 ou ultérieur (dev build Expo / prebuild pris en charge)
• RevenueCat configuré dans votre app avec des App User IDs
• @notifee/react-native (peer) pour les notifications locales de récupération des paiements et win back

1. Installation

Ajoutez le SDK et la dépendance peer Notifee. Notifee alimente les notifications locales utilisées par la récupération des paiements et le win back.

# Expo
npx expo install @redchurn/react-native-sdk @notifee/react-native

# bare React Native
npm install @redchurn/react-native-sdk @notifee/react-native

2. Enveloppez votre app avec le provider

Enveloppez votre racine une fois avec RedchurnProvider. Récupérez votre clé SDK dans le tableau de bord RedChurn (Paramètres, ou pendant l'onboarding). Passez l'App User ID RevenueCat pour que RedChurn puisse associer les abonnés aux événements webhook. Gardez notificationsEnabled pour planifier des rappels locaux à partir des textes du tableau de bord.

import { RedchurnProvider } from "@redchurn/react-native-sdk";

export default function App() {
  return (
    <RedchurnProvider config={{
      sdkKey: "rdchrn_live_xxxxxxxx",
      rcAppUserId: user.revenueCatAppUserId,
      notificationsEnabled: true,
      // locale: "fr",            // optional — auto-detected from device
      // debug: __DEV__,          // optional — logs [RedChurn SDK] lines
    }}>
      <RootNavigator />
    </RedchurnProvider>
  );
}

3. Enregistrez le gestionnaire d'arrière-plan

Appelez registerRedchurnBackgroundEventHandler une fois dans index.js, en dehors de React, pour que les appuis sur notification ouvrent le bon flux quand l'app est en arrière-plan. Sur Android 13+, demandez la permission de notification une fois après la connexion.

// index.js — before "expo-router/entry" (or your app entry)
import { registerRedchurnBackgroundEventHandler } from "@redchurn/react-native-sdk";

registerRedchurnBackgroundEventHandler();

import "expo-router/entry";

4. Définissez l'App User ID après la connexion

Si l'App User ID RevenueCat n'est pas disponible au lancement de l'app, définissez-le après l'authentification pour cibler le bon abonné :

import { useEffect } from "react";
import { useRedChurn } from "@redchurn/react-native-sdk";

function AuthBridge({ userId }: { userId: string }) {
  const { setRCAppUserId } = useRedChurn();

  useEffect(() => {
    setRCAppUserId(userId);
  }, [userId, setRCAppUserId]);

  return null;
}

5. Cancel Save

Enveloppez votre bouton d'annulation avec CancelSaveFlow. interceptCancel() affiche la feuille de sauvegarde (sondage puis vos offres configurées) et renvoie false quand rien ne doit s'afficher, pour retomber sur l'UI d'annulation du store. Appliquez l'offre acceptée dans onOfferAccepted via RevenueCat — lancez une exception en cas d'échec pour que RedChurn ne compte une sauvegarde qu'après une opération store/RC réussie.

import { CancelSaveFlow } from "@redchurn/react-native-sdk";

function SubscriptionSettings({ rcAppUserId }: { rcAppUserId: string }) {
  return (
    <CancelSaveFlow
      rcAppUserId={rcAppUserId}
      onOfferAccepted={async (offer) => {
        // Apply via RevenueCat. Throw on failure — save is recorded only on success.
      }}
      render={({ interceptCancel }) => (
        <Button
          title="Cancel subscription"
          onPress={async () => {
            const intercepted = await interceptCancel();
            if (!intercepted) openAppStoreSubscriptions();
          }}
        />
      )}
    />
  );
}

6. Billing Recovery

Quand RevenueCat signale un problème de facturation, RedChurn affiche une bannière de relance in-app et (avec Notifee) planifie des rappels locaux. Montez BillingRecoveryFlow comme enfant d'un conteneur plein écran et choisissez où il s'épingle.

import { BillingRecoveryFlow } from "@redchurn/react-native-sdk";
import { useSafeAreaInsets } from "react-native-safe-area-context";

function HomeScreen({ rcAppUserId }: { rcAppUserId: string }) {
  const insets = useSafeAreaInsets();
  return (
    <View style={{ flex: 1 }}>
      <YourHomeContent />
      <BillingRecoveryFlow
        rcAppUserId={rcAppUserId}
        placement="top"          // "top" | "bottom" | "inline"
        edgeInset={insets.top}
        onNotificationOpen={() => navigation.navigate("Home")}
      />
    </View>
  );
}

7. Win back

Pour les abonnés churnés (EXPIRATION RevenueCat), WinBackFlow affiche votre invite de réactivation à la prochaine ouverture et gère l'appui sur notification. Dirigez le CTA vers votre paywall.

import { WinBackFlow } from "@redchurn/react-native-sdk";

function HomeScreen({ rcAppUserId }: { rcAppUserId: string }) {
  return (
    <WinBackFlow
      rcAppUserId={rcAppUserId}
      onCtaPress={() => navigation.navigate("Paywall")}
      onNotificationOpen={() => navigation.navigate("Home")}
    />
  );
}

8. Push serveur (optionnel)

Les notifications locales ne partent que si l'app a tourné au moins une fois. Pour joindre les abonnés qui ne rouvrent jamais l'app, RedChurn envoie aussi du push serveur via FCM / APNs, déclenché par le webhook RevenueCat.

Le token s'enregistre automatiquement — aucune étape manuelle dans votre code. Sur iOS, le SDK utilise le token APNs natif ; installez @react-native-firebase/messaging si vous préférez FCM. Ajoutez vos identifiants FCM / APNs une fois dans Tableau de bord → Intégrations → Notifications push.

• Identifiants par app (BYOK) : JSON de compte de service FCM et/ou clé APNs .p8
• Sandbox vs Production : les builds Debug depuis Xcode utilisent le sandbox ; EAS internal/ad-hoc, TestFlight et App Store utilisent la production
• Testez de bout en bout depuis Tableau de bord → Événements → Tester les notifications push (dernier appareil ciblé automatiquement)

Deeplinks (e-mail → app)

Ouvrez le bon flux quand un abonné appuie sur un lien — par exemple le bouton de paiement dans un e-mail de récupération des paiements — et suivez l'ouverture pour l'attribution. Votre app possède son schéma d'URL / liens universels ; le SDK interprète l'URL. Un deeplink RedChurn transporte un flux (plus step, campagne et source optionnels).

Montez useRedChurnDeeplinkHandler une fois près de la racine. Il gère les liens au cold-start et en direct, ignore les URL non-RedChurn, et déclenche un événement LINK_OPENED avec le flux, la source et la campagne pour une attribution dans le tableau de bord.

Les appuis sur notification et les deeplinks mènent aux mêmes flux : useRedChurnOpenHandler({ onBillingRecovery, onWinBack }) relie les deux avec un seul jeu de callbacks — n'utilisez les deux hooks directement que si vous devez les traiter différemment.

import { useRedChurnDeeplinkHandler } from "@redchurn/react-native-sdk";

useRedChurnDeeplinkHandler({
  onBillingRecovery: () => billing.check(),
  onWinBack: () => winBack.check(),
});
// e.g. myapp://redchurn?flow=billing_recovery&campaign=oct&source=email

Configuration distante

Une fois le SDK installé, tout le contenu visible par l'abonné se gère dans le tableau de bord. Activez ou désactivez les flux, modifiez les textes, changez les offres et mettez à jour le style. Les changements se propagent en moins de 60 secondes.

Le SDK interroge un endpoint /version léger chaque minute et ne retélécharge la configuration que lorsque quelque chose a changé. Vous pouvez aussi déclencher un rafraîchissement quand l'app revient au premier plan.

• Flux et textes in-app : Tableau de bord → Scénarios → In-app
• Offres d'annulation : Tableau de bord → Cancel saves
• Séquences e-mail : Tableau de bord → Scénarios → E-mail
• Branding et CTA de secours : Tableau de bord → Paramètres

Comment le SDK communique avec RedChurn

Chaque appel SDK va vers l'API RedChurn sur https://app.redchurn.io, authentifié avec votre clé SDK en Bearer token. Vous n'appelez jamais ces endpoints directement — le provider et les composants de flux le font pour vous — mais connaître le contrat aide au débogage.

Au démarrage, le SDK enregistre l'appareil (heartbeat) et récupère la config distante. Il interroge ensuite un petit endpoint /version et ne retélécharge /config que lorsque le numéro de version change. Les événements et résultats sont postés au fil des interactions de l'abonné avec les flux ; seul /outcomes est réessayé (jusqu'à deux fois) car c'est l'appel qui crédite le MRR sauvegardé.

• Timeout de 12 secondes par requête, sans blocage de l'UI
• Réessais : uniquement POST /outcomes (back-off linéaire, max 2 réessais)
• rcAppUserId est la clé de jointure avec vos événements webhook RevenueCat
• Besoin d'un client brut ? import { createRedchurnClient } et appelez-le vous-même

Authorization: Bearer rdchrn_live_xxxxxxxx
Content-Type: application/json
Accept: application/json
X-RedChurn-Sdk-Version: 0.4.0
Accept-Language: fr            # when a locale is set

POST /api/sdk/v1/register     heartbeat + push token registration
GET  /api/sdk/v1/config       full remote config (flows, copy, offers)
GET  /api/sdk/v1/version      lightweight change check (polled)
GET  /api/sdk/v1/prompts      contextual billing-recovery / win-back prompts
POST /api/sdk/v1/events       APP_OPEN, CANCEL_SESSION, PROMPT_SHOWN/DISMISSED, LINK_OPENED
POST /api/sdk/v1/outcomes     saved / declined / dismissed (retried)

Comportement fail-safe

Le SDK ne lance jamais d'erreurs vers votre app. Si RedChurn est injoignable, les hooks deviennent no-op et votre app s'affiche normalement. Si le suivi d'annulation échoue, l'abonné peut toujours finaliser l'annulation.

Utilisez le callback onError pour journaliser les problèmes non fatals vers Sentry ou votre outil de monitoring.

• Timeout de requête de 12 secondes, pas de gel de l'UI
• Fail-open à l'annulation : l'utilisateur accède toujours au store s'il insiste
• Clé SDK invalide : les enfants s'affichent, les hooks sont no-op
• Unmount-safe : pas de mise à jour d'état après démontage du composant

<RedchurnProvider config={{
  sdkKey: "rdchrn_live_...",
  debug: __DEV__,
  onError: (error) => {
    Sentry.captureMessage(`[RedChurn] ${error.code}: ${error.message}`);
  },
}}>

Checklist production

• Webhook RevenueCat connecté et livrant des événements
• Clé SDK de l'environnement de production (rdchrn_live_...)
• App User ID défini pour chaque abonné authentifié
• registerRedchurnBackgroundEventHandler() appelé dans index.js
• Bouton d'annulation câblé via CancelSaveFlow / interceptCancel, pas un lien direct vers le store
• BillingRecoveryFlow et WinBackFlow montés dans votre layout home/racine
• Identifiants push ajoutés dans Tableau de bord → Intégrations (si push serveur)
• Textes et offres in-app relus dans le tableau de bord avant le lancement

Installation depuis npm ou téléchargement

Le chemin recommandé est npm (ou npx expo install pour Expo). Vous pouvez aussi télécharger l'archive tarball du SDK via le bouton en haut de cette page si vous avez besoin d'une copie hors ligne ou d'un miroir de registre privé.

# Public npm (once published)
npm install @redchurn/react-native-sdk @notifee/react-native

# Or from a downloaded tarball
npm install ./redchurn-react-native-sdk-0.4.0.tgz