RevenueCat Web Billing

Haz seguimiento de las comisiones de las compras web con RevenueCat Web Billing, gestionando la facturación directamente a través de la plataforma web de RevenueCat.

Cuando activas el seguimiento de RevenueCat Web Billing, puedes atribuir compras web a afiliados pasando parámetros UTM, ya sea como metadatos de la compra a través del Web SDK o como parámetros de consulta en un Web Purchase Link alojado.

Qué puedes rastrear

Una vez configurado, Insert Affiliate rastrea automáticamente:

  • Compras iniciales de suscripciones
  • Renovaciones de suscripciones
  • Compras únicas, incluidos los productos de por vida y otros productos no renovables (un NON_RENEWING_PURCHASE en RevenueCat, un pago único en Stripe)
  • Reembolsos, que revierten automáticamente la comisión del afiliado
  • Compras realizadas a través del Web SDK y a través de los Web Purchase Links alojados

Compras únicas y de por vida

Las compras únicas se rastrean, se muestran y se pagan exactamente igual que las compras de suscripciones.

La atribución de Web Billing llega a Insert Affiliate a través de Stripe Connect y no a través del webhook de RevenueCat, por lo que lo que leemos es el pago subyacente de Stripe. Un pago único se registra como una compra inicial, y tu configuración de comisiones, los totales de tu panel y tus pagos a afiliados lo tratan de la misma forma que tratan una suscripción. Un reembolso de ese pago también revierte la comisión de la misma manera.

Requisitos previos

Antes de configurar el seguimiento de Insert Affiliate, debes tener:

  • RevenueCat Web Billing configurado con Stripe
  • Stripe Connect configurado en tu panel de Insert Affiliate, usando la misma cuenta de Stripe a la que está conectado RevenueCat

Si vas a crear tu propio checkout con el Web SDK, también necesitas:

  • RevenueCat Web SDK instalado y configurado
  • Insert Affiliate SDK inicializado en tu página

Si, en cambio, vas a enviar a los clientes a un Web Purchase Link alojado, no necesitas ninguno de los dos SDK. Basta con añadir los parámetros UTM al enlace.

Configuración del webhook de RevenueCat

Importante: Al configurar tu webhook de RevenueCat para enviar eventos a Insert Affiliate, debes enviar solo eventos de App Store y Google Play Store, no eventos de Stripe ni de Web Billing.

Como Insert Affiliate recibe los eventos de Stripe directamente a través de Stripe Connect (configurado en el Paso 1 más abajo), enviar eventos del webhook de RevenueCat para transacciones de Stripe/Web Billing provocaría un seguimiento duplicado de las transacciones.

Para configurar tu webhook de RevenueCat:

  1. Ve a tu panel de RevenueCat → Project Settings → Integrations → Webhooks
  2. Al configurar el webhook de Insert Affiliate, configúralo para enviar eventos solo de:
    • App Store (iOS)
    • Google Play Store (Android)
  3. No incluyas eventos de Stripe ni de Web Billing en este webhook

Esto garantiza una atribución limpia: las transacciones móviles se rastrean mediante los webhooks de RevenueCat, mientras que las transacciones web se rastrean mediante Stripe Connect.

Guía de configuración

Paso 1: Conecta tu cuenta de Stripe mediante Stripe Connect

Como RevenueCat Web Billing usa Stripe internamente, debes conectar tu cuenta de Stripe a Insert Affiliate:

  1. Ve a Configuración → Stripe Connect en la pestaña Pagos y Cobros
  2. Haz clic en "Conectar con Stripe"
  3. Completa el proceso de incorporación de Stripe:
    • Inicia sesión en tu cuenta de Stripe existente (la misma que está conectada a RevenueCat)
    • Proporciona la información comercial requerida
    • Envía los documentos de verificación (si se solicitan)
  4. Se te redirigirá de nuevo a Insert Affiliate cuando termines

Indicadores de estado:

  • Activa: Tu cuenta de Stripe está totalmente conectada y lista
  • Restringida: Se necesita información adicional: haz clic en "Continuar incorporación"
  • Pendiente: Documentos en revisión (normalmente de 1 a 2 días hábiles)

✅ Una vez conectada tu cuenta de Stripe, Insert Affiliate recibirá automáticamente los eventos de Stripe de las transacciones de RevenueCat.

Implementación: integración del SDK

Paso 1: Instala el SDK de Insert Affiliate

Añade el SDK de Insert Affiliate a tu aplicación web:

npm install insert-affiliate-js-sdk

Paso 2: Inicializa ambos SDK

Inicializa tanto el SDK de Insert Affiliate como el RevenueCat Web SDK:

import { InsertAffiliate } from 'insert-affiliate-js-sdk';
import { Purchases } from '@revenuecat/purchases-js';

// Initialize Insert Affiliate SDK
await InsertAffiliate.initialize('your_company_code');

// Initialize RevenueCat Web SDK
const purchases = Purchases.configure('your_revenuecat_web_api_key');

Paso 3: Pasa los datos del afiliado durante la compra

Antes de realizar una compra, obtén el identificador del afiliado y el ID de la empresa, y luego pásalos como parámetros UTM en los metadatos de la compra:

// Get the current affiliate identifier and company ID
// Use ignoreTimeout: true to get the identifier even if attribution window expired
const affiliateId = await InsertAffiliate.returnInsertAffiliateIdentifier(true);
const companyId = await InsertAffiliate.returnCompanyId();

console.log('Affiliate ID:', affiliateId || 'none');
console.log('Company ID:', companyId || 'none');

// Prepare metadata with UTM parameters for RevenueCat Web Billing
const metadata: Record<string, string> = {};

if (affiliateId && affiliateId !== 'none') {
  metadata.utm_source = 'insertAffiliate';
  metadata.utm_medium = companyId || 'none';
  metadata.utm_campaign = affiliateId;
}

console.log('Purchase metadata:', JSON.stringify(metadata, null, 2));

// Get offerings and select a package
const offerings = await purchases.getOfferings();
const selectedPackage = offerings.current?.availablePackages[0];

if (!selectedPackage) {
  console.error('No packages available');
  return;
}

// Make the purchase with metadata
const { customerInfo } = await purchases.purchase({
  rcPackage: selectedPackage,
  metadata: metadata,
});

console.log('Purchase successful!');
console.log('Active entitlements:', Object.keys(customerInfo.entitlements.active));

Parámetros UTM obligatorios

Los siguientes parámetros UTM son obligatorios para una atribución correcta del afiliado:

  • utm_source: Siempre con el valor 'insertAffiliate' para identificar las conversiones de Insert Affiliate
  • utm_medium: El ID de tu empresa en Insert Affiliate
  • utm_campaign: El identificador del afiliado (código corto)

Notas importantes:

  • Llama siempre a returnInsertAffiliateIdentifier() y returnCompanyId() antes de iniciar la compra
  • Incluye los parámetros UTM en los metadatos solo si existe un identificador de afiliado
  • Los metadatos se enviarán con la compra y estarán disponibles en los eventos del webhook de RevenueCat

Si usas RevenueCat Web Purchase Links para campañas online (como email marketing, redes sociales o promociones de afiliados), debes añadir parámetros UTM para garantizar un seguimiento correcto de los afiliados.

Importante: Esto también se aplica si usas RevenueCat Paywalls en tu app móvil con un flujo de app a web. La función nativa Paywalls de RevenueCat no permite pasar metadatos personalizados en plataformas móviles, por lo que debes usar uno de estos enfoques:

  1. Redirigir a Web Purchase Links - En lugar de usar la interfaz de Paywall de RevenueCat, dirige a los usuarios a un Web Purchase Link con los parámetros UTM añadidos (enfoque recomendado)
  2. Crear un paywall personalizado - Crea tu propia interfaz de paywall que obtenga las offerings y llame directamente al método de compra con los metadatos

Cómo funciona

Los RevenueCat Web Purchase Links son páginas de pago alojadas que te permiten vender suscripciones y productos únicos sin crear tu propio flujo de checkout. Para hacer seguimiento de la atribución de afiliados, añade parámetros UTM a estos enlaces.

Esta vía no necesita ningún SDK, ni en la web ni en tu app. Sea lo que sea lo que genere el enlace, ya sea un sitio web, una app de escritorio o un email, basta con añadir los tres parámetros para la atribución. Esto la convierte en la opción más sencilla para plataformas que nuestros SDK no cubren, como una app de macOS o de escritorio.

Parámetros UTM obligatorios

  • utm_source: Siempre con el valor insertAffiliate
  • utm_medium: El ID de tu empresa en Insert Affiliate
  • utm_campaign: El código corto del afiliado

Ejemplo

Si tu RevenueCat Web Purchase Link es:

https://pay.rev.cat/sandbox/viqxbcoudyfaeaae/

Debes añadir los parámetros UTM:

?utm_source=insertAffiliate&utm_medium={insertAffiliateCompanyId}&utm_campaign={affiliateShortCode}

Ejemplo completo con parámetros

https://pay.rev.cat/sandbox/viqxbcoudyfaeaxa/?utm_source=insertAffiliate&utm_medium=12345&utm_campaign=AFF123

Donde:

  • utm_source=insertAffiliate - Identifica esto como una conversión de Insert Affiliate
  • utm_medium=12345 - El ID único de tu empresa en Insert Affiliate
  • utm_campaign=AFF123 - El código corto del afiliado

Cómo obtener el ID de tu empresa

Puedes encontrar el ID de tu empresa en Insert Affiliate en la configuración de tu panel.

Cómo obtener el identificador del afiliado

El identificador del afiliado (código corto) puede proceder de varias fuentes:

  • Deep linking: Cuando un usuario hace clic en un enlace de afiliado, captura el identificador a través de tu plataforma de deep linking
  • Código corto: Los usuarios pueden introducir o aplicar manualmente un código corto de afiliado
  • Parámetros de URL: El SDK los detecta automáticamente

Ver la documentación del JS SDK →

Plataformas de deep linking

Aunque es posible usar RevenueCat Web Purchase Links como el deep link que proporcionas a tus afiliados, no lo recomendamos, ya que hacerlo provocará que SOLO se rastreen las transacciones web, no las compras dentro de la app.

Esta limitación se debe a la forma en que los enlaces de pago de RevenueCat gestionan el paso de los parámetros utm_source, utm_medium y utm_campaign a la app al canjearlos mediante los enlaces de canje de RevenueCat.

Enfoque recomendado:

Si quieres usar RevenueCat Web Purchase Links para tus afiliados, debes:

  1. Seleccionar "Enlaces de Compra Web de RevenueCat" en la configuración de Insert Affiliate para rastrear las ventas web

    Configuración de la empresa con el desplegable Plataforma de Deep Linking establecido en Enlaces de Compra Web de RevenueCat

    Haz clic para ver a tamaño completo

  2. Implementar códigos cortos como mecanismo alternativo dentro de tu app móvil

  3. Pedir a los usuarios dentro de tu app que indiquen qué afiliado se la recomendó

  4. Aplicar la atribución de afiliado a las futuras compras dentro de la app según su respuesta

Este enfoque híbrido garantiza un seguimiento completo tanto de las compras web (mediante los parámetros UTM del Web Purchase Link) como de las compras dentro de la app (mediante códigos cortos).

Cuándo usar este enfoque:

Usa RevenueCat Web Purchase Links como tu plataforma de deep linking solo si te parece aceptable la limitación de que los enlaces de canje no atribuirán automáticamente las compras dentro de la app a los afiliados. El código corto como alternativa es esencial para mantener una atribución correcta de las transacciones móviles.

Probar tu configuración

Probar la integración del SDK

  1. Conecta tu cuenta de Stripe mediante Stripe Connect (pestaña Pagos y Cobros)
  2. Inicializa el SDK de Insert Affiliate en tu página
  3. Inicializa el RevenueCat Web SDK
  4. Realiza una compra de prueba con parámetros UTM en los metadatos
  5. Revisa tu panel de transacciones para confirmar que aparece la transacción
  1. Crea un RevenueCat Web Purchase Link
  2. Añade los parámetros UTM requeridos (utm_source, utm_medium, utm_campaign)
  3. Haz clic en el enlace y completa una compra de prueba
  4. Revisa tu panel de transacciones para verificar que la transacción está atribuida

Si vendes un producto único o de por vida, haz esta prueba específicamente con ese producto. Se atribuye a través del mismo pago de Stripe y aparece en el panel como una compra inicial.

Resolución de problemas

Las transacciones no aparecen

Revisa estos problemas comunes:

  • Estado de Stripe Connect: Verifica que tu cuenta de Stripe aparece como "Activa" en la configuración (pestaña Pagos y Cobros)
  • Parámetros UTM: Confirma que estás pasando los tres parámetros UTM obligatorios (utm_source, utm_medium, utm_campaign)
  • Inicialización del SDK: Asegúrate de que el SDK de Insert Affiliate está correctamente inicializado y devuelve valores válidos
  • Conexión de RevenueCat con Stripe: Verifica que RevenueCat Web Billing está correctamente conectado a la misma cuenta de Stripe que conectaste mediante Stripe Connect
  • Formato de los metadatos: Comprueba que los parámetros UTM se están pasando correctamente en los metadatos de la compra

El SDK no detecta al afiliado

  • Configuración del deep link: Verifica que tu plataforma de deep linking está correctamente configurada
  • Parámetros de URL: Comprueba que los enlaces de afiliado incluyen el parámetro insertAffiliate correcto
  • Momento de inicialización del SDK: Asegúrate de que el SDK se inicializa antes de que los usuarios inicien las compras
  • Ventana de atribución: Verifica que el identificador del afiliado no ha caducado (usa ignoreTimeout: true si es necesario)
  • Formato de los parámetros UTM: Asegúrate de que los parámetros UTM están correctamente codificados para URL
  • Escritura de los parámetros: Comprueba que los nombres de los parámetros están bien escritos (utm_source, utm_medium, utm_campaign)
  • ID de la empresa: Verifica que estás usando el ID de empresa correcto de Insert Affiliate
  • Código corto del afiliado: Confirma que el código corto del afiliado es válido y está activo

Qué pasa después

Una vez configurado:

  1. Las compras con metadatos UTM crean automáticamente registros de comisión
  2. Consulta todas las transacciones en tu panel
  3. Configura las tasas de comisión por afiliado
  4. Configura los métodos de pago para pagar a tus afiliados
  5. RevenueCat gestiona la facturación mientras Insert Affiliate hace seguimiento de la atribución