Getting Started

1. Instale el paquete

   bun add @capgo/native-purchases

2. Sincronice con proyectos nativos

   bunx cap sync

3. Verifique el soporte de facturación

   import { NativePurchases } from '@capgo/native-purchases';
   
   const { isBillingSupported } = await NativePurchases.isBillingSupported();
   if (!isBillingSupported) {
     throw new Error('Billing is not available on this device');
   }

4. Cargar productos directamente desde las tiendas

   import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
   
   const { products } = await NativePurchases.getProducts({
     productIdentifiers: [
       'com.example.premium.monthly',
       'com.example.premium.yearly',
       'com.example.one_time_unlock'
     ],
     productType: PURCHASE_TYPE.SUBS, // Use PURCHASE_TYPE.INAPP for one‑time products
   });
   
   products.forEach((product) => {
     console.log(product.title, product.priceString);
   });

5. Implementar flujos de compra y restauración

   import { NativePurchases, PURCHASE_TYPE } from '@capgo/native-purchases';
   
   const monthlyPlanId = 'monthly-plan'; // Base Plan ID from Google Play Console
   
   const transaction = await NativePurchases.purchaseProduct({
     productIdentifier: 'com.example.premium.monthly',
     planIdentifier: monthlyPlanId,        // REQUIRED for Android subscriptions, ignored on iOS
     productType: PURCHASE_TYPE.SUBS,
     quantity: 1,
   });
   
   console.log('Transaction ID', transaction.transactionId);
   
   await NativePurchases.restorePurchases();

   Planes de compromiso mensual de iOS

   Si un suscripción de iOS compatible devuelve pricingTerms, puedes mostrar una opción de facturación mensual con un compromiso de 12 meses y pasar billingPlanType: 'monthly' a purchaseProduct(). Consulta los planes de facturación mensual de compromiso de iOS para el flujo completo.

   iOS
   • Crea productos y suscripciones en la tienda en App Store Connect.
     
   • Utiliza StoreKit Local Testing o Sandbox testers para pruebas de QA.
     
   • No se requieren ediciones en el manifiesto. Asegúrate de que tus productos estén aprobados.
   Android
   • Crea productos y suscripciones en Google Play Console.
     
   • Sube al menos una versión de prueba interna y agrega licenciatarios de prueba.
     
   • Agregar la permiso de facturación a AndroidManifest.xml:

   <uses-permission android:name="com.android.vending.BILLING" />

Ejemplo de servicio de compra

import { NativePurchases, PURCHASE_TYPE, Transaction } from '@capgo/native-purchases';
import { Capacitor } from '@capacitor/core';

class PurchaseService {
  private premiumProduct = 'com.example.premium.unlock';
  private monthlySubId = 'com.example.premium.monthly';
  private monthlyPlanId = 'monthly-plan'; // Base Plan ID (Android only)

  async initialize() {
    const { isBillingSupported } = await NativePurchases.isBillingSupported();
    if (!isBillingSupported) throw new Error('Billing unavailable');

    const { products } = await NativePurchases.getProducts({
      productIdentifiers: [this.premiumProduct, this.monthlySubId],
      productType: PURCHASE_TYPE.SUBS,
    });

    console.log('Loaded products', products);

    if (Capacitor.getPlatform() === 'ios') {
      NativePurchases.addListener('transactionUpdated', (transaction) => {
        this.handleTransaction(transaction);
      });
    }
  }

  async buyPremium(appAccountToken?: string) {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: this.premiumProduct,
      productType: PURCHASE_TYPE.INAPP,
      appAccountToken,
    });

    await this.processTransaction(transaction);
  }

  async buyMonthly(appAccountToken?: string) {
    const transaction = await NativePurchases.purchaseProduct({
      productIdentifier: this.monthlySubId,
      planIdentifier: this.monthlyPlanId, // REQUIRED for Android subscriptions
      productType: PURCHASE_TYPE.SUBS,
      appAccountToken,
    });

    await this.processTransaction(transaction);
  }

  async restore() {
    await NativePurchases.restorePurchases();
    await this.refreshEntitlements();
  }

  async openManageSubscriptions() {
    await NativePurchases.manageSubscriptions();
  }

  private async processTransaction(transaction: Transaction) {
    this.unlockContent(transaction.productIdentifier);
    this.validateOnServer(transaction).catch(console.error);
  }

  private unlockContent(productIdentifier: string) {
    // persist entitlement locally
    console.log('Unlocked', productIdentifier);
  }

  private async refreshEntitlements() {
    const { purchases } = await NativePurchases.getPurchases({
      productType: PURCHASE_TYPE.SUBS,
    });
    console.log('Current purchases', purchases);
  }

  private async handleTransaction(transaction: Transaction) {
    console.log('StoreKit transaction update:', transaction);
    await this.processTransaction(transaction);
  }

  private async validateOnServer(transaction: Transaction) {
    await fetch('/api/validate-purchase', {
      method: 'POST',
      body: JSON.stringify({
        transactionId: transaction.transactionId,
        receipt: transaction.receipt,
        purchaseToken: transaction.purchaseToken,
      }),
    });
  }
}

Opciones de compra obligatorias

Opción	Plataforma	Descripción
productIdentifier	iOS + Android	SKU/ID de producto configurado en App Store Connect / Google Play Console.
productType	Solo para Android	PURCHASE_TYPE.INAPP o PURCHASE_TYPE.SUBSPor defecto es INAPPSiempre configurado como SUBS para suscripciones.
planIdentifier	Suscripciones de Android	ID de plan base desde el Console de Google Play. Requerido para suscripciones, ignorado en iOS y compras en aplicación.
billingPlanType	Suscripciones de iOS	Plan de facturación de StoreKit para comprar. Utilice 'monthly' para facturación mensual con un compromiso de 12 meses cuando product.pricingTerms exponga esa opción.
quantity	iOS	Sólo para compras en aplicación, predeterminado a 1. Android siempre compra un artículo.
appAccountToken	iOS + Android	UUID/cadena que enlaza la compra con su usuario. Requerido que sea UUID en iOS; Android acepta cualquier cadena obfusca hasta 64 caracteres.
isConsumable	Android	Establecer en true para consumir tokens automáticamente después de conceder permisos para consumibles. Por defecto es false.

Verificando el estado de permiso

Usar getPurchases() para una vista cruzada de cada transacción que los almacenes informan:

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

const { purchases } = await NativePurchases.getPurchases({
  productType: PURCHASE_TYPE.SUBS,
});

purchases.forEach((purchase) => {
  if (purchase.isActive && purchase.expirationDate) {
    console.log('iOS sub active until', purchase.expirationDate);
  }

  const isAndroidIapValid =
    ['PURCHASED', '1'].includes(purchase.purchaseState ?? '') && purchase.isAcknowledged;

  if (isAndroidIapValid) {
    console.log('Grant in-app entitlement for', purchase.productIdentifier);
  }
});

Comportamiento de la plataforma

• iOS: Las suscripciones incluyen isActive, expirationDate, willCancel, y soporte para escuchas de StoreKit 2. Las compras en la aplicación requieren validación de recibos del servidor.
• Android: isActive/expirationDate no se rellenan; llama al desarrollador de Google Play API con el purchaseToken para obtener el estado autoritativo. purchaseState deben ser PURCHASED y isAcknowledged deben ser true.

API referencia rápida

• isBillingSupported() – verifica la disponibilidad de StoreKit / Google Play.
• getProduct() / getProducts() – obtén el precio, título localizado, descripción, ofertas de introducción y términos de precios de iOS admitidos.
• purchaseProduct() – inicia el flujo de compra de StoreKit 2 o del cliente de facturación, incluidos los planes de facturación mensuales de iOS.
• restorePurchases() – repite las compras históricas y sincroniza con el dispositivo actual.
• getPurchases() – lista todas las transacciones de iOS o compras de Play Billing.
• manageSubscriptions() – abre la interfaz de usuario de gestión de suscripciones nativa.
• addListener('transactionUpdated') – gestione las transacciones pendientes de StoreKit 2 cuando su aplicación inicie (solo para iOS).

Consejos para una buena práctica

1. Mostrar precios de tienda – Apple requiere mostrar product.title y product.priceString; nunca codifique de forma rígida.
2. Utilice appAccountToken – genere de forma determinista un UUID (v5) a partir del ID de usuario para vincular compras a cuentas.
3. Validar en el lado del servidor – envíe receipt (iOS) / purchaseToken (Android) a su servidor de backend para verificar.
4. Maneje errores con amabilidad – compruebe las cancelaciones de usuario, las fallas de red y los entornos de facturación no admitidos.
5. Pruebe exhaustivamente – siga las guías de pruebas de iOS sandbox y guías de pruebas de Android sandbox.
6. Ofrezca restauración & gestión – agregue botones de interfaz de usuario conectados a restorePurchases() y manageSubscriptions().

Pasos siguientes para la recaudación de ingresos

Después de que el flujo de compra funciona, utilice el Libro de estrategias de recaudación de ingresos para planificar su primer canal de pago: alcance del producto, ASO, precios, ubicación de la pared de pago, análisis y retroalimentación de abandono.

Solución de problemas

Los productos no se cargan

• Asegúrese de que el ID de paquete / ID de aplicación coincida con la configuración de la tienda.
• Confirme que los IDs de producto estén activos y aprobados (Tienda de App) o activados (Google Play).
• Espera varias horas después de crear productos; la propagación de la tienda no es instantánea.

Cancelación de compra o atascada

• Los usuarios pueden cancelar en medio del flujo; envuelve las llamadas en try/catch y muestra mensajes de error amigables.
• Para Android, asegúrese de que las cuentas de prueba instalen la aplicación desde la Tienda de aplicaciones (pista interna) para que la facturación funcione.
• Verifique logcat/Xcode para errores de facturación al ejecutar en dispositivo.

Estado de suscripción incorrecto

• Utilice getPurchases() para comparar los datos de la tienda con su caché de derechos locales.
• On Android, always query the Google Play Developer API with the purchaseToken con el
• para obtener fechas de vencimiento o estado de devolución. isActive/expirationDate En iOS, verifique y valide los recibos para detectar devoluciones o revocaciones.

Sigue adelante desde Inicio rápido

Si estás utilizando Inicio rápido para planificar la aprobación y distribución de la tienda, conecta con Usando @capgo/compras-nativas para la capacidad nativa en Usando @capgo/compras-nativas, @capgo/capacitor-revisión-en-aplicación para el detalle de implementación en @capgo/capacitor-revisión-en-aplicación, Usando @capgo/capacitor-revisión-en-aplicación para la capacidad nativa en Usando @capgo/capacitor-revisión-en-aplicación, @capgo/capacitor-mercado-nativo para el detalle de implementación en @capgo/capacitor-native-market, y Usando @capgo/capacitor-native-market para la capacidad nativa en Usando @capgo/capacitor-native-market.