Crear Grupo de Suscripción iOS

Los grupos de suscripción son esenciales para organizar y gestionar múltiples niveles de suscripción en tu aplicación iOS. Comprender cómo funcionan es crucial para implementar la funcionalidad de actualización, descenso y crossgrade.

¿Qué es un Grupo de Suscripción?

Un grupo de suscripción es una colección de suscripciones relacionadas que los usuarios pueden elegir entre. Los usuarios solo pueden suscribirse a una suscripción dentro de un grupo en un momento dado. Cuando cambian de suscripción, Apple maneja la transición automáticamente.

¿Por qué los Grupos de Suscripción Importan?

Los grupos de suscripción permiten:

• Precios escalonados: Ofrecer planes básicos, premium y de alta gama
• Diferentes duraciones: Opciones mensuales, anuales y de por vida
• Lógica de actualización/descualificación: Manejo automático de cambios de suscripción
• Gestión simplificada: Agrupa las suscripciones relacionadas

Niveles de Suscripción

Dentro de un grupo, cada suscripción debe ser clasificada desde el valor más alto (nivel 1) hasta el valor más bajo. Esta clasificación determina cómo se clasifican los cambios de suscripción:

Ejemplos de Nivel

Nivel 1 (Valor más alto)

• Anual Premium ($99,99/año)
• Mensual Ultimate ($19,99/mes)

Nivel 2 (Valor medio)

• Anual Estándar ($49.99/año)
• Mensual Premium ($9.99/mes)

Nivel 3 (Valor más bajo)

• Anual Básico ($29.99/año)
• Mensual Estándar ($4.99/mes)

Tipos de cambios de suscripción

Apple gestiona automáticamente tres tipos de cambios de suscripción según la clasificación de nivel:

1. Actualización

Pasando a un nivel de suscripción más alto (por ejemplo, nivel 2 → nivel 1). Comportamiento:

Tiene efecto

• inmediatamente El usuario recibe
• un reembolso parcial por el tiempo restante La nueva suscripción comienza de inmediato
• Ejemplo:

Sección titulada “1. Actualizar”

// User currently has: Standard Monthly (Level 2)
// User upgrades to: Premium Annual (Level 1)
// Result: Immediate access to Premium, refund for unused Standard time

2. Descargar

Al moverse a un plan de nivel inferior (por ejemplo, nivel 1 → nivel 2). Comportamiento:

Entrará en vigor en la

• fecha de renovación siguiente El usuario conserva la suscripción actual hasta que finalice el período
• La nueva suscripción comienza automáticamente después de la expiración
• Ejemplo:

__CAPGO_KEEP_0__

// User currently has: Premium Annual (Level 1)
// User downgrades to: Standard Monthly (Level 2)
// Result: Premium access continues until annual renewal date, then switches

3. Actualización de nivel

Cambiar a otra suscripción a nivel de mismo nivel.

El comportamiento depende de la duración:

Duración diferente → Se comporta como descender

• Tiene efecto a la fecha de renovación siguiente
• Ejemplo: Mensual Premium (Nivel 1) → Anual Premium (Nivel 1)

Misma Duración → Actúa como actualizar

• Tiene efecto inmediato
• Ejemplo: Mensual Premium (Nivel 1) → Mensual Ultimate (Nivel 1)

Crear un Grupo de Suscripción

1. Ir a Suscripciones

   En App Store Connect, seleccione su aplicación y vaya a Monetizar > Suscripciones.

2. Crear Grupo

   Haga clic + al lado de “Grupos de Suscripción” para crear un nuevo grupo.

3. Nombre del Grupo

   Elige un nombre descriptivo que refleje las suscripciones que contiene:

   • “Acceso Premium”
   • “Planes de Almacenamiento en la Nube”
   • “Características Pro”

4. Agregar Suscripciones

   Después de crear el grupo, agrega suscripciones individuales a él. Cada suscripción tendrá un nivel de clasificación.

5. Establecer Clasificaciones de Nivel

   Arregla las suscripciones de mayor a menor valor. Considera:

   • Los planes anuales suelen tener un nivel más alto que los mensuales
   • Los niveles de precios más altos se encuentran por encima de los de precios más bajos
   • Los niveles de precios más altos se encuentran en la parte superior

Usando en tu Aplicación

El plugin native-purchases maneja automáticamente la lógica de grupos de suscripción:

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Fetch all subscriptions in a group
const { products } = await NativePurchases.getProducts({
  productIdentifiers: ['premium_monthly', 'premium_annual', 'ultimate_monthly'],
  productType: PURCHASE_TYPE.SUBS,
});

// Display current subscription using StoreKit transactions
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const activeSubs = purchases.filter((purchase) => purchase.isActive);

// Detect pending downgrade/cancellation (StoreKit sets willCancel === true)
const pendingChange = purchases.find((purchase) => purchase.willCancel === true);
if (pendingChange) {
  console.log('Subscription will stop auto-renewing on', pendingChange.expirationDate);
}

// Purchase (StoreKit handles upgrades/downgrades automatically)
await NativePurchases.purchaseProduct({
  productIdentifier: 'premium_annual',
  productType: PURCHASE_TYPE.SUBS,
});

// Listen for StoreKit updates (fires on upgrades/downgrades/refunds)
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription updated:', transaction);
});

Manejo de Cambios de Suscripción

Detectar Tipo de Cambio

import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';

// Get current subscription info
const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

const currentSubscription = purchases.find(
  (purchase) => purchase.subscriptionState === 'subscribed',
);

if (currentSubscription) {
  // StoreKit reports if user cancelled auto-renew
  if (currentSubscription.willCancel) {
    console.log(
      `User cancelled. Access remains until ${currentSubscription.expirationDate}`,
    );
  }

  if (currentSubscription.isUpgraded) {
    console.log('User recently upgraded to this plan.');
  }
}

// Listen for automatic upgrades/downgrades
NativePurchases.addListener('transactionUpdated', (transaction) => {
  console.log('Subscription changed!', transaction);
  if (transaction.subscriptionState === 'revoked') {
    revokeAccess();
  } else if (transaction.isActive) {
    unlockPremiumFeatures();
  }
});

Comunicación con el Usuario

Siempre comunica claramente el comportamiento de cambio:

For Upgrades:

“Obtendrá acceso inmediato a características Premium. Reembolsaremos su suscripción actual.”

For Downgrades:

“Mantendrá acceso Premium hasta [fecha de renovación], luego se cambiará a estándar.”

For Crossgrades:

“Su plan cambiará a facturación anual en la próxima renovación en [fecha].”

Monitoreo del servidor

Utilice las notificaciones del servidor de App Store de Apple o su propio backend de validación de recibos para reflejar los cambios de StoreKit en su base de datos. Asocie las notificaciones del servidor con el transactionUpdated escuchador para que tanto el cliente como el backend se mantengan sincronizados.

Prácticas recomendadas

Organización de Grupo

• Mantenga las suscripciones relacionadas en el mismo grupo
• No mezcle características no relacionadas (por ejemplo, almacenamiento y eliminación de anuncios)
• Crear grupos separados para diferentes conjuntos de características

Estrategia de Clasificación de Nivel

• Plan anual → Nivel superior que el mensual (para la misma categoría)
• Niveles de precios más altos → Nivel superior
• Considerar el valor, no solo el precio

Experiencia del Usuario

• Muestra la suscripción actual de manera clara
• Muestra todas las opciones disponibles en el grupo
• Indica qué cambios son inmediatos vs. a la renovación
• Permite cambiar fácilmente entre planes

Pruebas

• Prueba todos los escenarios de actualización
• Prueba todos los escenarios de descenso
• Verifica el comportamiento de crossgrade
• Verifica que se dispare el webhook

Escenarios comunes

Escenario 1: Planes mensuales de tres niveles

Level 1: Ultimate Monthly ($19.99)
Level 2: Premium Monthly ($9.99)
Level 3: Basic Monthly ($4.99)

• Básico → Premium: Actualizar (inmediato)
• Premium → Ultimate: Actualizar (inmediato)
• Ultimate → Premium: Descargar (a la renovación)
• Básico → Ultimate: Actualizar (inmediato)

Escenario 2: Planes de duración mixta

Level 1: Premium Annual ($99.99/year)
Level 2: Premium Monthly ($9.99/month)

• Mensual → Anual: Cambiar de plan (a la renovación)
• Anual → Mensual: Descargar (a la renovación)

Escenario 3: Multi-Tier Multi-Duración

Level 1: Ultimate Annual ($199/year)
Level 2: Ultimate Monthly ($19.99/month)
Level 3: Premium Annual ($99/year)
Level 4: Premium Monthly ($9.99/month)
Level 5: Basic Annual ($49/year)
Level 6: Basic Monthly ($4.99/month)

Esta configuración proporciona la máxima flexibilidad mientras mantiene una lógica de actualización/desactualización clara.

Solución de problemas

No se muestra la suscripción en el grupo:

• Verifique que esté asignado al grupo correcto
• Compruebe que esté en al menos el estado “Listo para enviar”
• Asegúrese de que el ID del producto sea correcto

Comportamiento de actualización/desactualización incorrecto:

• Revisar las clasificaciones de nivel (1 = más alto)
• Verificar que los niveles de suscripción tengan sentido
• Compruebe que los niveles estén configurados correctamente

Productos de diferentes grupos:

• Los usuarios pueden suscribirse a múltiples grupos simultáneamente
• Esto es intencional - mantenga los productos relacionados en el mismo grupo

getActiveProducts mostrando múltiples suscripciones:

• Compruebe si las suscripciones están en diferentes grupos
• Verifique que el usuario no esté suscrito a través de Family Sharing
• Revisar el estado de la suscripción en App Store Connect

Recursos adicionales

Para obtener más detalles, consulte la documentación oficial de Apple sobre grupos de suscripción.

Sigue adelante desde Crear Grupo de Suscripción de iOS

Si estás utilizando Crear Grupo de Suscripción de iOS para planificar la aprobación y distribución de la tienda, conecta con Usando @capgo/native-purchases para la capacidad nativa en Usando @capgo/native-purchases, @capgo/capacitor-revisión-en-la-aplicación para el detalle de implementación en @capgo/capacitor-revisión-en-la-aplicación, Usando @capgo/capacitor-revisión-en-la-aplicación para la capacidad nativa en Usando @capgo/capacitor-revisión-en-la-aplicación, @capgo/capacitor-mercado nativo para el detalle de implementación en @capgo/capacitor-mercado nativo, y Utilizando @capgo/capacitor-mercado nativo para la capacidad nativa en Utilizando @capgo/capacitor-mercado nativo.