Sistema de referidos React Native: guía completa en 1 día

Pasé 8 horas codificando algo que no tiene nada que ver con el producto en sí. Ni una nueva característica. Ni una corrección de errores. Ni una optimización. Un sistema de referidos completo — deep links de Android, Play Store Install Referrer, recompensas apiladas, notificaciones push en 6 idiomas — 22 archivos modificados, 1324 líneas añadidas. En un día. Así es como construí un sistema de referidos completo en React Native, las trampas técnicas a evitar y por qué es la inversión de marketing más rentable para un desarrollador en solitario.

Puntos clave a recordar:
- Un sistema de referidos necesita 3 fuentes de captura (deep links web, Android App Links, Play Store Install Referrer) para cubrir todos los escenarios de instalación.
- El Play Store Install Referrer es la fuente más subestimada: captura el código incluso si la instalación se realiza 3 días después del clic.
- Las recompensas apiladas (cola de meses gratis) son más motivadoras que una recompensa única, pero añaden complejidad con RevenueCat.
- La verificación de Android App Links es frágil: el SHA256 en assetlinks.json debe coincidir exactamente con la clave de firma.

¿Por qué un sistema de referidos es la mejor inversión para un desarrollador en solitario?

Desarrollo TAMSIV, un gestor de tareas por voz para Android. Desarrollador en solitario, más de 660 commits, 6 meses de trabajo. Tengo 12 testers alfa en Play Store y necesito que este número crezca — orgánicamente.

Las opciones clásicas de adquisición de usuarios para una aplicación móvil son costosas:

• Publicidad pagada: 1 a 5 EUR por instalación en Google Ads, sin garantía de retención.
• ASO (App Store Optimization): a largo plazo, resultados inciertos sin presupuesto de marketing.
• Influencers: fuera de presupuesto para un desarrollador en solitario.

El referido es diferente. Como muestra ReferralCandy, los usuarios adquiridos por referido tienen una tasa de retención un 37% superior y un LTV (Lifetime Value) un 16% más alto. La razón es simple: la recomendación de un amigo es la forma más fiable de marketing.

El concepto es simple: cada usuario tiene un código de referido único. Tú lo compartes. Cuando alguien se registra con él, ambos ganan 1 mes Pro gratis. Y se acumula — 10 referidos = 10 meses gratis, puestos en cola uno tras otro.

¿Cuáles son las 3 fuentes de captura indispensables para un sistema de referidos en Android?

La parte más difícil no es generar los códigos. Es capturarlos de manera fiable. En Android, hay tres escenarios de instalación completamente diferentes, y cada uno necesita su propia mecánica de captura.

Fuente 1: Deep links a través del sitio web

Cuando alguien visita tamsiv.com/invite/CODE, Next.js redirige a Play Store con el código de referido integrado. Este es el flujo más simple:

1. El usuario A comparte su enlace tamsiv.com/invite/ABC123
2. El usuario B hace clic — Next.js detecta el código y redirige a Play Store
3. El código se pasa a través del parámetro referrer de la URL de Play Store
4. La aplicación lo recupera en la instalación a través de la API Install Referrer

Fuente 2: Android App Links (apertura directa)

Si la aplicación ya está instalada, tamsiv://invite/CODE la abre directamente. Este es el caso en que un usuario existente comparte su código con alguien que ya tiene la aplicación. Esto requiere:

• La configuración del AndroidManifest.xml con los intent-filters para el esquema tamsiv://
• Un archivo assetlinks.json en el sitio para la verificación del dominio por parte de Google
• El SHA256 exacto de la clave de firma en el archivo assetlinks

Aquí es donde las cosas se complican. La verificación de Android App Links es frágil. Si el SHA256 no coincide exactamente — y hay una diferencia entre la clave de depuración y la clave de producción — el enlace se abre en el navegador en lugar de la aplicación. Sin error, sin mensaje. Simplemente no funciona.

Fuente 3: Play Store Install Referrer

Esta es la fuente más subestimada y poderosa. Cuando alguien hace clic en un enlace de Play Store con un parámetro &referrer=CODE, Android almacena esta cadena. Incluso si la persona instala la aplicación 3 días después, aún podemos leer el código.

La API Play Install Referrer permite recuperar este parámetro en el primer lanzamiento. La mayoría de los tutoriales omiten este método, pero es la única forma fiable de capturar referidos a través de instalaciones diferidas.

¿Cómo implementar recompensas apiladas con RevenueCat?

La mayoría de los sistemas de referidos dan una recompensa única. "Refiere a un amigo, gana un mes gratis." Fin. No hay motivación para un segundo referido.

Yo quería que las recompensas se acumularan. Cada referido añade 30 días de Pro, puestos en cola después de la expiración del anterior. 10 referidos = 10 meses gratis. El incentivo se mantiene constante.

La complejidad técnica con RevenueCat

RevenueCat gestiona las suscripciones de TAMSIV (Free, Pro, Team). Pero RevenueCat no tiene un concepto nativo de "crédito de tiempo gratis apilado". Hay que gestionarlo en el lado del servidor:

1. Tabla de recompensas: cada referido crea una línea en privat.referral_rewards con un estado (pendiente, activo, usado, expirado).
2. Cola: cuando una recompensa activa expira, la siguiente en la cola se activa automáticamente a través de un cron job de backend.
3. Sincronización con RevenueCat: el backend utiliza la API de RevenueCat para otorgar un promotional entitlement de 30 días, renovado automáticamente si hay otras recompensas pendientes.
4. Verificación de duplicados: un usuario no puede referir a la misma persona dos veces. El código se verifica en el backend antes de otorgar la recompensa.

Un simple "dar 1 mes gratis" es fácil. Poner en cola varias recompensas requiere gestionar las fechas de inicio, fin y la relación con RevenueCat. Esta fue la parte que más tiempo llevó en el día.

¿Cómo enviar notificaciones push de referidos en 6 idiomas?

Cuando alguien usa tu código, recibes una notificación push. En tu idioma. Debido a que TAMSIV habla 6 idiomas, el backend verifica la preferencia lingüística del referente antes de enviar a través de FCM (Firebase Cloud Messaging).

La plantilla de notificación se traduce a los 6 idiomas:

• ES: "¡Tu amigo {name} usó tu código! Ganas 1 mes Pro gratis."
• 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, IT, PT: equivalentes traducidos

Es un detalle, pero es el tipo de detalle que hace que el sistema sea profesional. Recibir una notificación de referido en un idioma que no entiendes mata la emoción del momento. La notificación debe ser tan natural como un mensaje de un amigo.

¿Cuáles son los errores técnicos a evitar con los deep links de Android?

Después de este día de desarrollo, estas son las trampas que encontré:

Trampa 1: el archivo assetlinks.json

El archivo .well-known/assetlinks.json debe servirse exactamente en el lugar correcto (https://tamsiv.com/.well-known/assetlinks.json) con el SHA256 exacto de tu clave de firma. Atención: la clave de depuración y la clave de producción tienen SHA256 diferentes. Google Play App Signing añade una capa adicional — debes usar el SHA256 del certificado de upload, no el de signing.

Trampa 2: el caching de los intent-filters

Android almacena en caché los intent-filters. Si corriges tu assetlinks.json, el dispositivo puede seguir usando la verificación antigua durante horas. Solución: desinstalar completamente la aplicación, borrar la caché de Chrome y reinstalar.

Trampa 3: la codificación de la URL del referrer

El parámetro referrer de la URL de Play Store debe estar correctamente codificado. Los caracteres especiales en el código (si usas UUIDs) deben ser escapados. Perdí 30 minutos debido a un + en un código que se decodificaba como un espacio.

¿Qué resultados esperar de un sistema de referidos para una aplicación en alfa?

Con 12 testers alfa, los resultados absolutos son modestos. Pero el sistema está listo para escalar. El ROI se mide en dos dimensiones:

• Costo de adquisición: 0 EUR por usuario adquirido a través de referidos (frente a 1-5 EUR en publicidad pagada).
• Calidad de los usuarios: un usuario referido ya conoce el concepto gracias a la recomendación — la tasa de retención es mecánicamente superior.
• Efecto viral: cada nuevo usuario puede referir a otros — el costo marginal de adquisición tiende a cero.

Para un desarrollador en solitario sin presupuesto de marketing, este es exactamente el tipo de mecanismo que permite crecer sin pagar. Es complementario con la estrategia de internacionalización como canal de adquisición que he implementado.

¿Cuál es el balance técnico de este día de desarrollo?

En cifras:

• 22 archivos modificados (backend, frontend, sitio web, manifiesto de Android)
• 1.324 líneas añadidas
• 1 día de trabajo concentrado (8 horas)
• 6 idiomas soportados para las notificaciones
• 3 fuentes de captura para una cobertura máxima

El sistema toca todas las capas de la arquitectura: el monorepo (frontend, backend, sitio web), la base de datos (Supabase), las notificaciones (FCM) y las suscripciones (RevenueCat). Esto es lo que hace que la característica sea compleja — no está aislada en un módulo, sino que atraviesa todo.

Preguntas frecuentes

¿El Play Store Install Referrer funciona en todos los dispositivos Android?

Sí, siempre que Play Store esté actualizado (versión 8.3.73+, es decir, >99% de los dispositivos activos). La API es proporcionada por Google a través de la librería com.android.installreferrer. En los raros dispositivos sin Play Services (Huawei AppGallery), se necesita un fallback.

¿Cuánto tiempo se conserva el referrer por Play Store?

Según la documentación de Google, el referrer se conserva durante 90 días después del clic. Esto es más que suficiente para capturar instalaciones diferidas, incluso si el usuario espera varias semanas antes de instalar la aplicación.

¿Cómo evitar el abuso del sistema de referidos (cuentas múltiples)?

Tres mecanismos de protección: (1) verificación de correo electrónico único — un correo electrónico solo puede recibir una recompensa de referido, (2) rate limiting — máximo 5 referidos por hora por referente, (3) verificación en el backend — el código es válido y el referido nunca ha sido referido antes. El sistema de rate limiting global de TAMSIV protege contra los intentos de abuso.

¿RevenueCat soporta nativamente los promotional entitlements?

Sí, a través de la API REST (POST /subscribers/{app_user_id}/entitlements/{entitlement_id}/promotional). Puedes otorgar un entitlement por una duración definida (30 días en nuestro caso). Sin embargo, la gestión de la cola (apilamiento de recompensas) debe hacerse en el lado del servidor — RevenueCat solo gestiona el entitlement activo.

¿Se necesita un backend para un sistema de referidos o se puede hacer todo en el lado del cliente?

Un backend es indispensable para la seguridad. Toda la lógica de validación (código válido, usuario elegible, antifraude) debe estar en el lado del servidor. El frontend se limita a enviar el código y recibir el resultado. La generación de códigos, la asignación de recompensas y el envío de notificaciones se realizan exclusivamente en el backend.