Native PurchasesのGetting Started

インストール

CapgoのAI-Assistedセットアップを使用してプラグインをインストールできます。AIツールにCapgoスキルを追加するには、以下のコマンドを使用してください。

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

次のプロンプトを使用してください。

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

手動設定を選択する場合は、以下のコマンドを実行してプラグインをインストールし、下記のプラットフォーム固有の手順に従ってください。

1. パッケージをインストール

   bun add @capgo/native-purchases

2. ネイティブプロジェクトと同期

   bunx cap sync

3. 請求サポートを確認

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

4. ストアから直接製品を読み込む

   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. 購入と復元フローを実装する

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

   iOS 月額コミットメントプラン

   サポートされるiOSサブスクリプションが返された場合 pricingTerms, 12 か月のコミットメントとともに月額請求オプションを表示し、 billingPlanType: 'monthly' を purchaseProduct()。 以下の iOS 月額コミットメント請求プラン を参照してください。

   iOS
   • App内商品とサブスクリプションを作成する
     
   • StoreKit Local TestingまたはSandboxテスターを使用してQAを行う
     
   • マニフェストの編集は必要ない。商品が承認されていることを確認する
   Android
   • Google Play ConsoleでApp内商品とサブスクリプションを作成する
     
   • 内部テストビルドをアップロードし、ライセンステスターを追加する
     
   • 課金許可を追加する AndroidManifest.xml:

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

購入サービス例

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

必要な購入オプション

オプション	プラットフォーム	説明
productIdentifier	iOS + Android	App Store Connect / Google Play Console での SKU / 商品 ID
productType	Android 限定	PURCHASE_TYPE.INAPP または PURCHASE_TYPE.SUBSまたは INAPP。デフォルトは SUBS 。常に
planIdentifier	サブスクリプション用	Android サブスクリプション用
billingPlanType	iOS サブスクリプション	StoreKit の課金プランを購入に使用します。 'monthly' 月額課金に 12 か月のコミットメントを設定する場合に使用します。 product.pricingTerms iOS
quantity	iOS のみのインアプリ購入に使用します。デフォルトは	。Android は常に 1 つのアイテムを購入します。 1iOS と Android
appAccountToken	iOS	購入をユーザーにリンクするための UUID/文字列です。iOS では必須の UUID です。Android は 64 文字までのオブfuscate された文字列を受け入れます。
isConsumable	Android	を設定すると、消耗可能なアイテムの特権を付与した後、自動的にトークンを消費します。デフォルトは true です。 false.

有効性の確認状態をチェックする

使用 getPurchases() クロスプラットフォームで、すべての取引を表示するために店舗が報告する:

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

プラットフォームの動作

• iOS: サブスクリプションには isActive, expirationDate, willCancel, および StoreKit 2 リスナーサポート。アプリ内購入にはサーバー受領票の検証が必要です。
• Android: isActive/expirationDate は埋められていません。Google Play Developer API を呼び出して、 purchaseToken for 認可状態. purchaseState は必要です. PURCHASED と isAcknowledged は必要です. true.

API クイック リファレンス

• isBillingSupported() – StoreKit / Google Play の利用可能性を確認します.
• getProduct() / getProducts() –価格、ローカライズされたタイトル、説明、イントロオファー、およびiOSのサポートされている価格条件を取得します.
• purchaseProduct() – StoreKit 2またはBillingクライアント購入フローの開始、iOSの月額コミットメント請求計画を含みます.
• restorePurchases() –過去の購入を再生し、現在のデバイスにsyncします.
• getPurchases() –iOSのすべての取引またはPlay Billingの購入をリストします.
• manageSubscriptions() –ネイティブのサブスクリプション管理UIを開きます.
• addListener('transactionUpdated') – iOSアプリが起動したときに、StoreKit 2の保留中の取引を処理する (iOSのみ).

ベストプラクティス

1. ショップの価格を表示 – Appleは表示を必要とします product.title そして product.priceString; どのハードコーディングも許可されません。
2. 使用 appAccountToken – ユーザーIDからUUID (v5) を決定的に生成して、購入をアカウントにリンクする。
3. サーバー側で検証 – (iOS) / receipt 送信 purchaseToken バックエンドに検証する
4. エラーを柔軟に処理する – ユーザーのキャンセル、ネットワークの失敗、非対応の請求環境を確認する
5. 徹底的にテストする – iOSサンドボックスガイド と Androidサンドボックスガイド.
6. 請求の復元と管理を提供する – UIボタンに接続する restorePurchases() と manageSubscriptions().

収益の次のステップ

購入フローの正常動作後、 Revenue Playbook を使用して、最初の有料チャネルを計画する: 製品スコープ、ASO、価格設定、壁の配置、分析、そして脱落フィードバック。

トラブルシューティング

トラブルシューティング

• 製品が読み込まれない
• バンドルID / アプリケーションIDがストアの設定と一致していることを確認してください。
• 製品IDがアクティブで承認済み (App Store) または有効化済み (Google Play) であることを確認してください。

製品を作成してから数時間待ってください。ストアのプロパゲーションは即時ではありません。

• 購入がキャンセルされたり、途中で止まったりする try/catch と表面に親しみやすいエラーメッセージ。
• Androidの場合、テストアカウントはPlayストア（内部トラック）からアプリをインストールして、Billingが機能するようにします。
• デバイス上で実行している場合、Billingエラーを確認するには、logcat/Xcodeを参照してください。

サブスクリプションの状態が不正です。

• を使用して getPurchases() ストアデータとローカルエンタイトルメントキャッシュを比較するために
• Androidの場合、常にGoogle Play Developer APIに purchaseToken を使用して、有効期限日または払い戻しステータスを取得します。
• iOSの場合、を確認して、払い戻しまたは取り消しを検出するために、受け取りを検証してください。 isActive/expirationDate 続けてGetting Started

「続けてGetting Started」というセクション

Capgoを使用している場合 はじめに 店舗承認と配布を計画するには Using @capgo/native-purchases for the native capability in Using @capgo/native-purchases, @capgo/capacitor-in-app-review for the implementation detail in @capgo/capacitor-in-app-review, Using @capgo/capacitor-in-app-review for the native capability in Using @capgo/capacitor-in-app-review, @capgo/capacitor-native-market for the implementation detail in @capgo/capacitor-native-market, and Using @capgo/capacitor-native-market for the native capability in Using @capgo/capacitor-native-market.