Getting Started

설치

AI-Assisted Setup을 사용하여 플러그인을 설치할 수 있습니다. 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.

만약 Manual Setup을 선호한다면, 다음 명령어를 실행하고 아래의 플랫폼별 설명서를 따르세요:

1. __CAPGO_KEEP_0__을 설치하세요

   bun add @capgo/native-purchases

2. __CAPGO_KEEP_0__과 네이티브 프로젝트 동기화

   bunx cap sync

3. __CAPGO_KEEP_0__ 요금제 지원 확인

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

4. __CAPGO_KEEP_0__를 직접 스토어에서 불러옵니다

   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. __CAPGO_KEEP_0__ 구입 및 복원 흐름 구현

   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 Store Connect에서 인앱 제품 및 구독을 만들 수 있습니다.
     
   • StoreKit Local Testing 또는 Sandbox 테스터를 사용하여 QA를 진행할 수 있습니다.
     
   • __CAPGO_KEEP_0__을 편집할 필요가 없습니다. 제품이 승인되도록 확인하세요.
   Android
   • __CAPGO_KEEP_0__에서 Google Play Console에서 앱 내 제품 및 구독을 만들세요.
     
   • __CAPGO_KEEP_0__에 내부 테스트 빌드를 업로드하고 라이선스 테스터를 추가하세요.
     
   • __CAPGO_KEEP_0__에 결제 권한을 추가하세요. 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/Product ID를 구성합니다.
productType	Android만	PURCHASE_TYPE.INAPP 또는 PURCHASE_TYPE.SUBS. 기본값은 INAPP. 항상 SUBS 구독에 대해
planIdentifier	Android 구독	Google Play Console 에서 Base Plan ID를 가져옵니다. 구독에 필요하고 iOS 및 인앱 구매에서는 무시됩니다.
billingPlanType	iOS 구독	StoreKit 구입을위한 billing plan을 사용합니다. 'monthly' 월 12개월 계약으로 월별 청구를 선택할 수 있습니다. product.pricingTerms iOS에서만 사용할 수 있는 in-app 구매 옵션입니다. 기본값은
quantity	. Android는 항상 1개의 아이템을 구매합니다.	iOS + Android 1구매를 연결하는 사용자 ID입니다. iOS에서는 UUID를 사용해야 하며, Android에서는 64자 이내의 암호화된 문자열을 허용합니다.
appAccountToken	Android	기본값은
isConsumable	.	소비 가능한 토큰을 부여한 후 자동으로 소비할지 여부를 결정합니다. 기본값은 true . false.

소비 가능한 토큰을 부여한 후 자동으로 소비할지 여부를 결정합니다.

__CAPGO_KEEP_0__ getPurchases() __CAPGO_KEEP_1__

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

__CAPGO_KEEP_3__

• __CAPGO_KEEP_5____CAPGO_KEEP_6__ isActive, expirationDate, willCancel__CAPGO_KEEP_7__
• __CAPGO_KEEP_8__: isActive/expirationDate are not populated; call the Google Play Developer API with the purchaseToken __CAPGO_KEEP_10__ purchaseState __CAPGO_KEEP_11__ PURCHASED __CAPGO_KEEP_0__ quick reference isAcknowledged __CAPGO_KEEP_0__ quick reference true.

API quick reference

• isBillingSupported() – iOS 월간 약속 결제 플랜을 포함하여 StoreKit 2 또는 Billing 클라이언트 구매 흐름을 시작합니다.
• getProduct() / getProducts() – 기기에서 역사적인 구매를 재생하고 현재 기기에 동기화합니다.
• purchaseProduct() – iOS 거래 또는 플레이 빌링 구매를 모두 목록화합니다.
• restorePurchases() – 네이티브 구독 관리 UI를 열어줍니다.
• getPurchases() – 앱이 시작될 때 iOS 전용으로 대기 중인 StoreKit 2 거래를 처리합니다.
• manageSubscriptions() __CAPGO_KEEP_0__ best practices
• addListener('transactionUpdated') __CAPGO_KEEP_0__ best practices

__CAPGO_KEEP_0__

1. 스토어 가격 표시 – 애플은 가격을 표시해야 하며 product.title 그리고 product.priceString; 항상 하드 코딩하지 마십시오.
2. 사용 appAccountToken – 사용자 ID에서 UUID (v5)를 결정적으로 생성하여 구매를 계정에 연결하세요.
3. 서버 측에서 유효성 검사 – (iOS) / receipt (Android) 구매를 확인하기 위해 백엔드에 전송하십시오. purchaseToken 오류를 잘 처리하십시오.
4. – (iOS) / – 사용자의 취소, 네트워크 오류 및 비지원 결제 환경을 확인하십시오.
5. 깊이 테스트하십시오 – 다음을 따라 iOS 샌드박스 가이드 및 Android 샌드박스 가이드.
6. 구매 후 복원 및 관리를 제공하십시오 – UI 버튼을 연결하여 restorePurchases() 및 manageSubscriptions().

수익성 다음 단계

구매 흐름이 작동하면 다음을 사용하십시오 __CAPGO_KEEP_0__ __CAPGO_KEEP_1__

__CAPGO_KEEP_2__

__CAPGO_KEEP_4__

• __CAPGO_KEEP_5__
• __CAPGO_KEEP_6__
• __CAPGO_KEEP_7__

__CAPGO_KEEP_8__

• __CAPGO_KEEP_9__ try/catch __CAPGO_KEEP_10__
• __CAPGO_KEEP_11__
• __CAPGO_KEEP_0__

구독 상태 오류

• 사용하여 getPurchases() 로 로컬 권한 캐시와 스토어 데이터를 비교합니다.
• 안드로이드에서 항상 Google Play Developer API와 purchaseToken 을 사용하여 만료일 또는 환불 상태를 얻습니다.
• iOS에서 isActive/expirationDate 를 확인하고 환불 또는 취소된 경우를 검증합니다.

Getting Started에서 계속

Capgo를 사용하는 경우 Getting Started에서 시작합니다 스토어 승인 및 배포를 계획하고 연결하세요. @capgo/native-purchases를 사용하여 @capgo/native-purchases의 네이티브 기능을 사용하는 경우 @capgo/capacitor-in-app-review를 사용하여 @capgo/capacitor-in-app-review의 구현 세부 사항을 확인하는 경우 @capgo/capacitor-in-app-review를 사용하여 @capgo/capacitor-in-app-review의 네이티브 기능을 사용하는 경우 @capgo/capacitor-native-market를 사용하여 @capgo/capacitor-native-market의 구현 세부 사항을 확인하는 경우, @capgo/capacitor-native-market를 사용하여 @capgo/capacitor-native-market의 네이티브 기능을 사용하는 경우.