시작하기

1. 패키지를 설치

   bun add @capgo/native-purchases

2. 자연 프로젝트와 Sync

   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 구독이 지원되면, 12개월의 약속과 함께 월별 청구 옵션을 보여주고 pricingTermspass billingPlanType: 'monthly' __CAPGO_KEEP_0__ purchaseProduct(). iOS 월간 청구 요금 계획을 확인하세요. iOS

   Android
   • StoreKit Local Testing 또는 Sandbox 테스터를 사용하여 QA를 진행하세요.
     
   • 매니페스트 편집이 필요하지 않습니다. 제품이 승인되었는지 확인하세요.
     
   • Google Play Console에서 앱 내 제품 및 구독을 생성하세요.
   App Store Connect에서 앱 내 제품 및 구독을 생성하세요.
   • 내부 테스트 빌드를 업로드하고 라이선스 테스터를 추가하세요.
     
   • billing permission을 추가하세요.
     
   • __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	애플 스토어 커넥트 / 구글 플레이 콘솔에서 SKU/제품 ID를 구성했습니다.
productType	Android만	PURCHASE_TYPE.INAPP 또는 PURCHASE_TYPE.SUBS. 기본값입니다. INAPP. 항상 설정됩니다. SUBS 구독을 위한.
planIdentifier	구독.	구글 플레이 콘솔에서 가져오는 Android 구독의 기본 플랜 ID입니다. 구독을 위한 필수 값이며 iOS 및 인앱 구매에서는 무시됩니다.
billingPlanType	iOS 구독.	StoreKit 구매를 위한 iOS의 billing plan을 사용하세요. 'monthly' 를 사용하여 월별 결제와 12개월의 약속을 사용할 수 있습니다. product.pricingTerms iOS
quantity	인앱 구매를 위한 것만 해당하며 기본값은	입니다. Android는 항상 하나의 아이템을 구매합니다. 1iOS
appAccountToken	iOS + Android	__CAPGO_KEEP_0__
isConsumable	Android	설정 true 구매를 사용자와 연결하는 UUID/문자열. iOS에서는 UUID가 필요하며 Android는 64자 이하의 암호화된 문자열을 허용합니다. false.

Android

소비 가능한 권한을 부여한 후 토큰을 자동으로 소비하는지 확인합니다. 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 리스너 지원 포함.
• 서버 수신 영수증 검증이 필요합니다.: isActive/expirationDate are not populated; call the Google Play Developer API with the purchaseToken 은 채워지지 않습니다; Google Play 개발자 __CAPGO_KEEP_0__에 Google Play Developer __CAPGO_KEEP_0__에 호출하여 purchaseState 의 권위 있는 상태입니다. PURCHASED must be isAcknowledged and true.

API quick reference

• isBillingSupported() 제목이 “__CAPGO_KEEP_0__ 빠른 참조”인 섹션
• getProduct() / getProducts() – 가격을 가져오고, 지역화된 제목, 설명, 소개, 및 지원되는 iOS 가격 조건을 가져옵니다.
• purchaseProduct() – StoreKit 2 또는 Billing 클라이언트 구매 흐름을 시작하고, iOS 월간 약속 결제 계획을 포함합니다.
• restorePurchases() – 역사적인 구매를 재생하고 현재 기기와 동기화합니다.
• getPurchases() – iOS 거래 또는 Play Billing 구매를 모두 목록화합니다.
• manageSubscriptions() – 네이티브 구독 관리 UI를 열어줍니다.
• addListener('transactionUpdated') – 앱이 시작될 때 StoreKit 2 거래를 처리할 때 (iOS 전용).

Best practices

1. 스토어 가격을 표시하세요 – 애플은 표시해야 하며, 절대로 하드 코딩하지 마세요. product.title – 스토어 가격을 표시하세요. product.priceString– 애플은 절대로 하드 코딩하지 마세요.
2. 사용하여 appAccountToken – 사용자 ID에서 UUID (v5)를 결정론적으로 생성하여 구매를 계정에 연결합니다.
3. 서버 측에서 유효성 검사합니다 – (iOS) / (Android)를 백엔드에 전송하여 확인합니다. receipt 오류를 부드럽게 처리합니다 purchaseToken – 사용자 취소, 네트워크 오류 및 지원되지 않는 결제 환경을 확인합니다.
4. 깊이 테스트합니다 – iOS 샌드박스 가이드를 따르세요.
5. Android 샌드박스 가이드를 따르세요. iOS 샌드박스 환경에서 테스트하세요. Android 샨드박스 환경에서 테스트하세요. iOS 샨드박스 환경에서 테스트하는 방법을 확인하세요. 안드로이드 샌드박스 가이드.
6. 판매 복원 및 관리 – UI 버튼을 연결하여 restorePurchases() 및 manageSubscriptions().

수익성 다음 단계

구매 흐름이 작동하면, 첫 번째 유료 채널을 계획하는 데 사용하는 수익성 플레이북 제품 범위, ASO, 가격, paywall 위치, 분석, churn feedback

문제 해결

제품 로드가 안되는 문제

• bundle ID / 애플리케이션 ID가 스토어 구성과 일치하는지 확인하십시오.
• 제품 ID가 활성화되고 승인된 상태인지 (App Store) 또는 활성화된 상태인지 (Google Play) 확인하십시오.
• 상품을 생성한 후 몇 시간 기다리십시오; 스토어 전파는 즉시 이루어지지 않습니다.

구매가 취소되거나 중단된 경우

• 사용자는 중간에 취소할 수 있으므로 try/catch 그리고 사용자 친화적인 오류 메시지를 표면화하십시오.
• Android의 경우, 내부 트랙으로 Play Store에서 앱을 설치한 테스트 계정으로 Billing이 작동하도록 하십시오.
• 장치에서 실행 중인 경우 Billing 오류를 확인하기 위해 logcat/Xcode를 확인하십시오.

구독 상태가 올바르지 않은 경우

• 를 사용하여 스토어 데이터와 로컬 권한 캐시를 비교하십시오. getPurchases() Android의 경우, 항상 Google Play Developer __CAPGO_KEEP_0__와 Google Play Developer __CAPGO_KEEP_0__를 쿼리하십시오.
• On Android, always query the Google Play Developer API with the purchaseToken __CAPGO_KEEP_0__
• iOS에서 만료일 또는 환불 상태를 확인하세요. isActive/expirationDate __CAPGO_KEEP_1__