Configuration des deeplinks (e-mail → app)

Ce dont vous avez besoin

RedChurn ajoute flow, source=email et campaign à votre URL de base lors du rendu des CTA e-mail. Votre rôle : (1) déclarer une URL que l'OS peut router vers l'app, (2) coller cette URL de base dans Tableau de bord → Scénarios → E-mail → Branding, et (3) monter le handler deeplink SDK pour que l'app route vers le bon flux.

Préférez un lien universel HTTPS comme https://app.example.com/r : il ouvre l'app si installée et retombe sur une page web sinon. Un schéma custom comme myapp://redchurn fonctionne aussi mais est moins fiable depuis les clients e-mail.

• URL de base deeplink du tableau de bord, ex. https://app.example.com/r ou myapp://redchurn
• iOS Associated Domains + fichier apple-app-site-association sur votre domaine
• Filtres intent Android + assetlinks.json sur votre domaine (pour liens HTTPS)
• Handler SDK : useRedChurnDeeplinkHandler (RN/Expo) ou Redchurn.shared.handleDeeplink (Swift)

1. Tableau de bord : URL de base deeplink

Ouvrez Tableau de bord → Scénarios → E-mail et développez Branding. Définissez URL de base deeplink (optionnel) au préfixe que RedChurn doit utiliser pour les CTA e-mail, sans paramètres de requête.

RedChurn transformera un bouton de récupération des paiements en quelque chose comme https://app.example.com/r?flow=billing_recovery&source=email&campaign=<id>. Si le champ est vide, les e-mails continuent d'utiliser votre URL CTA web par défaut (App Store, portail de facturation, etc.).

2. iOS (Apple) : Universal Links

Les Universal Links permettent à https://yourdomain.com/... d'ouvrir votre app directement depuis Mail et Safari quand elle est installée.

• Choisissez un préfixe de chemin que vous contrôlez, ex. https://app.example.com/r. Cela devient votre URL de base deeplink du tableau de bord.
• Dans Apple Developer → Identifiers → votre App ID → activez Associated Domains.
• Dans Xcode → Signing & Capabilities → Associated Domains, ajoutez applinks:app.example.com (sans https://).
• Hébergez apple-app-site-association (sans extension) sur https://app.example.com/.well-known/apple-app-site-association servi en application/json avec le team ID et bundle ID de votre app.
• Incluez le chemin /r/* (ou votre préfixe choisi) dans le tableau paths AASA pour ne réclamer que les liens RedChurn.
• Reconstruisez et installez sur un appareil physique. Les Universal Links ne fonctionnent pas de façon fiable dans le Simulator.
• Swift : transmettez les URL au SDK avec .onOpenURL { url in Task { await Redchurn.shared.handleDeeplink(url) } }.

3. Android (Google Play) : App Links

Les App Links vérifient que https://yourdomain.com appartient à votre app pour qu'Android l'ouvre sans dialogue de désambiguïsation.

• Utilisez la même base HTTPS qu'iOS, ex. https://app.example.com/r.
• Dans AndroidManifest.xml, ajoutez un intent-filter avec android:autoVerify="true" sur votre activité principale pour https, host app.example.com, et pathPrefix /r.
• Hébergez assetlinks.json sur https://app.example.com/.well-known/assetlinks.json listant votre nom de package et l'empreinte SHA-256 du certificat de signature (cert Play App Signing pour les builds production).
• Lancez adb shell pm verify-app-links --re-verify your.package.name après l'installation d'une build release/signée.
• React Native / Expo : déclarez le même host et chemin dans app.json (voir ci-dessous) pour qu'EAS/prebuild génère les entrées manifest.
• Montez useRedChurnDeeplinkHandler (ou useRedChurnOpenHandler) près de la racine. Il écoute Linking et gère les URL au cold-start.

4. Expo (app.json)

Expo prebuild génère la config native Universal Link / App Link depuis app.json.

• Reconstruisez avec eas build ou npx expo prebuild. Expo Go ne peut pas tester les liens natifs custom.
• Définissez l'URL de base deeplink du tableau de bord sur https://app.example.com/r (HTTPS) ou myapp://redchurn (schéma custom).

{
  "expo": {
    "scheme": "myapp",
    "ios": {
      "bundleIdentifier": "com.example.app",
      "associatedDomains": ["applinks:app.example.com"]
    },
    "android": {
      "package": "com.example.app",
      "intentFilters": [
        {
          "action": "VIEW",
          "autoVerify": true,
          "data": [
            { "scheme": "https", "host": "app.example.com", "pathPrefix": "/r" }
          ],
          "category": ["BROWSABLE", "DEFAULT"]
        }
      ]
    }
  }
}

5. React Native (bare)

React Native bare utilise les mêmes étapes natives qu'au-dessus. Configurez Associated Domains dans Xcode et les intent filters dans AndroidManifest.xml manuellement, ou utilisez un config plugin.

• iOS : types URL Info.plist pour schémas custom si vous utilisez myapp:// ; plus Associated Domains pour HTTPS.
• Android : intent-filter avec autoVerify pour votre host/chemin HTTPS.
• npm : aucun package RedChurn supplémentaire. Utilisez useRedChurnDeeplinkHandler depuis @redchurn/react-native-sdk.

6. Handler SDK et attribution

Une fois que l'OS livre l'URL à votre app, le SDK parse flow / source / campaign et déclenche un événement LINK_OPENED pour l'attribution dans le tableau de bord.

• billing_recovery et win_back sont les flux définis automatiquement sur les CTA e-mail.
• Si rien ne se passe quand vous appuyez sur le bouton e-mail, le lien natif n'atteint pas l'app. Corrigez AASA / assetlinks d'abord, puis le handler SDK.

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

useRedChurnOpenHandler({
  onBillingRecovery: () => billing.check(),
  onWinBack: () => winBack.check(),
});