Crear Grupo de Suscripción iOS

Los grupos de suscripción son fundamentales 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, desactualización 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 gestiona la transición automáticamente.

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

Los grupos de suscripción permiten:

• Precios escalonados: Ofrecer planes básico, premium y ultimate
• 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: Agrupar 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 niveles

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 maneja automáticamente tres tipos de cambios de suscripción según el nivel de clasificación:

1. Actualización

Cambiar a un plan de suscripción de mayor nivel (por ejemplo, nivel 2 → nivel 1). Comportamiento:

Tiene efecto

• inmediatamente __CAPGO_KEEP_0__
• El usuario recibe una devolución parcial por el tiempo restante
• La nueva suscripción comienza de inmediato

Ejemplo:

// 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. Descender

Al cambiar a una suscripción de nivel inferior (por ejemplo, nivel 1 → nivel 2). Comportamiento:

__CAPGO_KEEP_0__

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

Ejemplo:

// 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. Crossgrade

Cambiar a otra suscripción en el mismo nivel de tarifa.

El comportamiento depende de la duración:

Duración diferente → Actúa como descender

• Tiene efecto a la fecha de renovación siguiente
• Ejemplo: Suscripción mensual (Nivel 1) → Suscripción anual (Nivel 1)

Duración igual → Actúa como ascender

• Tiene efecto inmediatamente
• Ejemplo: Suscripción Premium mensual (Nivel 1) → Suscripción Ultimate mensual (Nivel 1)

Crear un Grupo de Suscripciones

1. Ir a Suscripciones

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

2. Crear Grupo

   Haga clic + al lado de “Grupos de Suscripciones” para crear un nuevo grupo.

3. Denomine al 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, agregue suscripciones individuales a él. Cada suscripción tendrá un nivel de clasificación.

5. Establecer Clasificaciones de Nivel

   Organizar las suscripciones desde el valor más alto (1) hasta el valor más bajo. Considera:

   • Los planes anuales suelen tener un ranking más alto que los mensuales
   • Los niveles de precios más altos se colocan por encima de los de precios más bajos
   • Los niveles de precios máximos/premiados tienen el ranking más alto

Usar en Tu Aplicación

El plugin de compras nativas maneja automáticamente la lógica de grupos de suscripciones:

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);
});

Gestionar 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:

Para actualizaciones:

“You’ll get immediate access to Premium features. We’ll prorate your current subscription.”

Para descargas:

“You’ll keep Premium access until [renewal date], then switch to Standard.”

Para cambios de categoría:

“Your plan will change to Annual billing at the next renewal on [date].”

Monitoreo del servidor

Utilice las notificaciones del servidor de Apple Store v2 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 "listener" para que tanto el cliente como el backend se mantengan sincronizados. transactionUpdated Prácticas recomendadas

Sección titulada “Prácticas recomendadas”

Sección titulada “Organización de grupos”

• No mezcle características no relacionadas (por ejemplo, almacenamiento y eliminación de anuncios)
• Cree grupos separados para diferentes conjuntos de características
• Estrategia de clasificación de niveles

Sección titulada “Estrategia de clasificación de niveles”

• Planes anuales → Nivel superior que los mensuales (para la misma categora)
• Niveles de precio más altos → Nivel superior
• Considerar el valor, no solo el precio

Experiencia del usuario

• Mostrar la suscripción actual claramente
• Mostrar todas las opciones disponibles en el grupo
• Indicar qué cambios son inmediatos vs. a la renovación
• Permitir cambiar fácilmente entre planes

Pruebas

• Probar todos los escenarios de actualización
• Prueba todos los escenarios de descarga
• Verificar el comportamiento de crossgrade
• Comprueba 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 (en 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: Cambio de categoría (en renovación)
• Anual → Mensual: Descalificar (en renovación)

Escenario 3: Multi-Nivel 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/descalificación clara.

Solución de problemas

Suscripción no aparece en el grupo:

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

Comportamiento de actualización/descualificación incorrecto:

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

Productos de diferentes grupos:

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

getActiveProducts muestra múltiples suscripciones:

• Comprueba si las suscripciones están en diferentes grupos
• Verifique que el usuario no está suscrito a través de la Compartición Familiar
• 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.

Siga adelante desde Crear Grupo de Suscripción iOS

Si está utilizando Crear Grupo de Suscripción iOS para planificar la aprobación y la distribución de la tienda, conéctelo con Usando @capgo/native-purchases para la capacidad nativa en Usando @capgo/native-purchases, @capgo/capacitor-in-app-review para el detalle de implementación en @capgo/capacitor-in-app-review, Usando @capgo/capacitor-in-app-review para la capacidad nativa en Usando @capgo/capacitor-in-app-review, @capgo/native-market para el detalle de implementación en @capgo/native-market, y Usando @capgo/native-market para la capacidad nativa en Usando @capgo/native-market.