Getting Started

Instalación

Puede utilizar nuestra configuración asistida por IA para instalar el plugin. Agregue las Capgo habilidades a su herramienta de IA utilizando el siguiente comando:

npx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Luego utilice el siguiente prompt:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/native-purchases` plugin in my project.

Si prefiere la configuración manual, instale el plugin ejecutando los siguientes comandos y siguiendo las instrucciones específicas de la plataforma a continuación:

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. Cargue 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. Implemente 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 mensuales de iOS

   Si un suscripción de iOS admitida devuelve pricingTermspuedes mostrar una opción de facturación mensual con un compromiso de 12 meses y pasar billingPlanType: 'monthly' a purchaseProduct(). Ver planes de facturación mensuales de compromiso de iOS para el flujo completo.

   iOS
   • Crea productos y suscripciones en aplicaciones en App Store Connect.
     
   • Utiliza StoreKit Local Testing o Sandbox testers para QA.
     
   • No se requieren ediciones del manifiesto. Asegúrese de que sus productos estén aprobados.
   Android
   • Crear productos y suscripciones en la consola de Google Play.
     
   • Subir al menos una versión de prueba interna y agregar probadores de licencia.
     
   • 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 requeridas

Opción	Plataforma	Descripción
productIdentifier	iOS + Android	Código de producto/SKU configurado en App Store Connect / Google Play Console.
productType	Solo para Android	PURCHASE_TYPE.INAPP o PURCHASE_TYPE.SUBS. Por defecto es INAPP. Siempre se establece en SUBS para suscripciones.
planIdentifier	Suscripciones de Android	ID de plan base desde Google Play Console. Requerido para suscripciones, ignorado en iOS y compras in-app.
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 exposa esa opción.
quantity	iOS	Sólo para compras en la aplicación, predeterminado a 1. Android siempre compra un artículo.
appAccountToken	iOS + Android	UUID/cadena que vincula la compra a su usuario. Requerido que sea UUID en iOS; Android acepta cualquier cadena obfusca hasta 64 caracteres.
isConsumable	Android	Establecido a true para consumir tokens automáticamente después de otorgar la autorización para consumibles. Predeterminado a false.

Verificar el estado de la autorización

Usa getPurchases() para una vista transversal 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 el soporte de escucha de StoreKit 2. Los compras en la aplicación requieren la validación de la factura del servidor.
• Android: isActive/expirationDate no se rellenan; llama al desarrollador de Google Play API con el purchaseToken para el estado autoritativo. purchaseState deben ser PURCHASED y isAcknowledged debe ser true.

API referencia rápida

• isBillingSupported() – verificar la disponibilidad de StoreKit / Google Play.
• getProduct() / getProducts() – obtener el precio, título localizado, descripción, ofertas de introducción y términos de precios de iOS admitidos.
• purchaseProduct() – iniciar el flujo de compra de StoreKit 2 o cliente de facturación, incluyendo planes de facturación mensuales de compromiso de iOS.
• restorePurchases() – reproducir compras históricas y sincronizar con el dispositivo actual.
• getPurchases() – listar todas las transacciones de iOS o compras de facturación de Play.
• manageSubscriptions() – abrir la interfaz de usuario de gestión de suscripciones nativa.
• addListener('transactionUpdated') – manejar transacciones pendientes de StoreKit 2 cuando se inicia la aplicación (solo iOS).

Prácticas recomendadas

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

pasos de ingresos siguientes

Después de que el flujo de compra funciona, utilice el Plan de Ingresos Para planificar tu primer canal de pago: alcance del producto, ASO, precios, ubicación de la pantalla de pago, análisis y retroalimentación de abandono.

Solución de Problemas

Productos no cargando

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

Compra cancelada 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úrate de que las cuentas de prueba instalen la aplicación desde la Tienda de Play (ruta interna) para que la facturación funcione.
• Ver logcat/Xcode para errores de facturación al ejecutar en dispositivo.

Estado de suscripción incorrecto

• Usar getPurchases() para comparar datos de tienda con su caché de permisos locales.
• On Android, always query the Google Play Developer API with the purchaseToken con el
• para obtener fechas de vencimiento o estado de reembolso. isActive/expirationDate En iOS, verifique

y valide los recibos para detectar reembolsos o revocaciones.

Sección titulada “Siga adelante desde Getting Started” Si está utilizando el tutorial de Getting Started de Capgo, consulte la documentación de Capacitor para obtener más información sobre cómo obtener fechas de vencimiento o estado de reembolso en Android. para planificar la aprobación y distribución de la tienda, conecte 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 Usando @capgo/capacitor-mercado-nativo para la capacidad nativa en Usando @capgo/capacitor-mercado-nativo.