Sistema di referral React Native: guida completa in 1 giorno

Ho passato 8 ore a programmare qualcosa che non ha nulla a che fare con il prodotto stesso. Nessuna nuova funzionalità. Nessun bug fix. Nessuna ottimizzazione. Un sistema di referral completo — deep link Android, Play Store Install Referrer, ricompense accumulate, notifiche push in 6 lingue — 22 file modificati, 1324 righe aggiunte. In un solo giorno. Ecco come ho costruito un sistema di referral completo in React Native, le trappole tecniche da evitare e perché è l'investimento di marketing più redditizio per uno sviluppatore solista.

Punti chiave da ricordare:
- Un sistema di referral richiede 3 fonti di acquisizione (deep link web, Android App Links, Play Store Install Referrer) per coprire tutti gli scenari di installazione.
- Il Play Store Install Referrer è la fonte più sottovalutata: cattura il codice anche se l'installazione avviene 3 giorni dopo il clic.
- Le ricompense accumulate (coda di mesi gratuiti) sono più motivanti di una ricompensa unica, ma aggiungono complessità con RevenueCat.
- La verifica degli Android App Links è fragile: lo SHA256 in assetlinks.json deve corrispondere esattamente alla chiave di firma.

Perché un sistema di referral è il miglior investimento per uno sviluppatore solista?

Sto sviluppando TAMSIV, un gestore di attività vocale per Android. Sviluppatore solista, oltre 660 commit, 6 mesi di lavoro. Ho 12 tester alpha sul Play Store e ho bisogno che questo numero cresca — organicamente.

Le opzioni classiche di acquisizione utenti per un'app mobile sono costose:

• Pubblicità a pagamento: da 1 a 5 EUR per installazione su Google Ads, senza garanzia di retention.
• ASO (App Store Optimization): a lungo termine, risultati incerti senza budget di marketing.
• Influencer: fuori budget per uno sviluppatore solista.

Il referral è diverso. Come mostrato da ReferralCandy, gli utenti acquisiti tramite referral hanno un tasso di retention superiore del 37% e un LTV (Lifetime Value) superiore del 16%. La ragione è semplice: la raccomandazione di un amico è la forma di marketing più affidabile.

Il concetto è semplice: ogni utente ha un codice di referral unico. Tu lo condividi. Quando qualcuno si iscrive con esso, entrambi guadagnano 1 mese Pro gratuito. E si accumula — 10 referral = 10 mesi gratuiti, messi in coda uno dopo l'altro.

Quali sono le 3 fonti di acquisizione indispensabili per un sistema di referral Android?

La parte più difficile non è generare i codici. È catturarli in modo affidabile. Su Android, ci sono tre scenari di installazione completamente diversi, e ognuno richiede la propria meccanica di acquisizione.

Fonte 1: Deep link tramite il sito web

Quando qualcuno visita tamsiv.com/invite/CODE, Next.js reindirizza al Play Store con il codice di referral integrato. Questo è il flusso più semplice:

1. L'utente A condivide il suo link tamsiv.com/invite/ABC123
2. L'utente B clicca — Next.js rileva il codice e reindirizza al Play Store
3. Il codice viene passato tramite il parametro referrer dell'URL del Play Store
4. L'app lo recupera all'installazione tramite l'API Install Referrer

Fonte 2: Android App Links (apertura diretta)

Se l'app è già installata, tamsiv://invite/CODE la apre direttamente. Questo è il caso in cui un utente esistente condivide il suo codice con qualcuno che ha già l'app. Ciò richiede:

• La configurazione di AndroidManifest.xml con gli intent-filter per lo schema tamsiv://
• Un file assetlinks.json sul sito per la verifica del dominio da parte di Google
• Lo SHA256 esatto della chiave di firma nel file assetlinks

È qui che le cose si complicano. La verifica degli Android App Links è fragile. Se lo SHA256 non corrisponde esattamente — e c'è una differenza tra la chiave di debug e la chiave di produzione — il link si apre nel browser invece che nell'app. Nessun errore, nessun messaggio. Semplicemente non funziona.

Fonte 3: Play Store Install Referrer

Questa è la fonte più sottovalutata e più potente. Quando qualcuno clicca su un link del Play Store con un parametro &referrer=CODE, Android memorizza questa stringa. Anche se la persona installa l'app 3 giorni dopo, possiamo comunque leggere il codice.

L'API Play Install Referrer consente di recuperare questo parametro al primo avvio. La maggior parte dei tutorial salta questo metodo, ma è l'unico modo affidabile per catturare i referral tramite installazioni differite.

Come implementare ricompense accumulate con RevenueCat?

La maggior parte dei sistemi di referral offre una ricompensa unica. "Invita un amico, guadagna un mese gratuito." Finito. Nessuna motivazione per un secondo referral.

Volevo che le ricompense si accumulassero. Ogni referral aggiunge 30 giorni di Pro, messi in coda dopo la scadenza del precedente. 10 referral = 10 mesi gratuiti. L'incentivo rimane costante.

La complessità tecnica con RevenueCat

RevenueCat gestisce gli abbonamenti di TAMSIV (Free, Pro, Team). Ma RevenueCat non ha un concetto nativo di "credito di tempo gratuito accumulato". Bisogna gestirlo lato server:

1. Tabella delle ricompense: ogni referral crea una riga in privat.referral_rewards con uno stato (pending, active, used, expired).
2. Coda: quando una ricompensa attiva scade, la successiva in coda viene attivata automaticamente tramite un cron job backend.
3. Sincronizzazione RevenueCat: il backend utilizza l'API RevenueCat per concedere un promotional entitlement di 30 giorni, rinnovato automaticamente se altre ricompense sono in attesa.
4. Verifica dei duplicati: un utente non può invitare la stessa persona due volte. Il codice viene verificato lato backend prima di concedere la ricompensa.

Un semplice "dai 1 mese gratuito" è facile. Mettere in coda più ricompense richiede la gestione delle date di inizio, di fine e la relazione con RevenueCat. Questa è la parte che ha richiesto più tempo durante la giornata.

Come inviare notifiche push di referral in 6 lingue?

Quando qualcuno usa il tuo codice, ricevi una notifica push. Nella tua lingua. Poiché TAMSIV parla 6 lingue, il backend verifica la preferenza linguistica del referrer prima di inviare tramite FCM (Firebase Cloud Messaging).

Il template di notifica è tradotto nelle 6 lingue:

• 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: equivalenti tradotti

È un dettaglio, ma è il tipo di dettaglio che rende il sistema professionale. Ricevere una notifica di referral in una lingua che non capisci uccide l'emozione del momento. La notifica deve essere naturale come un messaggio di un amico.

Quali errori tecnici evitare con i deep link Android?

Dopo questa giornata di sviluppo, ecco le insidie che ho incontrato:

Trappola 1: il file assetlinks.json

Il file .well-known/assetlinks.json deve essere servito esattamente nel posto giusto (https://tamsiv.com/.well-known/assetlinks.json) con lo SHA256 esatto della tua chiave di firma. Attenzione: la chiave di debug e la chiave di produzione hanno SHA256 diversi. Google Play App Signing aggiunge un ulteriore livello — devi usare lo SHA256 del certificato di upload, non quello di signing.

Trappola 2: il caching degli intent-filter

Android memorizza nella cache gli intent-filter. Se correggi il tuo assetlinks.json, il dispositivo può continuare a usare la vecchia verifica per ore. Soluzione: disinstallare completamente l'app, svuotare la cache di Chrome e reinstallare.

Trappola 3: l'encoding dell'URL referrer

Il parametro referrer dell'URL del Play Store deve essere codificato correttamente. I caratteri speciali nel codice (se usi UUID) devono essere escapati. Ho perso 30 minuti a causa di un + in un codice che veniva decodificato come uno spazio.

Quali risultati aspettarsi da un sistema di referral per un'app in alpha?

Con 12 tester alpha, i risultati assoluti sono modesti. Ma il sistema è pronto a scalare. Il ROI si misura in due dimensioni:

• Costo di acquisizione: 0 EUR per utente acquisito tramite referral (vs 1-5 EUR in pubblicità a pagamento).
• Qualità degli utenti: un utente referenziato conosce già il concetto grazie alla raccomandazione — il tasso di retention è meccanicamente superiore.
• Effetto virale: ogni nuovo utente può a sua volta referenziare — il costo marginale di acquisizione tende a zero.

Per uno sviluppatore solista senza budget di marketing, questo è esattamente il tipo di meccanismo che permette di crescere senza pagare. È complementare alla strategia di internazionalizzazione come canale di acquisizione che ho implementato.

Qual è il bilancio tecnico di questa giornata di sviluppo?

In cifre:

• 22 file modificati (backend, frontend, website, manifesto Android)
• 1.324 righe aggiunte
• 1 giornata di lavoro concentrato (8 ore)
• 6 lingue supportate per le notifiche
• 3 fonti di acquisizione per la massima copertura

Il sistema tocca tutti gli strati dell'architettura: il monorepo (frontend, backend, website), il database (Supabase), le notifiche (FCM) e gli abbonamenti (RevenueCat). Questo è ciò che rende la funzionalità complessa — non è isolata in un modulo, attraversa tutto.

Domande frequenti

Il Play Store Install Referrer funziona su tutti i dispositivi Android?

Sì, a condizione che il Play Store sia aggiornato (versione 8.3.73+, ovvero >99% dei dispositivi attivi). L'API è fornita da Google tramite la libreria com.android.installreferrer. Sui rari dispositivi senza Play Services (Huawei AppGallery), è necessario un fallback.

Per quanto tempo il referrer viene conservato dal Play Store?

Secondo la documentazione di Google, il referrer viene conservato per 90 giorni dopo il clic. Questo è ampiamente sufficiente per catturare le installazioni differite — anche se l'utente aspetta diverse settimane prima di installare l'app.

Come evitare gli abusi del sistema di referral (account multipli)?

Tre meccanismi di protezione: (1) verifica dell'email unica — un'email può ricevere un solo reward di referral, (2) rate limiting — massimo 5 referral all'ora per referrer, (3) verifica lato backend — il codice è valido e il referenziato non è mai stato referenziato prima. Il sistema di rate limiting globale di TAMSIV protegge dai tentativi di abuso.

RevenueCat supporta nativamente i promotional entitlements?

Sì, tramite l'API REST (POST /subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional). Puoi concedere un entitlement per una durata definita (30 giorni nel nostro caso). Tuttavia, la gestione della coda (accumulo di ricompense) deve essere fatta lato server — RevenueCat gestisce solo l'entitlement attivo.

È necessario un backend per un sistema di referral o si può fare tutto lato client?

Un backend è indispensabile per la sicurezza. Tutta la logica di validazione (codice valido, utente idoneo, anti-frode) deve essere lato server. Il frontend si limita a inviare il codice e a ricevere il risultato. La generazione dei codici, l'attribuzione delle ricompense e l'invio delle notifiche avvengono esclusivamente lato backend.