StoreKit 2 API 의 새로운 기능과 Apple이 인앱 구매 통합 을 간소화한 방법

Updated: 3월 20, 2023

Content

62fdf0da8b35ff3ba074dbce jp android tutorial 1 configuration 5 5

Apple은최근에 열린 WWDC2021에서새로운 버전의 StoreKit2를선보였습니다.iOS에서구매를 담당하는 프레임워크입니다.인앱구매 (in-apppurchase) 및구독 (subscription)기능이있는 앱 (app)의점유율이 꾸준히 증가하고 있으며,Apple은StoreKit2를출시하여 인앱 구매를 앱에 통합하는 것을 크게간소화했습니다.오늘우리는 서버 측에서 StoreKit2로작업하는 것 즉,App Store Server API를사용하는 법을 알아볼 것입니다.

인증요청

현재API 버전에서는요청을 보내기 위해 공유 암호 (SharedSecret)가필요합니다.이것은App StoreConnect에서얻을 수 있는 고정 암호 문자열입니다.API의새 버전은 요청 인증을 위해 JSONWeb Token (JWT) 표준을사용합니다.

키생성

가장먼저,요청을승인하는 데 사용되는 개인키를 생성합니다.App Store Connect를열고 Usersand Access 섹션으로이동한 다음 Keys탭으로이동합니다.인앱구매 키 유형을 선택합니다.새키를 다운로드합니다.또한ID가필요한데,App Store Connect API 탭에서찾을 수 있는 IssueID와동일한 페이지에서 복사할 수 있습니다.

Creating a private key to work with StoreKit 2 — *AppStore Server API 작업을위한 개인 키 생성*

토큰생성하기

다음단계는 요청을 승인하는 데 사용할 토큰을 만드는것입니다.이과정은 문서에자세히 설명되어 있으므로,크게신경쓸 필요는 없습니다.다음은파이톤을 위한 기성품 구현의 예입니다.모든새 요청에 대해 새 토큰을 생성하는 것은 의미가없습니다.토큰을생성할 때 기한을 최대 60분으로설정하고,이기간 동안 동일한 토큰을 사용합니다.

import time, uuid from authlib.jose import jwt  BUNDLE_ID = 'com.adapty.sample_app' ISSUER_ID = '4336a124-f214-4d40-883b-6db275b5e4aa' KEY_ID = 'J65UYBDA74' PRIVATE_KEY = ''' -----BEGIN PRIVATE KEY----- MIGTAgMGByqGSMBHkAQQgR/fR+3Lkg4... -----END PRIVATE KEY----- '''  issue_time = round(time.time()) expiration_time = issue_time + 60 * 60 # 1 hour expiration   header = {  'alg': 'ES256',  'kid': KEY_ID,  'typ': 'JWT' }  payload = {  'iss': ISSUER_ID,  'iat': issue_time,  'exp': expiration_time,  'aud': 'appstoreconnect-v1',  'nonce': str(uuid.uuid4()),  'bid': BUNDLE_ID }  token_encoded = jwt.encode(header, payload, PRIVATE_KEY) token_decoded = token_encoded.decode()  authorization_header = {  'Authorization': f'Bearer {token_decoded}' }

서명된거래

새버전의 API에서는모든 거래가 JSONWeb Signature (JWS) 표준으로반환됩니다.이것은점으로 나누어진 세 부분으로 구성된 문자열입니다.

1. Base64 헤더.

2. Base64 거래 페이로드.

3. 거래 서명.

Base64(header) + "." + Base64(payload) + "." + sign(Base64(header) + "." + Base64(payload))

거래헤더

거래가인증되었는지 확인하려면 헤더가 필요합니다.Alg 키는암호화 알고리즘을 포함하고,x5c 키는인증서 체인을 포함합니다.

{   "kid": "AMP/DEV",   "alg": "ES256",   "x5c": [     "MIIEO...",     "MIIDK..."   ] }

거래페이로드

{   "transactionId": "1000000831360853",   "originalTransactionId": "1000000806937552",   "webOrderLineItemId": "1000000063561721",   "bundleId": "com.adapty.sample_app",   "productId": "basic_subscription_1_month",   "subscriptionGroupIdentifier": "27636320",   "purchaseDate": 1624446341000,   "originalPurchaseDate": 1619686337000,   "expiresDate": 1624446641000,   "quantity": 1,   "type": "Auto-Renewable Subscription",   "appAccountToken": "fd12746f-2d3a-46c8-bff8-55b75ed06aca",   "inAppOwnershipType": "PURCHASED",   "signedDate": 1624446484882,   "offerType": 2,   "offerIdentifier": "basic_subscription_1_month.pay_as_you_go.3_months" }

Apple은거래 형식을 변경 및 확장했습니다.지금은그들과 함께 일하는 것이 더 편리하다고 생각됩니다.새형식에 대한 자세한 내용은 문서에나와있습니다.아래에서가장 중요한 변경 사항에 대해 설명하겠습니다.

Apple은 appAccountToken 필드를 추가했는데, 시스템의 사용자 Id가 포함되어 있습니다. 이 ID는 UUID 형식이어야 하며, 구매가 초기화될 때 모바일 앱에서 설정됩니다. 설정된 경우, 이 체인의 모든 거래 (갱신, 결제 문제 등 (billing issue))에서 반환되므로, 어떤 사용자가 구매했는지 쉽게 파악할 수 있습니다.
Apple은 또한 사용된 할인이 있다면, 그에 대한 정보가 포함된 offerType 및 offerIdentifier 필드를 추가했습니다. 다음은 offerType 필드의 값입니다.

1 — 출시 할인 (intro offer) (활성 또는 만료된 구독이 없는 사용자만 사용 가능)
2 — 프로모션 할인 (promo offer) (현재 및 만료된 구독에만 사용 가능)
3 — 할인 코드

프로모션할인 또는 할인 코드가 사용된 경우,offerIdentifier 키에사용된 할인의 ID가포함됩니다.과거에는서버 측에서 할인 사용을 추적하는 것이 불가능하여분석을 악화시켰습니다.이제분석에 할인 코드를 사용할 수 있습니다.

Apple은 inAppOwnershipType 필드를 추가했는데, 이는 사용자가 제품을 구입했는지 또는 가족 구독 덕분에 제품에 액세스했는지 여부를 이해하는 데 도움을 줍니다. 가능한 값:

PURCHASED
FAMILY_SHARED
또 다른 새로운 필드인 type에는 거래 유형이 포함됩니다. 가능한 값:

자동 갱신 구독
비소모품
소모품
비갱신 구독

Cancellation_date 및 cancellation_reason 필드는 이제 revocationDate 및 revocationReason이라는 새 이름을 갖습니다. 참고로, 환불로 인한 구독 철회 (subscription revocation) 사유와 날짜가 포함되어 있으므로, 새 이름이 더 논리적으로 보입니다.
모든 키는 camelCase 형식으로 반환됩니다 (모든 App Store Server API 요청과 마찬가지입니다).
모든 날짜는 밀리초 단위의 Unix 타임스탬프 형식으로 표시됩니다.

사용자구독 상태

현재사용자의 구독상태를확인하려면,GET 요청을https://api.storekit.itunes.apple.com/inApps/v1/subscriptions/{originalTransactionId}로보냅니다.여기서{originalTransactionId}는사용자의 거래 체인 ID입니다.응답으로모든 구독 그룹에 대한 상태가 포함된 거래를 받게됩니다.

{   "environment": "Sandbox",   "bundleId": "com.adapty.sample_app",   "data": [     {       "subscriptionGroupIdentifier": "39636320",       "lastTransactions": [         {           "originalTransactionId": "1000000819078552",           "status": 2,           "signedTransactionInfo": "eyJraWQiOi...",           "signedRenewalInfo": "eyJraWQiOi..."         }       ]     }   ] }

상태키는 현재 구독 상태를 표시하며,이를기반으로 사용자에게 앱의 유료 기능에 대한 접근권한을 제공할지 여부를 결정할 수 있습니다.가능한값:

1 — 구독이 활성 상태이며, 사용자는 유료 기능에 접근할 수 있어야 합니다.
2 — 구독이 만료되었습니다. 사용자는 유료 기능에 접근할 수 없어야 합니다.
3 — 구독 상태가 결제 재시도 (Billing Retry)입니다. 즉, 사용자가 구독을 취소하지 않았지만 결제에 문제가 있음을 의미합니다. Apple은 60일 동안 카드 청구를 시도합니다. 사용자는 유료 기능에 접근할 수 없어야 합니다.
4 — 구독 상태는 유예 기간 (Grace Period)이며, 이는 사용자가 구독을 취소하지 않았지만 결제 문제가 발생했음을 의미합니다. App Store Connect에서 유예 기간이 설정되어 있으므로 사용자는 유료 기능에 접근할 수 있어야 합니다.
5 — 환불로 인해 구독이 취소되었습니다. 사용자는 유료 기능에 접근할 수 없어야 합니다..

SignedTransactionInfo키는체인의 마지막 거래에 대한 정보를 포함합니다.위에서형식에 대한 세부 정보를 찾을 수 있습니다.

구독갱신 (subscription renewal)에대한 정보

SignedRenewalInfo키에는구독갱신에대한 정보가 포함되어 있습니다.

{   "expirationIntent": 1,   "originalTransactionId": "1000000819078552",   "autoRenewProductId": "basic_subscription_1_month",   "productId": "basic_subscription_1_month",   "autoRenewStatus": 0,   "isInBillingRetryPeriod": false,   "signedDate": 1624520884048 }

이정보를 통해 다음 지불 기간 동안 구독이 어떻게 되는지이해할 수 있습니다.예를들어,사용자가자동 갱신을 취소한 것을 보게 되면 다른 구독 플랜으로전환하도록 제안하거나 할인을 제공할 수 있습니다.서버알림 (servernotifications)을통해 이러한 이벤트 (events)를추적하는 것이 편리합니다.이에대해서는 곧 알려 드리겠습니다.

사용자의거래 내역

사용자의거래내역을얻으려면,GET 요청을https://api.storekit.itunes.apple.com/inApps/v1/history/{originalTransactionId}로보냅니다.여기서{originalTransactionId}는사용자의 거래 체인 ID입니다.응답으로시간별로 정렬된 거래 어레이를 얻습니다.

{ 	"revision": "1625872984000_1000000212854038", 	"bundleId": "com.adapty.sample_app", 	"environment": "Sandbox", 	"hasMore": true, 	"signedTransactions": [ 		"eyJraWQiOiJ...", 		"joiRVMyNeyX...", 		"5MnkvOTlOZl...", 		... 	] }

요청에는20개이하의 거래만 포함할 수 있습니다.사용자가더 많이 갖고 있다면,hasMore 플래그의값은 true가될 것입니다.다음거래 페이지가 필요하면 수정 GET매개변수가포함된 요청을 다시 보내십시오.동일한키의 값이 포함됩니다.

서버거래 알림

서버알림은 신규 구매,갱신,결제문제 등에 대한 정보를 얻는 데 도움이 됩니다.이를통해 보다 정확한 분석을 구축하고,구독자상태 관리를 간소화할 수 있습니다.

기존서버 알림 (V1)은대부분의 문제를 해결할 수 있지만 가끔 불편합니다.주로사용자의 한 동작에 대해 여러 알림을 받는 상황에관한 것입니다.예를들면,이제사용자가 구독을 업그레이드할 때 Apple은두 가지 알림을 보냅니다.DID_CHANGE_RENEWAL_STATUS 및INTERACTIVE_RENEWAL.현재는이 케이스를 처리하려면,어떻게든상태를 저장하고 두 번째 알림이 전송되었는지 확인해야합니다.새로운버전의 서버 알림 (V2)에서는사용자의 하나의 작업에 대해 하나의 알림만 있습니다.이것은훨씬 더 편리합니다.

두번째 버전의 서버 알림에는 새로운 이벤트인OFFER_REDEEMED,EXPIRED 및GRACE_PERIOD_EXPIRED가있습니다.구독자상태를 훨씬 쉽게 관리할 수 있습니다.SUBSCRIBED 및PRICE_INCREASE이벤트는첫 번째 버전에서 개선된 이벤트입니다.

Transaction notifications in StoreKit 2 feature new events

알림유형

알림에는이제 유형이 있으므로,사용자의모든 작업에 대한 알림 하나만으로 발생한 상황을이해할 수 있습니다.

알림유형

{   "notificationType": "SUBSCRIBED",   "subtype": "INITIAL_BUY",   "version": 2,   "data": {     "environment": "Sandbox",     "bundleId": "com.adapty.sample_app",     "appAppleId": 739104078,     "bundleVersion": 1,     "signedTransactionInfo": "eyJraWQiOi...",     "signedRenewalInfo": "eyJraWQiOi..."   } }