Getting Started

Copiez un prompt de configuration avec les étapes d'installation et la guide markdown complète pour ce plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/native-purchases`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/native-purchases/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Installez le package
Fenêtre de terminal
```
bun add @capgo/native-purchases
```
Synchroniser avec les projets natifs
Fenêtre de terminal
```
bunx cap sync
```

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

Charger les produits directement des 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);
});

Mettre en œuvre les flux d'achat et 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();
```
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(). Consultez les plans de facturation mensuelle de souscription iOS pour la marche complète.
- IOS
- Android
- Créez des produits et des souscriptions en application dans App Store Connect.
- Utilisez StoreKit Local Testing ou les testeurs Sandbox pour les tests de qualité.
- Aucune modification du manifeste n'est requise. Assurez-vous que vos produits soient approuvés.
- Créez des produits et des abonnements en-ligne 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 `product.pricingTerms` expose cette option.
`quantity`	iOS	Seulement pour les achats en application, par défaut à `1`. L'Android achète toujours un article.
`appAccountToken`	iOS + Android	UUID/chaine liant l'achat à votre utilisateur. Obligatoire d'être UUID sur iOS; L'Android accepte toute chaîne chiffrée jusqu'à 64 caractères.
`isConsumable`	Android	Défini à `true` pour consommer automatiquement les jetons après avoir accordé l'entitlement pour les consommables. Par défaut à `false`.

Vérification de l'état de l'entitlement

Utiliser getPurchases() pour une vue transversale de chaque transaction 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 de la plateforme

iOSLes abonnements comprennent isActive, expirationDate, willCancelet le support de l'écouteur 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 autoritaire. purchaseState doivent ê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 StoreKit 2 ou du client de facturation, y compris les plans mensuels de facturation iOS.
restorePurchases() – réexécutez 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érez les transactions StoreKit 2 en attente lorsque votre application démarre (iOS uniquement).

Meilleures pratiques

Afficher les tarifs de l'application – Apple exige de vous afficher product.title et product.priceString; ne jamais coder directement.
Utilisez appAccountToken – générer déterminément un UUID (v5) à partir de l'ID de votre utilisateur pour lier les achats aux comptes.
Valider côté serveur – envoyer receipt (iOS) / purchaseToken (Android) à votre backend pour la vérification.
Gérer les erreurs avec élégance – vérifier les annulations de l'utilisateur, les erreurs de réseau et les environnements de facturation non pris en charge.
Testez soigneusement – suivez le guide du sandbox iOS et guide du sandbox Android.
Proposez la restauration & la gestion – ajoutez des boutons UI connectés à restorePurchases() et manageSubscriptions().

Étapes suivantes pour les revenus

Après que le flux d'achat fonctionne, utilisez le Playbook des revenus planer votre premier canal payant : portée du produit, ASO, tarification, placement de la clôture payante, analytics et feedback sur le dégonflement.

Dépannage

Les produits ne s'affichent pas

Vérifiez que l'ID de l'application / l'ID d'application correspond à la configuration de la boutique.
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 de la boutique n'est pas instantanée.

Annulation ou blocage d'achat

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

État d'abonnement incorrect

Utiliser getPurchases() pour comparer les données de magasin avec votre cache d'entitlement local.
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 Getting Started pour planifier l'approbation et la distribution du magasin, connectez-le avec Utiliser @capgo/achats-natifs pour la capacité native dans Utiliser @capgo/achats-natifs, @capgo/capacitor-avis-achat-intérieur pour le détail d'implémentation dans @capgo/capacitor-avis-achat-intérieur, Utiliser @capgo/capacitor-avis-achat-intérieur pour la capacité native dans Utiliser @capgo/capacitor-avis-achat-intérieur, @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-marché-natif.