Démarrage

Installation

Vous pouvez utiliser notre configuration assistée par l'IA pour installer le plugin. Ajoutez les compétences Capgo à votre outil IA à l'aide de la commande suivante :

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

Ensuite, utilisez la prompt suivante :

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

Si vous préférez une configuration manuelle, installez le plugin en exécutant les commandes suivantes et suivez les instructions spécifiques à la plateforme ci-dessous :

1. Installer le package

   bun add @capgo/native-purchases

2. Synchroniser avec les projets natifs

   bunx cap sync

3. Vérifier le support facturation

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

4. Charger les produits directement depuis les magasins

   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. Implémentez les flux d'achat & de restauration

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

   Plans de engagement mensuels iOS

   Si une souscription iOS prise en charge renvoie pricingTerms vous pouvez afficher une option de facturation mensuelle avec un engagement de 12 mois et passer billingPlanType: 'monthly' à purchaseProduct(). Voir Plans de facturation mensuelle de l'engagement iOS pour la marche à suivre complète.

   iOS
   • Créez des produits et des abonnements en app dans App Store Connect.
     
   • Utilisez StoreKit Local Testing ou Sandbox testers pour les tests de Q&A.
     
   • Aucune modification du manifeste n'est requise. Assurez-vous que vos produits soient approuvés.
   Android
   • Créez des produits et des abonnements en app dans Google Play Console.
     
   • Téléchargez au moins une version de test interne et ajoutez des testeurs de licence.
     
   • Ajoutez la permission de facturation à AndroidManifest.xml:

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

Exemple de service d'achat

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

Options d'achat requises

Option	Plateforme	Description
productIdentifier	iOS + Android	Le SKU/ID de produit configuré dans App Store Connect / Google Play Console.
productType	Seulement Android	PURCHASE_TYPE.INAPP ou PURCHASE_TYPE.SUBS. Par défaut à INAPP. Toujours défini à SUBS pour les abonnements.
planIdentifier	Abonnements Android	ID de plan de base depuis Google Play Console. Obligatoire pour les abonnements, ignoré sur iOS et pour les achats en application.
billingPlanType	abonnements iOS	Plan de facturation StoreKit pour l'achat. Utilisez 'monthly' pour un facturation mensuelle avec un engagement de 12 mois lorsque product.pricingTerms expose cette option.
quantity	iOS	Seul pour les achats en application, par défaut à 1. Android achète toujours un article.
appAccountToken	iOS + Android	Identifiant UUID/chaine liant l'achat à votre utilisateur. Obligatoire d'être UUID sur iOS ; Android accepte toute chaîne chiffrée jusqu'à 64 caractères.
isConsumable	Android	Fixé à true pour consommer automatiquement les jetons après avoir accordé l'entitlement pour les consommables. Par défaut à false.

État de la titularisation

Utiliser getPurchases() pour une vue croisée de toutes les transactions que les magasins signalent :

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

Comportement du plateau

• iOS: Les abonnements incluent isActive, expirationDate, willCancel, et la prise en charge du listener StoreKit 2. Les achats en application nécessitent la validation du reçu de serveur.
• Android: isActive/expirationDate ne sont pas remplis ; appelez le développeur Google Play API avec le purchaseToken pour un statut d'autorité. purchaseState doit être PURCHASED et isAcknowledged doit être true.

API référence rapide

• isBillingSupported() – vérifiez la disponibilité de StoreKit / Google Play.
• getProduct() / getProducts() – récupérez le prix, le titre localisé, la description, les offres d'introduction et les termes de tarification iOS pris en charge.
• purchaseProduct() – initiez la procédure d'achat de StoreKit 2 ou du client de facturation, y compris les plans mensuels de facturation iOS.
• restorePurchases() – répliquez les achats historiques et synchronisez-les avec le dispositif actuel.
• getPurchases() – affichez toutes les transactions iOS ou les achats de facturation Play.
• manageSubscriptions() – ouvrez l'interface utilisateur de gestion des abonnements natives.
• addListener('transactionUpdated') Gérer les transactions StoreKit 2 en attente lors du démarrage de votre application (iOS uniquement).

Meilleures pratiques

1. Afficher les prix de l'application Gérer les transactions StoreKit 2 en attente lors du démarrage de votre application (iOS uniquement). product.title Apple exige de vous afficher product.priceStringet
2. ; ne jamais les coder en dur. appAccountToken Utilisez
3. Générez un UUID (v5) de manière déterministe à partir de l'ID de votre utilisateur pour lier les achats aux comptes. Valider côté serveur receipt Envoyez (iOS) / purchaseToken (Android) à votre backend pour vérification.
4. Gérer les erreurs avec élégance – vérifiez les annulations de l'utilisateur, les échecs de réseau et les environnements de facturation non pris en charge.
5. Testez soigneusement – suivez le guide de sandbox iOS et guide de sandbox Android.
6. Proposez la restauration et la gestion – ajoutez des boutons de l'interface utilisateur connectés à restorePurchases() et manageSubscriptions().

Étapes de revenus suivantes

Après que le flux de vente fonctionne, utilisez le Guide du chiffre d’affaires pour planifier votre premier canal payant : portée du produit, ASO, tarification, placement de la barrière de paiement, analytics et feedback sur le taux de dérive.

Résolution des problèmes

Produits non chargés

• Assurez-vous que l'ID de l'ensemble / l'ID d'application correspond à la configuration de l'application.
• Confirmez que les ID de produits sont actifs et approuvés (App Store) ou activés (Google Play).
• Attendez plusieurs heures après avoir créé des produits ; la propagation du magasin n'est pas instantanée.

Annulation ou blocage de la vente

• Les utilisateurs peuvent annuler en cours de flux ; enveloppez les appels dans try/catch et messages d'erreur amicaux pour la surface.
• Pour Android, assurez-vous que les comptes de test installent l'application depuis Google Play Store (piste interne) afin que la facturation fonctionne.
• Vérifiez logcat/Xcode pour les erreurs de facturation lors de l'exécution sur appareil.

L'état de l'abonnement est incorrect

• Utilisez getPurchases() pour comparer les données de magasin avec votre cache de droits locaux.
• On Android, always query the Google Play Developer API with the purchaseToken pour obtenir les dates d'expiration ou l'état de remboursement.
• Sur iOS, vérifiez isActive/expirationDate et validez les reçus pour détecter les remboursements ou les révocations.

Continuez de Getting Started

Si vous utilisez Démarrage pour planifier l'approbation et la distribution de l'application, connectez-le avec Utiliser @capgo/native-purchases pour la capacité native dans Utiliser @capgo/native-purchases, @capgo/capacitor-examen-en-ligne pour le détail d'implémentation dans @capgo/capacitor-examen-en-ligne, Utiliser @capgo/capacitor-examen-en-ligne pour la capacité native dans Utiliser @capgo/capacitor-examen-en-ligne, @capgo/capacitor-marché-natif pour le détail d'implémentation dans @capgo/capacitor-marché-natif, et Utiliser @capgo/capacitor-marché-natif pour la capacité native dans Utiliser @capgo/capacitor-native-market.