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 utiliza el siguiente prompt:

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

Si prefieres la configuración manual, instala el complemento ejecutando los siguientes comandos y sigue las instrucciones específicas de la plataforma a continuación:

1. Instalar el paquete

   bun add @capgo/native-purchases

2. Sincronizar con proyectos nativos

   bunx cap sync

3. Verificar 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 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(). Consulte Planes de facturación mensuales de compromiso de iOS para el flujo completo.

   iOS
   • Crear productos y suscripciones en la tienda en App Store Connect.
     
   • Utilice 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 Google Play Console.
     
   • Cargar al menos una versión de prueba interna y agregar 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 requeridas

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.SUBSDefaults a } INAPP. Por defecto SUBS . Siempre establecido en
planIdentifier	para suscripciones	ID de Plan Base desde la Consola 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 compras. Utilice 'monthly' Plan de facturación de StoreKit para la compra. Utilice product.pricingTerms exposa esa opción.
quantity	iOS	Solo para compras en la aplicación, predeterminado a 1. Compra siempre un item en Android.
appAccountToken	iOS + Android	UUID/cadena que vincula la compra a su usuario. Requerido ser UUID en iOS; Android acepta cualquier cadena obfusca hasta 64 chars.
isConsumable	Android	Establecido a true para consumir tokens automáticamente después de otorgar acceso a consumibles. Predeterminado a false.

Verificar estado de acceso

Usar getPurchases() para una vista cruz- plataforma de cada transacción que los tiendas 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, willCancely soporte para escuchas de StoreKit 2. Los pagos en la aplicación requieren la validación de recibos del servidor.
• Android: isActive/expirationDate no se rellenan; llame al desarrollador de Google Play API con el purchaseToken para obtener el estado autoritativo. purchaseState deben PURCHASED y isAcknowledged deben true.

API referencia rápida

• isBillingSupported() – verificar la disponibilidad de StoreKit / Google Play.
• getProduct() / getProducts() – obtener 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 Billing, incluyendo planes de facturación mensuales de iOS.
• restorePurchases() – reproducir compras históricas y sincronizar con el dispositivo actual.
• getPurchases() – listar todas las transacciones de iOS o compras de Play Billing.
• manageSubscriptions() abre la interfaz de gestión de suscripciones nativas.
• 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; no codifique nunca.
2. Usar appAccountToken – genere un UUID (v5) determinísticamente a partir de su ID de usuario para vincular compras a cuentas.
3. Validar en el servidor – enviar receipt (iOS) / purchaseToken (Android) a su servidor de backend para la verificación.
4. Manejar errores con amabilidad – verificar cancelaciones de usuario, fallos de red y entornos de facturación no compatibles.
5. Probar exhaustivamente – seguir los Guía de sandbox de iOS y Guía del entorno de pruebas de Android.
6. Gestión de ofertas y restauración – agregar botones de interfaz de usuario conectados a restorePurchases() y manageSubscriptions().

Pasos siguientes de ingresos

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

Ayuda con 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 (App Store) o activados (Google Play).
• Espera varias horas después de crear productos; la propagación de almacenamiento no es instantánea.

Comprado cancelado o atascado

• Users can cancel mid-flow; wrap calls in try/catch y muestre mensajes de error amigables.
• Para Android, asegúrese de que las cuentas de prueba instalen la aplicación desde la tienda Play (carril interno) para que la facturación funcione.
• Verifique logcat/Xcode para errores de facturación al ejecutar en dispositivo.

Estado de la suscripción incorrecto

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

Siga adelante desde Inicio

Si está utilizando Getting Started para planificar la aprobación de la tienda y la distribución, 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