Recomendaciones en la app

Permite que los usuarios de tu app se conviertan en recomendadores desde dentro de tu app. Con una sola llamada al SDK puedes mostrar una pantalla Recomienda a un amigo lista para usar, dar a cada usuario su propio código y enlace, y ver cuántos amigos ha traído, para recompensarlo en tu app con créditos, tokens o tiempo gratis.

Los recomendadores en la app son afiliados normales. Tienen acceso a un panel, aparecen en tu lista de afiliados y pueden ganar comisión, recompensas en la app o ambas cosas.

Cómo funciona

1. Tu app inscribe al usuario. El SDK envía el correo electrónico y el nombre del usuario. Insert Affiliate crea su cuenta de afiliado, su código corto y (en las empresas que usan Insert Links) su enlace.
2. El usuario comparte. La pantalla lista para usar muestra su código y su enlace con los botones Copy y Share. Para compartir se usa el menú de compartir del propio teléfono.
3. Los amigos se atribuyen como siempre. Las instalaciones, los eventos y las compras del dispositivo del amigo se atribuyen al recomendador exactamente igual que con cualquier otro afiliado.
4. Tú lo recompensas. El SDK, un webhook y la API pública informan un recuento de recomendaciones. Cuando aumenta, otorga la recompensa.

Cómo se ve la pantalla

La pantalla Recomienda a un amigo lista para usar en una app real, desde la inscripción, pasando por el código y el enlace del recomendador con Copy y Share, hasta los códigos de recompensa que ha ganado:

Configúralo en tu panel

1. Ve a Configuración → Recomendaciones en la app
2. Activa Permite que los usuarios se conviertan en recomendadores desde tu app
3. Elige Qué cuenta como recomendación:
   • Un amigo realiza una compra (recomendado): cuenta las compras nuevas, no las renovaciones
   • Un amigo completa un evento dentro de la app: cuenta un evento registrado, como signup. Introduce el nombre del evento que envía tu app.
   • Un amigo instala la app: cuenta las instalaciones y aperturas atribuidas. Es la opción más fácil de falsear; consulta qué tan seguro es el recuento y las reglas de las tiendas.
4. Si quieres, activa Requerir un código por correo para nuevos recomendadores si tu app no verifica por sí misma las direcciones de correo electrónico
5. Define el Título, el Color del botón y el Texto de la recompensa que se muestran en la pantalla lista para usar. La vista previa se actualiza mientras escribes.
6. Haz clic en Guardar configuración de recomendaciones

Los cambios en el texto y el color de la pantalla llegan a tu app de inmediato, sin necesidad de publicar una nueva versión.

Añádelo a tu app

Todos los SDK tienen los mismos métodos. La vía más rápida es la pantalla lista para usar, que se encarga por ti de la inscripción, del paso del código por correo y de compartir.

React Native

import { ReferAFriend } from 'insert-affiliate-react-native-sdk';

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  email={currentUser.email}
  name={currentUser.name}
/>

Swift (iOS)

InsertAffiliateSwift.showReferAFriend(
  from: viewController,
  options: ReferAFriendOptions(email: currentUser.email, name: currentUser.name)
)

Flutter, Android (Java/Kotlin), Unity y JavaScript usan los mismos nombres de métodos. Consulta el README de cada SDK para ver su sintaxis exacta: Swift, Android, React Native, Flutter, Unity, JavaScript.

Cambiar el texto de la pantalla

La pantalla viene con textos en inglés. Tu app puede reemplazar cualquier etiqueta de la pantalla con una opción strings, que se pasa al abrir la pantalla. Así es como traduces la pantalla, ya que no incluimos traducciones, y como cambias su redacción para que suene como tu app.

<ReferAFriend
  visible={showReferral}
  onClose={() => setShowReferral(false)}
  strings={{
    emailLabel: 'Correo electrónico',
    joinButton: 'Obtener mi enlace',
    codeSentNotice: 'Enviamos un código de 6 dígitos a {email}.',
    shareButton: 'Compartir',
    premiumUntil: 'Premium gratis hasta {date}',
  }}
/>

Reglas para todos los SDK:

• Reemplaza solo lo que quieras. Una clave que omitas, o que definas como cadena vacía, conserva nuestro texto en inglés. Una clave que no conocemos se ignora.
• Conserva los marcadores. {email} en codeSentNotice y {date} en premiumUntil se rellenan al mostrar el texto.
• El título y el texto de la recompensa no están en strings. Vienen de tu panel, y cada SDK tiene su propia opción para reemplazarlos en cada llamada.

Las claves que comparten la mayoría de los SDK:

La pantalla de cada SDK es un poco distinta, así que cada README tiene la lista completa con nuestros textos predeterminados en inglés. El SDK de JavaScript separa copyCodeButton y copyLinkButton y no tiene el título "Your code", y los SDK de Android, Unity, Flutter y React Native añaden claves para etiquetas propias, como un título "Your link" separado o el texto de ejemplo dentro de los campos.

Un código de error para el que no tenemos clave usa errorServer.

Dar estilo a la pantalla

El mismo objeto de opciones también define el aspecto, en cada llamada:

• Color: primaryColor, un valor #RRGGBB que reemplaza el color de botón de tu panel.
• Fuente: fontName en Swift, fontFamily en React Native, Flutter y JavaScript, font en Unity y setTypeface en Android.
• Radio de las esquinas: cornerRadius para los botones, los campos y la propia hoja.
• Texto para compartir: shareMessage, el mensaje con el que se abre el menú de compartir.

Crear tu propia pantalla

¿Prefieres tu propio diseño? Omite nuestra pantalla y llama tú mismo a los métodos. Son todo lo que usa la pantalla lista para usar.

Llámalos en este orden:

1. getReferralProgramConfig() cuando se abra tu pantalla. Si no está activado, no muestres la pantalla.
2. getMyAffiliateDetails() al mismo tiempo. Si devuelve datos, este dispositivo ya está conectado, así que pasa directamente al estado de inscrito.
3. No inscrito: pide un correo electrónico y un nombre, y llama a createAffiliateForUser. created lleva al estado de inscrito y verificationRequired lleva al paso del código.
4. Código necesario: pide el código de 6 dígitos y llama a verifyAffiliateCode. Para enviar un código nuevo, vuelve a llamar a createAffiliateForUser.
5. Inscrito: muestra el código corto y el enlace, referralCount, totalEarned y currency, y ofrece copiar y compartir.
6. Recompensas: rewardsGranted y premiumUntil cubren el tiempo premium gratis. rewardCodes contiene códigos de tienda, cada uno con code, store y redeemUrl. Muestra solo los del teléfono que usa el usuario, porque un código de App Store no se puede canjear en Android y un código de Google Play no se puede canjear en iPhone.
7. Errores: todos los errores llegan como un código, como PROGRAM_DISABLED, AFFILIATE_LIMIT_REACHED, INVALID_EMAIL, INVALID_CODE, TOO_MANY_CODES o RATE_LIMITED, para que puedas escribir tus propios mensajes.
8. setReferrerAccount cuando el usuario se suscriba o inicie sesión más adelante, y signOutAffiliate() cuando cierre sesión.

Dos cosas que debes saber antes de empezar:

• Un resultado vacío no dice por qué. getMyAffiliateDetails() no devuelve nada tanto cuando el dispositivo no está conectado como cuando la solicitud falló. Consulta isUserAnAffiliate() después para distinguirlos: si sigue siendo verdadero, la solicitud falló y vale la pena reintentarla.
• Algunas funciones auxiliares de la pantalla son internas. Filtrar los códigos de recompensa por tienda, construir el texto para compartir y limpiar un código escrito no son públicas, así que tu pantalla debe implementar las suyas. Son un par de líneas cada una sobre lo que ya devuelven los métodos, y shareReferralLink cubre el texto para compartir.

redeemUrl y dashboardUrl vienen de nuestro servidor, así que comprueba que cada uno empiece por https:// antes de abrirlo.

Reinstalaciones y teléfonos nuevos

Cuando un usuario se convierte en recomendador, su teléfono recibe un token de acceso privado que demuestra quién es. En iPhone se guarda en el Keychain, así que normalmente se conserva aunque se elimine y se vuelva a instalar la app.

Si el token se pierde (un teléfono nuevo, o una reinstalación en Android), volver a inscribir el mismo correo electrónico no da acceso de inmediato. En su lugar:

1. createAffiliateForUser devuelve verificationRequired y enviamos al usuario un código de 6 dígitos por correo
2. El usuario lo introduce y tu app llama a verifyAffiliateCode
3. El teléfono queda conectado de nuevo. Sus recomendaciones, ganancias y panel no cambian.

La pantalla lista para usar muestra este paso automáticamente. Los códigos caducan a los 10 minutos y dejan de funcionar tras 5 intentos fallidos, y enviamos como máximo 3 códigos por hora al mismo correo electrónico (después, createAffiliateForUser devuelve TOO_MANY_CODES). Cualquiera que ya sea tu afiliado, incluidos los creadores con panel, siempre confirma un código al conectar un teléfono nuevo. Esto también impide que alguien vea las recomendaciones de otra persona escribiendo su correo electrónico.

Recompensar a los recomendadores

Configúralo en Configuración → Recomendaciones en la app → Recompensas de recomendadores. Se aplica a cada nuevo recomendador que se une desde tu app:

• Comisión en efectivo: tu comisión predeterminada, sin efectivo (solo recompensas) o una comisión diferente solo para recomendadores.
• Descuento de su amigo: elige uno de tus códigos de oferta para iOS, Android y web. Los amigos que usan el enlace o el código de un recomendador lo reciben.
• Su recompensa por cada recomendación: Nada adicional (solo comisión), Tiempo premium gratis, otorgado automáticamente o Yo los recompensaré personalmente.

referralCount cuenta a cada amigo una sola vez y nunca disminuye.

Tiempo premium gratis, otorgado automáticamente

Otorgamos la recompensa a través de lo que uses para las compras, en el momento en que una recomendación cuenta:

Indícanos quién es el recomendador en tu sistema de compras, para que podamos recompensar a la cuenta correcta:

// When they join (RevenueCat app user ID or Adapty customer user ID)
await createAffiliateForUser(email, name, { appUserId: revenueCatAppUserId });

// Or later, e.g. once they subscribe (Android: their Play purchase token)
await setReferrerAccount({ appUserId, playPurchaseToken });

Si llega una recomendación antes de que tu app haya enviado esto, la recompensa espera y se otorga en cuanto llega.

En Android, envía el token de compra de Play del recomendador en cuanto se suscriba. Sin él no podemos saber que es suscriptor, así que recibe un código promocional en su lugar, y Google no permite canjear uno a quien ya se ha suscrito antes.

Códigos de oferta de App Store: creamos por ti códigos de un solo uso con tu clave de App Store Connect. Cada persona solo puede canjear un código por oferta, así que elige tus ofertas en orden: la 2.ª recompensa de un recomendador sale de tu 2.ª oferta, y así sucesivamente. La oferta decide lo que recibe, por ejemplo un mes gratis. Cada recomendador puede recibir una recompensa de App Store por cada oferta que elijas (hasta 20 ofertas). Cuando ya las ha recibido todas, las siguientes recompensas aparecen como failed, así que elige suficientes ofertas o recompensa tú mismo las demás.

Códigos promocionales de Google Play: Google no nos ofrece ninguna forma de crear códigos promocionales, y solo quienes nunca se han suscrito pueden canjear uno. Por eso, a los suscriptores se les retrasa el cobro y todos los demás reciben un código de una lista que subes tú:

1. En Play Console, abre Monetize with Play > Promo codes y crea una promoción de one-time codes para tu suscripción, con una prueba gratuita de 3 a 90 días. Google permite 10.000 códigos por suscripción cada trimestre.
2. Descarga el CSV y súbelo en Configuración > Recomendaciones en la app, con la fecha de fin de la promoción. Dejamos de entregar códigos 2 días antes de esa fecha.
3. Cada recompensa usa el siguiente código sin usar. Si se agotan, las recompensas esperan y se entregan en la hora siguiente a tu próxima subida.

Recompensarlos tú mismo

¿Qué tan seguro es el recuento? Depende de lo que cuentes:

• Las compras no se pueden falsear. Una compra solo cuenta después de verificarse con el recibo de la tienda a través de tu verificación de compras (App Store, Google Play, RevenueCat, Adapty y el resto), exactamente igual que cualquier venta de afiliado. Las recompensas basadas en compras son seguras, incluidos los meses gratis.
• Los registros y las instalaciones los informa tu app, así que una app modificada o llamadas automatizadas podrían falsearlos. Úsalos para pequeños beneficios y cuenta las compras para cualquier cosa valiosa.

Para la configuración más sólida, otorga las recompensas desde tu servidor. Tu backend lee el recuento verificado a través del webhook o de la API pública en lugar de fiarse de lo que muestra el teléfono.

Webhook: referral.created

Si tienes configurados webhooks, enviamos referral.created cada vez que ocurre algo que cuentas como recomendación:

{
  "event": "referral.created",
  "affiliate_id": "ia_45fee001",
  "email": "[email protected]",
  "deep_link": "https://myapp.link/ref/abc123",
  "short_code": "a1b2c3d4",
  "trigger": "purchase",
  "referral_count": 3,
  "reward_status": "not_automatic",
  "occurred_at": "2026-09-18T12:00:00.000Z"
}

Recompensa hasta referral_count. Como es un total acumulado, nunca recompensas dos veces, y el siguiente envío recupera cualquiera que te hayas perdido. Los webhooks no se reintentan, así que para tener la imagen completa consulta la API pública, que siempre muestra el recuento actual.

reward_status indica qué pasó con nuestra recompensa automática cuando se registró la recomendación:

• granted: otorgada
• not_automatic: no otorgamos ninguna recompensa. O elegiste Yo los recompensaré personalmente, así que recompénsalo ahora, o elegiste Nada adicional (solo comisión).
• waiting_for_account: todavía no conocemos la cuenta del recomendador en tu sistema de compras, o tu sistema de compras todavía no tiene un registro suyo. Reintentamos cada hora, así que esto se resuelve solo en cuanto exista su cuenta.
• waiting_for_codes: estamos esperando a que Apple genere los códigos de oferta, o a que subas más códigos promocionales de Google Play. Reintentamos cada hora.
• failed: no se pudo otorgar la recompensa, por ejemplo porque falta una clave o una configuración. Las causas más comunes son no tener configurada una clave de App Store Connect ni ofertas (así que no se puede recompensar a los recomendadores de iPhone), que falte el nombre del entitlement o del nivel de acceso, y un recomendador que ya ha recibido todas las ofertas que configuraste.
• capped: supera el límite mensual, no recompenses esta

Se envía una sola vez, cuando se registra la recomendación. Si una recompensa pendiente se otorga más tarde, no se envía un segundo webhook.

API pública

GET /public/v1/affiliates/{identifier} (el correo electrónico o el código corto del afiliado) incluye un objeto referrals con trigger (lo que cuenta tu programa), referralCount, installCount, eventCount y purchaseCount. La API pública está disponible en el plan Enterprise.

Autorrecomendaciones y límites

• Cada amigo cuenta una vez. Las instalaciones y los eventos se asocian al teléfono del amigo, así que un amigo que se registra dos veces es una sola recomendación. Las compras se asocian a la cuenta del amigo en la app (su app user ID de RevenueCat o su customer user ID de Adapty). Sin ella, cada compra se asocia por separado, así que un amigo que compra dos productos distintos puede contar dos veces.
• Una recomendación necesita un amigo que podamos identificar. Una instalación o un evento que llega sin un ID de dispositivo no se cuenta.
• Recomendarte a ti mismo no cuenta. Una instalación o un evento desde el propio teléfono del recomendador se registra, pero no se cuenta ni se recompensa. En las compras, solo podemos detectar la compra del propio recomendador cuando tu app ha enviado su app user ID (consulta más arriba) y el mismo ID llega con la compra. Sin él, un recomendador que compra en su propio teléfono se cuenta como cualquier amigo.
• Límite mensual (opcional). Desactivado de forma predeterminada. Activa Limitar recompensas por recomendador cada mes para limitar las recompensas. Las recomendaciones que superan el límite siguen sumando a su total, pero no generan recompensa ese mes.

Estadísticas del programa

La pestaña Recomendaciones en la app muestra tus recomendadores, las recomendaciones en total y este mes, las recompensas otorgadas y tus principales recomendadores.

Reglas de las tiendas

Los programas de recomendación están permitidos en App Store y Google Play. La pantalla lista para usar ya sigue estas reglas por ti:

• Compartir es opcional. Nunca bloquees una función detrás de compartir y nunca recompenses una calificación o una reseña.
• Solo el menú de compartir. La pantalla no pide acceso a los Contactos y no tiene una opción de "invitar a todos".
• Recompensa acciones reales. Recompensar compras o eventos dentro de la app es lo más seguro. Google Play vigila las apps que recompensan instalaciones.
• Tiempo premium gratis. Otórgalo mediante códigos de oferta de App Store, códigos promocionales de Google Play o un cobro de Google Play retrasado, un entitlement promocional de RevenueCat o un nivel de acceso de Adapty, en lugar de un sistema de códigos propio.
• Sin recompensas en criptomonedas por invitar a otras personas.

Conviene saber

• Los recomendadores ocupan un espacio. Cada uno cuenta para el límite de afiliados de tu plan, como cualquier afiliado. Cuando alcanzas el límite, createAffiliateForUser devuelve AFFILIATE_LIMIT_REACHED.
• Se requiere un correo electrónico para convertirse en recomendador. Es con lo que inician sesión en su panel.
• Enlaces. Cada recomendador recibe un enlace igual que cualquier afiliado nuevo: las empresas con Insert Links reciben uno generado automáticamente, las empresas con Short Code Only comparten el código, y las empresas con Branch, AppsFlyer y RevenueCat Web Purchase Link reciben el siguiente enlace de sus deep links subidos. Si se te acaban los enlaces subidos, los nuevos recomendadores pueden unirse igualmente y compartir su código, así que mantén la lista abastecida.
• Comisión. Los recomendadores reciben la comisión que elijas en Recompensas de recomendadores. Elige Sin efectivo (solo recompensas) si solo quieres dar recompensas en la app.
• Encontrarlos. Los recomendadores en la app tienen una insignia En la app en tu lista de afiliados, y puedes filtrar por cómo se unieron los afiliados.