Inicio

Título de la sección “Instalación”

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

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

Instalación

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 mensual de compromiso de iOS para el flujo completo.

   iOS
   • Crear productos y suscripciones en la App Store Connect.
     
   • Usar StoreKit Local Testing o Sandbox testers para pruebas de QA.
     
   • No se requieren ediciones del manifiesto. Asegúrese de que sus productos estén aprobados.
   Android
   • Crear productos y suscripciones en el Google Play Console.
     
   • 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	ID de producto configurado en App Store Connect / Google Play Console.
productType	Solo para Android	PURCHASE_TYPE.INAPP o PURCHASE_TYPE.SUBSo INAPPpor defecto SUBS siempre configurado como
planIdentifier	para suscripciones.	Suscripciones de Android
billingPlanType	suscripciones de iOS	plan de facturación de StoreKit para realizar una compra. Utilice 'monthly' para facturación mensual con un compromiso de 12 meses cuando product.pricingTerms exponga esa opción.
quantity	iOS	Solo para compras en la aplicación, por defecto se utiliza 1Android siempre compra un artículo.
appAccountToken	iOS + Android	ID de dispositivo UUID/cadena que vincula la compra a su usuario. Es obligatorio que sea UUID en iOS; Android acepta cualquier cadena obfusca hasta 64 caracteres.
isConsumable	Android	Establezca a true para consumir tokens automáticamente después de conceder la autorización para consumibles. Por defecto se utiliza false.

Verificar el estado de la licencia

Usar getPurchases() para una vista cruzada de todas las transacciones 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, willCancel, y soporte de escucha de StoreKit 2. Las compras en la aplicación requieren validación de recibos del servidor.
• Androide: isActive/expirationDate no se poblaron; llame al desarrollador de Google Play API con el purchaseToken para obtener el estatus autoritativo. purchaseState debe ser PURCHASED y isAcknowledged debe ser true.

API referencia rápida

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

Prácticas recomendadas

1. Mostrar precios de la tienda – Apple requiere mostrar product.title y product.priceString; nunca codifique directamente.
2. Usar appAccountToken – genere de manera determinista un UUID (v5) a partir de su ID de usuario para vincular compras a cuentas.
3. Validar en el lado del servidor – enviar receipt (iOS) / purchaseToken (Android) a su servidor backend para su 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. Pruebe exhaustivamente – siga las instrucciones del guía de pruebas de iOS y guía de pruebas de Android.
6. Ofrezca restauración y gestión – agregue 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 recaudación de ingresos para planificar su primer canal de pago: alcance del producto, SEO, precios, ubicación de la pared de pago, análisis y retroalimentación de la tasa de rotura.

Resolución de problemas

Sección titulada “Resolución de problemas”

• Productos no 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 varios horas después de crear productos; la propagación de la tienda no es instantánea.

• Compra cancelada o atascada en el proceso de pago de la tienda de aplicaciones o Google Play Store. Los usuarios pueden cancelar en cualquier momento durante el proceso de pago. Para evitar esto, envuelva las llamadas en un bloque de código que maneje los errores y la cancelación de la compra. Por ejemplo, puedes utilizar un bloque de código que maneje los errores y la cancelación de la compra, como el siguiente ejemplo: `try { // código que realiza la compra } catch (error) { // maneja el error } finally { // maneja la cancelación de la compra }` try/catch y mensajes de error amigables para la superficie.
• Para Android, asegúrese de que las cuentas de prueba instalen la aplicación desde la Tienda de Play (pista interna) para que Billing funcione.
• Verifique logcat/Xcode para errores de facturación cuando se ejecuta en un dispositivo.

Estado de la suscripción incorrecto

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

Siga adelante desde Inicio

If estás utilizando Getting Started 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-mercado-nativo, y Usando @capgo/capacitor-mercado-nativo para la capacidad nativa en Using @capgo/capacitor-native-market.