Getting Started

이 플러그인의 설치 단계와 전체 마크다운 가이드를 포함한 설정 지시를 복사.

        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.

설치

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을 선호한다면, 플러그인을 설치하기 위해 다음 명령어를 실행하고 아래에 플랫폼별 지침을 따르세요:

__CAPGO_KEEP_0__을 설치하세요
__CAPGO_KEEP_0__ 창
```
bun add @capgo/native-purchases
```
__CAPGO_KEEP_0__과 네이티브 프로젝트 동기화
__CAPGO_KEEP_0__ 창
```
bunx cap sync
```

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

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

__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 지원 구독이 반환 pricingTerms월간 청구 옵션을 표시하고 12 개월의 의무와 함께 billingPlanType: 'monthly' 를 purchaseProduct(). 참조 iOS 월간 청구 계획 iOS 월간 청구 청구 계획을 위한 전체 흐름을 참조하십시오.
- iOS
- Android
- App Store Connect에서 인앱 제품 및 구독을 만들십시오.
- StoreKit Local Testing 또는 Sandbox 테스터를 사용하여 QA를 진행하십시오.
- No manifest edits required. 제품이 승인되도록 제품을 확인하세요.
- Google Play Console에서 앱 내 제품 및 구독을 생성하세요.
- 내부 테스트 빌드를 업로드하고 라이선스 테스터를 추가하세요.
- __CAPGO_KEEP_0__에 billing 권한을 추가하세요. 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,
      }),
    });
  }
}

구매가 필요한 옵션

__CAPGO_KEEP_3__	플랫폼	설명
`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에서만 사용할 수 있는 옵션입니다.
`quantity`	iOS	인앱 구매 전용으로, 기본값은 `1`. 안드로이드는 항상 1개의 아이템을 구매합니다.
`appAccountToken`	iOS + 안드로이드	구매를 사용자와 연결하는 UUID/문자열입니다. iOS에서는 UUID가 필요하며, 안드로이드에서는 64자 이하의 암호화된 문자열을 허용합니다.
`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 availability를 확인하세요.

isBillingSupported() – StoreKit 2 또는 Billing 클라이언트 구매 흐름을 시작합니다. (iOS 월간 약속 결제 계획 포함).
getProduct() / getProducts() – 역사적인 구매를 재생하고 현재 기기와 동기화합니다.
purchaseProduct() – iOS 거래 또는 Play Billing 구매 목록을 표시합니다.
restorePurchases() – 네이티브 구독 관리 UI를 열어줍니다.
getPurchases() – 앱이 시작될 때 StoreKit 2 거래를 처리하세요 (iOS 전용).
manageSubscriptions() __CAPGO_KEEP_0__ best practices
addListener('transactionUpdated') __CAPGO_KEEP_0__ best practices

__CAPGO_KEEP_0__ best practices

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

판매 다음 단계를 추가합니다.

판매 흐름이 작동한 후에 이 단계를 사용합니다. Revenue Playbook 첫 번째 유료 채널을 계획하는 데 도움이 되는 매출 전략서: 제품 범위, ASO, 가격, 벽돌 배치, 분석, 그리고 churn feedback.

Troubleshooting

Products not loading

bundle ID / 애플리케이션 ID가 스토어 구성과 일치하는지 확인하십시오.
Confirm the product IDs are active and approved (App Store) or activated (Google Play).
스토어 전파가 즉시 이루어지지 않으므로 제품을 생성한 후 몇 시간 기다리십시오.

Purchase cancelled or stuck

사용자는 중간에 취소할 수 있으므로 try/catch 와 친절한 오류 메시지를 표면화하십시오.
Android의 경우, Billing이 작동하도록 Play Store(내부 트랙)에서 앱을 설치한 테스트 계정으로 확인하십시오.
__CAPGO_KEEP_0__에서 로그캣/Xcode를 확인하여 장치에서 빌링 오류를 확인하세요.

구독 상태가 잘못되었습니다.

Use getPurchases() 를 사용하여
On Android, always query the Google Play Developer API with the purchaseToken 안드로이드에서 항상 Google Play Developer __CAPGO_KEEP_0__와
를 사용하여 만료 날짜 또는 환불 상태를 얻으세요. isActive/expirationDate iOS에서

와 유효성을 검사하여 환불 또는 취소된 경우를 감지하세요.

Getting Started에서 계속하세요 Getting Started에서 계속하세요. 스토어 승인 및 배포를 계획하고 연결하세요. @capgo/native-purchases를 사용하여 native capability을 사용하는 @capgo/native-purchases의 경우 @capgo/capacitor-in-app-review를 사용하여 @capgo/capacitor-in-app-review의 구현 세부 사항을 확인하세요. @capgo/capacitor-in-app-review를 사용하여 native capability을 사용하는 @capgo/capacitor-in-app-review의 경우 @capgo/capacitor-native-market를 사용하여 @capgo/capacitor-native-market의 구현 세부 사항을 확인하세요. 그리고 @capgo/capacitor-native-market를 사용하여 native capability을 사용하는 @capgo/capacitor-native-market의 경우