Systeme de parrainage React Native : guide complet en 1 jour

J'ai passé 8 heures à coder quelque chose qui n'a rien à voir avec le produit lui-même. Pas de nouvelle feature. Pas de bug fix. Pas d'optimisation. Un système de parrainage complet — deep links Android, Play Store Install Referrer, rewards empilés, push notifications en 6 langues — 22 fichiers modifiés, 1324 lignes ajoutées. En une journée. Voici comment j'ai construit un système de referral complet en React Native, les pièges techniques à éviter, et pourquoi c'est l'investissement marketing le plus rentable pour un dev solo.

Points clés à retenir :
- Un système de parrainage nécessite 3 sources de capture (deep links web, Android App Links, Play Store Install Referrer) pour couvrir tous les scénarios d'installation.
- Le Play Store Install Referrer est la source la plus sous-estimée : il capture le code même si l'installation se fait 3 jours après le clic.
- Les rewards empilés (file d'attente de mois gratuits) sont plus motivants qu'une récompense unique mais ajoutent de la complexité avec RevenueCat.
- La vérification Android App Links est fragile : le SHA256 dans assetlinks.json doit correspondre exactement à la clé de signature.

Pourquoi un système de parrainage est-il le meilleur investissement pour un dev solo ?

Je développe TAMSIV, un gestionnaire de tâches vocal pour Android. Dev solo, 660+ commits, 6 mois de travail. J'ai 12 testeurs alpha sur le Play Store et j'ai besoin que ce nombre grandisse — organiquement.

Les options classiques d'acquisition utilisateur pour une app mobile sont coûteuses :

• Publicité payante : 1 à 5 EUR par installation sur Google Ads, sans garantie de rétention.
• ASO (App Store Optimization) : long terme, résultats incertains sans budget marketing.
• Influenceurs : hors budget pour un dev solo.

Le parrainage, c'est différent. Comme le montre ReferralCandy, les utilisateurs acquis par referral ont un taux de rétention 37% supérieur et un LTV (Lifetime Value) 16% plus élevé. La raison est simple : la recommandation d'un ami est la forme de marketing la plus fiable.

Le concept est simple : chaque utilisateur a un code de parrainage unique. Tu le partages. Quand quelqu'un s'inscrit avec, les deux gagnent 1 mois Pro gratuit. Et ça se cumule — 10 parrainages = 10 mois gratuits, mis en file d'attente les uns après les autres.

Quelles sont les 3 sources de capture indispensables pour un système de referral Android ?

La partie la plus difficile n'est pas de générer les codes. C'est de les capturer de manière fiable. Sur Android, il y a trois scénarios d'installation complètement différents, et chacun nécessite sa propre mécanique de capture.

Source 1 : Deep links via le site web

Quand quelqu'un visite tamsiv.com/invite/CODE, Next.js redirige vers le Play Store avec le code de parrainage intégré. C'est le flux le plus simple :

1. L'utilisateur A partage son lien tamsiv.com/invite/ABC123
2. L'utilisateur B clique — Next.js détecte le code et redirige vers le Play Store
3. Le code est passé via le paramètre referrer de l'URL Play Store
4. L'app le récupère à l'installation via l'Install Referrer API

Source 2 : Android App Links (ouverture directe)

Si l'app est déjà installée, tamsiv://invite/CODE l'ouvre directement. C'est le cas où un utilisateur existant partage son code à quelqu'un qui a déjà l'app. Cela nécessite :

• La configuration du AndroidManifest.xml avec les intent-filters pour le scheme tamsiv://
• Un fichier assetlinks.json sur le site pour la vérification du domaine par Google
• Le SHA256 exact de la clé de signature dans le fichier assetlinks

C'est ici que les choses se compliquent. La vérification Android App Links est fragile. Si le SHA256 ne correspond pas exactement — et il y a une différence entre la clé de debug et la clé de production — le lien s'ouvre dans le navigateur au lieu de l'app. Pas d'erreur, pas de message. Ça ne marche juste pas.

Source 3 : Play Store Install Referrer

C'est la source la plus sous-estimée et la plus puissante. Quand quelqu'un clique sur un lien Play Store avec un paramètre &referrer=CODE, Android stocke cette chaîne. Même si la personne installe l'app 3 jours plus tard, on peut toujours lire le code.

L'API Play Install Referrer permet de récupérer ce paramètre au premier lancement. La plupart des tutoriels passent cette méthode, mais c'est le seul moyen fiable de capturer les parrainages via des installations différées.

Comment implémenter des rewards empilés avec RevenueCat ?

La plupart des systèmes de parrainage donnent une récompense unique. "Parraine un ami, gagne un mois gratuit." Fini. Pas de motivation pour un deuxième parrainage.

Je voulais que les rewards s'accumulent. Chaque parrainage ajoute 30 jours de Pro, mis en file d'attente après l'expiration du précédent. 10 parrainages = 10 mois gratuits. L'incitation reste constante.

La complexité technique avec RevenueCat

RevenueCat gère les abonnements de TAMSIV (Free, Pro, Team). Mais RevenueCat n'a pas de concept natif de "crédit de temps gratuit empilé". Il faut le gérer côté serveur :

1. Table de rewards : chaque parrainage crée une ligne dans privat.referral_rewards avec un statut (pending, active, used, expired).
2. File d'attente : quand un reward actif expire, le suivant en file est activé automatiquement via un cron job backend.
3. Synchronisation RevenueCat : le backend utilise l'API RevenueCat pour accorder un promotional entitlement de 30 jours, renouvelé automatiquement si d'autres rewards sont en attente.
4. Vérification de doublons : un utilisateur ne peut pas parrainer la même personne deux fois. Le code est vérifié côté backend avant d'accorder le reward.

Un simple "donne 1 mois gratuit" est facile. Mettre en file d'attente plusieurs récompenses demande de gérer les dates de début, de fin, et la relation avec RevenueCat. C'est la partie qui a pris le plus de temps dans la journée.

Comment envoyer des push notifications de parrainage en 6 langues ?

Quand quelqu'un utilise ton code, tu reçois une notification push. Dans ta langue. Parce que TAMSIV parle 6 langues, le backend vérifie la préférence linguistique du parrain avant d'envoyer via FCM (Firebase Cloud Messaging).

Le template de notification est traduit dans les 6 langues :

• FR : "Ton ami {name} a utilisé ton code ! Tu gagnes 1 mois Pro gratuit."
• EN : "Your friend {name} used your code! You earn 1 free Pro month."
• DE, ES, IT, PT : équivalents traduits

C'est un détail, mais c'est le genre de détail qui rend le système professionnel. Recevoir une notification de parrainage dans une langue que tu ne comprends pas tue l'excitement du moment. La notification doit être aussi naturelle qu'un message d'un ami.

Quelles sont les erreurs techniques à éviter avec les deep links Android ?

Après cette journée de développement, voici les pièges que j'ai rencontrés :

Piège 1 : le fichier assetlinks.json

Le fichier .well-known/assetlinks.json doit être servi exactement au bon endroit (https://tamsiv.com/.well-known/assetlinks.json) avec le SHA256 exact de ta clé de signature. Attention : la clé de debug et la clé de production ont des SHA256 différents. Google Play App Signing ajoute une couche supplémentaire — tu dois utiliser le SHA256 du certificat de upload, pas celui de signing.

Piège 2 : le caching des intent-filters

Android met en cache les intent-filters. Si tu corriges ton assetlinks.json, l'appareil peut continuer à utiliser l'ancienne vérification pendant des heures. Solution : désinstaller complètement l'app, vider le cache Chrome, et réinstaller.

Piège 3 : le referrer URL encoding

Le paramètre referrer de l'URL Play Store doit être correctement encodé. Les caractères spéciaux dans le code (si tu utilises des UUIDs) doivent être échappés. J'ai perdu 30 minutes à cause d'un + dans un code qui était décodé comme un espace.

Quels résultats attendre d'un système de parrainage pour une app en alpha ?

Avec 12 testeurs alpha, les résultats absolus sont modestes. Mais le système est prêt à scaler. Le ROI se mesure en deux dimensions :

• Coût d'acquisition : 0 EUR par utilisateur acquis via parrainage (vs 1-5 EUR en publicité payante).
• Qualité des utilisateurs : un utilisateur parrainé connaît déjà le concept grâce à la recommandation — le taux de rétention est mécaniquement supérieur.
• Effet viral : chaque nouvel utilisateur peut lui-même parrainer — le coût marginal d'acquisition tend vers zéro.

Pour un dev solo sans budget marketing, c'est exactement le type de mécanisme qui permet de croître sans payer. C'est complémentaire avec la stratégie d'internationalisation comme canal d'acquisition que j'ai mise en place.

Quel est le bilan technique de cette journée de développement ?

En chiffres :

• 22 fichiers modifiés (backend, frontend, website, manifeste Android)
• 1 324 lignes ajoutées
• 1 journée de travail concentré (8 heures)
• 6 langues supportées pour les notifications
• 3 sources de capture pour une couverture maximale

Le système touche toutes les couches de l'architecture : le monorepo (frontend, backend, website), la base de données (Supabase), les notifications (FCM), et les abonnements (RevenueCat). C'est ce qui rend la feature complexe — elle n'est pas isolée dans un module, elle traverse tout.

Questions fréquentes

Le Play Store Install Referrer fonctionne-t-il sur tous les appareils Android ?

Oui, à condition que le Play Store soit à jour (version 8.3.73+, soit >99% des appareils actifs). L'API est fournie par Google via la librairie com.android.installreferrer. Sur les rares appareils sans Play Services (Huawei AppGallery), il faut un fallback.

Combien de temps le referrer est-il conservé par le Play Store ?

Selon la documentation Google, le referrer est conservé pendant 90 jours après le clic. C'est largement suffisant pour capturer les installations différées — même si l'utilisateur attend plusieurs semaines avant d'installer l'app.

Comment éviter les abus du système de parrainage (comptes multiples) ?

Trois mécanismes de protection : (1) vérification de l'email unique — un email ne peut recevoir qu'un seul reward de parrainage, (2) rate limiting — maximum 5 parrainages par heure par parrain, (3) vérification côté backend — le code est valide et le parrainé n'a jamais été parrainé auparavant. Le système de rate limiting global de TAMSIV protège contre les tentatives d'abus.

RevenueCat supporte-t-il nativement les promotional entitlements ?

Oui, via l'API REST (POST /subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional). Tu peux accorder un entitlement pour une durée définie (30 jours dans notre cas). Cependant, la gestion de la file d'attente (empilement de rewards) doit être faite côté serveur — RevenueCat ne gère que l'entitlement actif.

Faut-il un backend pour un système de parrainage ou peut-on tout faire côté client ?

Un backend est indispensable pour la sécurité. Toute la logique de validation (code valide, utilisateur éligible, anti-fraude) doit être côté serveur. Le frontend se contente d'envoyer le code et de recevoir le résultat. La génération de codes, l'attribution de rewards et l'envoi de notifications se font exclusivement côté backend.