Systeme de parrainage React Native : guide complet en 1 jour

J'ai passe 8 heures a coder quelque chose qui n'a rien a voir avec le produit lui-meme. Pas de nouvelle feature. Pas de bug fix. Pas d'optimisation. Un systeme de parrainage complet — deep links Android, Play Store Install Referrer, rewards empiles, push notifications en 6 langues — 22 fichiers modifies, 1324 lignes ajoutees. En une journee. Voici comment j'ai construit un systeme de referral complet en React Native, les pieges techniques a eviter, et pourquoi c'est l'investissement marketing le plus rentable pour un dev solo.

Points cles a retenir :
- Un systeme de parrainage necessite 3 sources de capture (deep links web, Android App Links, Play Store Install Referrer) pour couvrir tous les scenarios d'installation.
- Le Play Store Install Referrer est la source la plus sous-estimee : il capture le code meme si l'installation se fait 3 jours apres le clic.
- Les rewards empiles (file d'attente de mois gratuits) sont plus motivants qu'une recompense unique mais ajoutent de la complexite avec RevenueCat.
- La verification Android App Links est fragile : le SHA256 dans assetlinks.json doit correspondre exactement a la cle de signature.

Pourquoi un systeme de parrainage est-il le meilleur investissement pour un dev solo ?

Je developpe TAMSIV, un gestionnaire de taches 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 couteuses :

• Publicite payante : 1 a 5 EUR par installation sur Google Ads, sans garantie de retention.
• ASO (App Store Optimization) : long terme, resultats incertains sans budget marketing.
• Influenceurs : hors budget pour un dev solo.

Le parrainage, c'est different. Comme le montre ReferralCandy, les utilisateurs acquis par referral ont un taux de retention 37% superieur et un LTV (Lifetime Value) 16% plus eleve. 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 ca se cumule — 10 parrainages = 10 mois gratuits, mis en file d'attente les uns apres les autres.

Quelles sont les 3 sources de capture indispensables pour un systeme de referral Android ?

La partie la plus difficile n'est pas de generer les codes. C'est de les capturer de maniere fiable. Sur Android, il y a trois scenarios d'installation completement differents, et chacun necessite sa propre mecanique 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 integre. 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 detecte le code et redirige vers le Play Store
3. Le code est passe via le parametre referrer de l'URL Play Store
4. L'app le recupere a l'installation via l'Install Referrer API

Source 2 : Android App Links (ouverture directe)

Si l'app est deja installee, tamsiv://invite/CODE l'ouvre directement. C'est le cas ou un utilisateur existant partage son code a quelqu'un qui a deja l'app. Cela necessite :

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

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

Source 3 : Play Store Install Referrer

C'est la source la plus sous-estimee et la plus puissante. Quand quelqu'un clique sur un lien Play Store avec un parametre &referrer=CODE, Android stocke cette chaine. Meme si la personne installe l'app 3 jours plus tard, on peut toujours lire le code.

L'API Play Install Referrer permet de recuperer ce parametre au premier lancement. La plupart des tutoriels passent cette methode, mais c'est le seul moyen fiable de capturer les parrainages via des installations differees.

Comment implementer des rewards empiles avec RevenueCat ?

La plupart des systemes de parrainage donnent une recompense unique. "Parraine un ami, gagne un mois gratuit." Fini. Pas de motivation pour un deuxieme parrainage.

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

La complexite technique avec RevenueCat

RevenueCat gere les abonnements de TAMSIV (Free, Pro, Team). Mais RevenueCat n'a pas de concept natif de "credit de temps gratuit empile". Il faut le gerer cote serveur :

1. Table de rewards : chaque parrainage cree 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 active automatiquement via un cron job backend.
3. Synchronisation RevenueCat : le backend utilise l'API RevenueCat pour accorder un promotional entitlement de 30 jours, renouvele automatiquement si d'autres rewards sont en attente.
4. Verification de doublons : un utilisateur ne peut pas parrainer la meme personne deux fois. Le code est verifie cote backend avant d'accorder le reward.

Un simple "donne 1 mois gratuit" est facile. Mettre en file d'attente plusieurs recompenses demande de gerer les dates de debut, de fin, et la relation avec RevenueCat. C'est la partie qui a pris le plus de temps dans la journee.

Comment envoyer des push notifications de parrainage en 6 langues ?

Quand quelqu'un utilise ton code, tu recois une notification push. Dans ta langue. Parce que TAMSIV parle 6 langues, le backend verifie la preference 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 utilise 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 : equivalents traduits

C'est un detail, mais c'est le genre de detail qui rend le systeme professionnel. Recevoir une notification de parrainage dans une langue que tu ne comprends pas tue l'excitement du moment. La notification doit etre aussi naturelle qu'un message d'un ami.

Quelles sont les erreurs techniques a eviter avec les deep links Android ?

Apres cette journee de developpement, voici les pieges que j'ai rencontres :

Piege 1 : le fichier assetlinks.json

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

Piege 2 : le caching des intent-filters

Android met en cache les intent-filters. Si tu corriges ton assetlinks.json, l'appareil peut continuer a utiliser l'ancienne verification pendant des heures. Solution : desinstaller completement l'app, vider le cache Chrome, et reinstaller.

Piege 3 : le referrer URL encoding

Le parametre referrer de l'URL Play Store doit etre correctement encode. Les caracteres speciaux dans le code (si tu utilises des UUIDs) doivent etre echappes. J'ai perdu 30 minutes a cause d'un + dans un code qui etait decode comme un espace.

Quels resultats attendre d'un systeme de parrainage pour une app en alpha ?

Avec 12 testeurs alpha, les resultats absolus sont modestes. Mais le systeme est pret a scaler. Le ROI se mesure en deux dimensions :

• Cout d'acquisition : 0 EUR par utilisateur acquis via parrainage (vs 1-5 EUR en publicite payante).
• Qualite des utilisateurs : un utilisateur parraine connait deja le concept grace a la recommandation — le taux de retention est mecaniquement superieur.
• Effet viral : chaque nouvel utilisateur peut lui-meme parrainer — le cout marginal d'acquisition tend vers zero.

Pour un dev solo sans budget marketing, c'est exactement le type de mecanisme qui permet de croitre sans payer. C'est complementaire avec la strategie d'internationalisation comme canal d'acquisition que j'ai mise en place.

Quel est le bilan technique de cette journee de developpement ?

En chiffres :

• 22 fichiers modifies (backend, frontend, website, manifeste Android)
• 1 324 lignes ajoutees
• 1 journee de travail concentre (8 heures)
• 6 langues supportees pour les notifications
• 3 sources de capture pour une couverture maximale

Le systeme touche toutes les couches de l'architecture : le monorepo (frontend, backend, website), la base de donnees (Supabase), les notifications (FCM), et les abonnements (RevenueCat). C'est ce qui rend la feature complexe — elle n'est pas isolee dans un module, elle traverse tout.

Questions frequentes

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

Oui, a condition que le Play Store soit a 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 conserve par le Play Store ?

Selon la documentation Google, le referrer est conserve pendant 90 jours apres le clic. C'est largement suffisant pour capturer les installations differees — meme si l'utilisateur attend plusieurs semaines avant d'installer l'app.

Comment eviter les abus du systeme de parrainage (comptes multiples) ?

Trois mecanismes de protection : (1) verification 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) verification cote backend — le code est valide et le parraine n'a jamais ete parraine auparavant. Le systeme de rate limiting global de TAMSIV protege 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 duree definie (30 jours dans notre cas). Cependant, la gestion de la file d'attente (empilement de rewards) doit etre faite cote serveur — RevenueCat ne gere que l'entitlement actif.

Faut-il un backend pour un systeme de parrainage ou peut-on tout faire cote client ?

Un backend est indispensable pour la securite. Toute la logique de validation (code valide, utilisateur eligible, anti-fraude) doit etre cote serveur. Le frontend se contente d'envoyer le code et de recevoir le resultat. La generation de codes, l'attribution de rewards et l'envoi de notifications se font exclusivement cote backend.