앱 내 구입을 위한 App Store Server API 자세히 알아보기

안녕하세요, App Store server 팀 엔지니어 Riyaz입니다 이 세션에서는 앱 내 구입 관련 App Store Server API를 살펴보겠습니다 최신 업데이트를 통해 앱 서버의 작업이 간소화되고 향상되는 방식을 보여드리겠습니다 앱 서버의 주요 작업을 살펴보는 것으로 시작해 보겠습니다 세 가지 중요한 작업이 있는데

먼저, 앱 내 구입을 관리합니다 트랜잭션 데이터를 고객 계정으로 연결해 앱에서 원활하게 콘텐츠와 서비스를 제공하도록 지원하는 것과 관련된 작업이죠

다음으로, 요청에 서명합니다 서명하려면 App Store에 대한 서버의 요청을 승인하는 서명을 생성해야 합니다

마지막으로, 환불 결정 절차에 참여합니다 서버는 구입 관련 소비 데이터를 공유하여 App Store에서 데이터를 바탕으로 환불을 결정하게 합니다 앱 서버에서 관리하는 여러 중요한 작업 중의 일부분입니다 다음으로, App Store Server API 최신 업데이트를 통해 이 작업이 어떻게 향상되는지 살펴보겠습니다 다뤄야 하는 내용이 많으니 바로 시작하겠습니다 우선, 트랜잭션 식별자가 업데이트되었습니다 앱 내 구입을 효율적으로 관리하는 데 도움이 됩니다 다음으로 서명 생성 개선 사항을 살펴볼 텐데 서버 측 요청 서명 절차가 간소화됩니다 마지막으로 환불 절차 참여 방법을 간소화하는 개선 사항을 살펴봅니다

앱 내 구입의 관리부터 자세히 살펴보죠 앱 내 구입의 관리는 시스템의 효과적인 고객 계정 관리에서 시작됩니다

일반적으로 고객마다 고유한 시스템 내 계정 ID가 할당되어 고객의 계정과 App Store 트랜잭션이 명확하게 연결됩니다 이러한 연결은 구입한 콘텐츠를 제공하고 고객의 사용자 경험을 개인화하는 데 매우 중요합니다 3개의 데이터 구조를 통해 앱 내 구입 데이터를 제공하는데 AppTransaction JWSTransaction JWSRenewalInfo이 그것이죠

먼저 JWSTransaction 구조를 집중적으로 살펴보겠습니다 다른 구조 유형에 대해서는 나중에 설명합니다

고객이 앱 내 구입을 실행하면 App Store는 서명된 트랜잭션 객체를 제공합니다 서버에서 JWSTransaction은 이 서명된 트랜잭션을 나타냅니다 App Store Server Library를 사용해 검증, 디코딩합니다

signedTransactionInfo의 디코딩된 샘플입니다

처음 몇 개의 필드에 앱과 관련된 중요한 정보와 앱 내 구입 상품 유형이 나와 있습니다 다음은 구입에 대한 메타데이터로 수량, 가격, 통화 등이죠 고객이 특가를 제공받는 경우 JWSTransaction에 offerType offerIdentifier offerDiscountType 필드가 추가됩니다 최근 offerPeriod 필드를 새로 추가했는데 제공받은 특가의 사용 기간을 ISO 8601 기간 표시 형식을 사용해 표시합니다 이 필드는 JWSRenewalInfo에도 포함되며 다음에 구독을 갱신할 때 적용되는 특가의 사용 기간을 알려 줍니다

다음은 트랜잭션 식별자가 있죠 transactionId는 앱 내 구입, 복원, 구독 갱신 등의 트랜잭션을 지칭하는 고유 식별자입니다 이 예제에서는 구독 갱신의 트랜잭션 ID를 나타냅니다

originalTransactionId는 최초 구입의 트랜잭션 ID입니다 구독 갱신 기간 내내 일관성 있게 유지되는 자동 갱신 구독임을 식별할 수 있게 합니다

마지막 appAccountToken은 고객이 앱 내 구입을 실행할 때 앱에서 StoreKit을 사용해서 설정한 UUID죠 이 필드를 사용해 앱 내 구입을 시스템의 고객 계정과 연결합니다 구독 갱신을 위해 appAccountToken을 가져오기 쉽도록 JWSRenewalInfo에 이 필드를 포함했습니다 이 정보를 통해 고객 계정을 최근의 구독 갱신 트랜잭션에 연결할 수 있습니다 어떻게 그렇게 되는지는 다음에 설명할게요 서버에서 UUID를 생성하면서 시작하고 생성 값을 고객 계정에 연결합니다 서버는 이 값을 StoreKit 기반 앱으로 전달하고 앱 내 구입 시 appAccountToken이 설정됩니다 특정 고객 계정을 통한 모든 앱 내 구입에 대해 동일한 appAccountToken 값을 사용하는 것이 좋습니다 App Store 서버는 JWS 트랜잭션 및 갱신 정보에서 동일한 appAccountToken 값을 반환합니다 전에는 앱 내 구입 과정에서 appAccountToken을 설정했습니다 문제는 App Store에서 특가 코드를 사용하거나 프로모션을 통해 구입하는 경우와 같이 고객은 앱 외부에서도 구입할 수 있습니다 이런 경우 appAccountToken 설정을 더 유연하게 처리하는 새 서버 엔드포인트가 있습니다 Set App Account Token으로 새 appAccountToken을 설정하거나 기존 appAccountToken을 트랜잭션을 위해 업데이트합니다 모든 상품 유형에 대해 엔드포인트를 사용할 수 있는데 소모성 항목 비소모성 항목 비갱신 구독 등의 과거 일회성 구입과 각 자동 갱신 구독의 최근 구입에 대해 사용할 수 있습니다 자동 갱신 구독의 경우 엔드포인트로 설정한 appAccountToken이 업그레이드/다운그레이드 포함 향후 갱신에도 적용됩니다

Set App Account Token 엔드포인트는 고객이 앱 외부에서 트랜잭션을 완료할 때 유용합니다 특가 코드를 사용하는 경우 등이죠 전에는 이 유형의 구입에 대해 appAccountToken 필드를 설정할 방법이 없었는데 StoreKit을 사용하지 않았기 때문입니다 또한 appAccountToken을 고객 계정에 연결하는 동안 발생한 불일치를 수정할 수 있습니다 시스템에서 계정 소유자가 바뀌는 경우 등이죠 지금 보여드리는 엔드포인트는 App Store Server API에 포함되어 있습니다

Set App Account Token 엔드포인트 사용 방법을 보여드리면 경로에 최초 구입의 TransactionId를 제공합니다 이 값으로 일회성 구입 트랜잭션인지 appAccountToken을 설정할 구독인지 식별합니다

요청 본문에서 appAccountToken에 대해 원하는 UUID 값을 설정합니다 엔드포인트를 통해 제공한 appAccountToken은 이전에 설정된 appAccountToken을 덮어씁니다 appAccountToken은 다른 트랜잭션 식별자인 transactionId originalTransactionId와 함께 고객 계정이 App Store 트랜잭션에 연결되도록 합니다 식별자에 대해 간략히 말씀드리면 App Store에서 transactionId와 originalTransactionId를 생성하고 appAccountToken을 생성하고 App Store 트랜잭션에 연결하는 것은 앱 쪽에서 담당합니다 transactionId를 통해 특정 구입 이벤트를 식별합니다 originalTransactionId는 단일 구독 그룹 내에서 자동 갱신 구독의 구독 주기를 관리하고 구독 상태를 확인하기에 좋습니다 appAccountToken은 고객의 계정 정보를 앱 내 구입으로 연결할 때 필요합니다 앱에서 가족 공유를 지원하는 경우 appAccountToken을 가족 공유 트랜잭션에 사용할 수 없습니다 transactionId와 originalTransactionId 모두 JWSTransaction 및 JWSRenewalInfo에 있죠 appAccountToken은 StoreKit 혹은 엔드포인트로 토큰을 설정한 경우에만 사용할 수 있습니다

고객이 앱을 다운로드하면 AppTransaction 객체는 StoreKit에서 사용할 수 있고 중요한 앱 다운로드 정보를 나타냅니다 transactionId, originalTransactionId appAccountToken은 앱 내 구입에 한정되며 AppTransaction 객체에는 포함되어 있지 않습니다 앱 다운로드를 고유하게 식별해야 한다면 앱 설치 시 콘텐츠를 잠금 해제하는 경우죠 appTransactionId라는 새로운 필드를 AppTransaction 객체에 추가하면 됩니다 appTransactionId는 앱별로 Apple 계정마다 부여되는 전역 고유 식별자(GUID)입니다 가족 공유에서는 가족 구성원마다 고유한 appTransactionId를 받죠 appTransactionId는 Apple 계정과 앱이 같으면 재다운로드 환불, 재구매, 스토어프론트 변경과 관계없이 고정 유지돼요 appTransactionId는 앱 내 구입 시에도 제공되므로 고객 계정과 App Store 트랜잭션 간 연결의 유연성이 커집니다 어떻게 그런 건지는 다음에 설명할게요 appTransactionId를 사용해 고객 계정을 App Store 트랜잭션과 연결하는 한 방법은 고객이 앱을 다운로드할 때 시스템의 고객 계정을 AppTransaction 객체에 있는 appTransactionId와 연결하는 것입니다 서버에서 AppTransaction 객체를 가져오려면 앱에서 이 정보를 보내면 됩니다 고객이 앱 내 구입을 실행하면 JWSTransaction 및 JWSRenewalInfo에 동일한 appTransactionId가 포함되죠 한 번 연결하면 모든 App Store 트랜잭션 객체에서 재사용합니다 appTransactionId는 모든 App Store 트랜잭션 객체에 공통적으로 포함되므로 앱에서 동일한 고객 계정으로 발생한 서로 다른 두 건의 구독을 식별하는 등의 유용한 활용이 가능합니다 앱에서 월간 스포츠 뉴스레터와 라이브 경기를 시청하는 연간 시즌 구독까지 두 개의 구독 상품을 지원한다면 고객 계정으로 두 구독 상품을 모두 이용 가능한지 어떻게 확인하나요?

두 개의 구독은 고유한 transactionId와 originalTransactionId가 있지만 appTransactionId는 동일합니다 이 필드를 활용해 앱 내 구입을 복원하는 등의 앱 내 맞춤화를 출시 시 활성화할 수 있습니다 appTransactionId를 Get Transaction History Get All Subscription Statuses 인기 있는 App Store Server API 엔드포인트를 사용할 때 트랜잭션 ID로 사용할 수도 있죠 서버 엔드포인트를 사용해 AppTransaction 객체를 가져오는 새 엔드포인트를 소개합니다 새 Get App Transaction Info 엔드포인트를 사용하면 최초로 기기가 아닌 서버에서 직접 앱 다운로드 정보를 가져올 수 있습니다 AppTransaction 객체를 사용해 앱 버전, 플랫폼, 환경 등의 중요한 앱 다운로드 정보를 확인할 수 있습니다 이 정보를 사용하면 비즈니스 모델 변경에 따른 앱의 실적을 확인할 수 있습니다 이 엔드포인트로는 기기 검증 과 같은 기기 관련 세부 정보는 확인할 수 없습니다 그러한 용도로는 앱에서 획득한 AppTransaction 객체를 계속 사용하면 됩니다 보여드릴 엔드포인트는 App Store Server API의 일부로

Get App Transaction Info 엔드포인트 사용 사례입니다 경로에 originalTransactionId transactionId, appTransactionId 같은 트랜잭션 식별자를 제공할 수 있습니다 응답에는 JWS signedAppTransactionInfo가 포함됩니다 App Store Server Library를 사용해 signedAppTransactionInfo를 디코딩하는 것도 가능합니다 Get App Transaction Info 엔드포인트는 하반기 출시됩니다 appTransactionId를 앞서 보여드린 다른 트랜잭션 식별자와 비교하면 transactionId originalTransactionId와 마찬가지로 App Store에서 appTransactionId를 생성합니다

appTransactionId를 사용하면 앱 다운로드를 고유하게 식별하고 고객의 후속 구매를 그 다운로드와 연결할 수 있습니다 appTransactionId는 모든 App Store 트랜잭션 객체에서 동일합니다 가족 공유 트랜잭션에 appTransactionId를 사용할 수 있습니다 앱에서 가족 공유를 지원한다면요 모든 필요에 대한 원스톱 식별자 솔루션 appTransactionId를 사용하는 것을 추천합니다 앱 내 구입 관리를 간소화하고 구입을 서버의 고객 계정과 간단히 연결합니다 이제 요청 서명의 주요 개선 사항을 살펴보겠습니다 먼저 서버에서 JSON 웹 서명의 약자인 JWS 문자열을 생성합니다 다음으로 App Store Connect에서 다운로드하는 개인 키를 사용해 이 정보에 서명합니다

이 서명 문자열을 StoreKit 기반 앱으로 전송하면 앱에서 서명이 필요한 함수를 호출합니다

StoreKit은 서명된 서명 문자열을 App Store 서버로 보내요 이전에는 사용 사례별로 App Store 서버에서 요구하는 다양한 형식의 서명 문자열에 서명했습니다 이제 모든 사용 사례에서 JWS 서명 형식을 사용하도록 요청 서명 방식이 통합되었습니다 요청 서명이 필요한 StoreKit 호출에 형식을 사용합니다 프로모션 특가 서명 생성 같은 함수를 비롯해서요 JWS 형식을 사용해 프로모션 특가에 서명하면 됩니다 새로운 서명 방식은 이전의 프로모션 특가 서명을 대신합니다 신규 구독 특가를 유연하게 설정할 수 있도록 최근 새로운 JWS 신규 구독 특가 서명을 도입했습니다 이 기능을 사용하면 트랜잭션별로, 사용자별로 신규 구독 특가용 맞춤 자격 조건을 설정할 수 있어 고객이 App Store에서 신규 구독 특가를 제공받는 횟수를 조절할 수 있습니다 Advanced Commerce API로 서명된 JWS 인앱 요청을 보내도 돼요 자세한 내용은 개발자 문서를 참고하세요 서버에서 JWS 프로모션 특가 서명을 생성하는 방법을 보여드리겠습니다 StoreKit에서 프로모션 특가 서명을 사용해 기존 구독자를 유지하거나 이탈자의 재참여를 유도하세요 App Store Server Library를 사용해 프로모션 특가 서명을 생성하는 사례입니다 이 예제에서는 Java를 사용하겠습니다 PromotionalOfferV2SignatureCreator 클래스를 인스턴스화합니다 앱의 개인 키, keyId issuerId, bundleId를 사용해서요 App Store Connect에서 키, keyId issuerId를 다운로드합니다

이러한 값은 서명 문자열에 서명 시 사용되어 고객이 개발자 동의 없이 프로모션 특가를 제공받을 수 없도록 합니다

transactionId를 지정합니다 여기에서 고객에게 속한 모든 트랜잭션 식별자 appTransactionId를 포함해서요 제공할 수 있습니다

특정 고객으로 한정하려면 transactionId를 제공하고 아니라면 이 필드는 건너뜁니다

productId와 offerId를 제공합니다 App Store Connect에서 이 ID로 표시되는 특가를 미리 설정해 두었습니다

마지막으로 productId offerId, transactionId를 createSignature 함수에 전달합니다 입력 항목이 줄어 새 서명은 기존 서명보다 간단합니다 통합된 JWS 서명 형식을 사용하면 여러 사용 사례에 걸쳐 요청 서명 방식을 간소화할 수 있습니다 특가를 제공한 후에도 통제를 벗어난 상황으로 인해 고객이 반품하고 환불을 요청하는 것도 가능합니다 청구 문제가 발생했거나 실수로 구매한 경우 등이죠 이런 경우를 대비해 환불 결정 절차에 참여하는 방법을 보여드리겠습니다 몇 가지 장점을 소개해 드리자면 고객의 상품 사용 여부를 알고 있기 때문에 환불 결정에 참여하는 것을 고려해야 합니다 앱에서 소모성 상품을 지원하는 경우 서버에서 이미 고객의 소모성 항목 잔액을 관리합니다 환불 요청 후 고객 만족도를 개선하는 데 도움이 됩니다

고객이 환불을 요청하면 App Store에서 서버로 CONSUMPTION_REQUEST 알림을 보냅니다 환불 결정 절차에 정보를 제공할 수 있도록 Send Consumption Information 엔드포인트를 사용해 이 알림에 응답할 수 있습니다

새롭게 개선된 Send Consumption Information V2 엔드포인트를 소개하게 되어 기쁩니다

핵심은 입력 항목의 수가 크게 줄어 이전 버전에 비해 엔드포인트 통합이 간소화되었다는 점이죠 새 엔드포인트는 상품의 부분적 소비가 더 잘 반영되도록 일할계산 환불방식 설정도 지원합니다 이 엔드포인트의 이전 버전에서는 소모성 항목과 자동 갱신 구독에 대해서만 일할 계산이 지원되었지만 비소모성 항목과 비갱신 구독 포함 모든 상품 유형으로 지원을 확장했습니다

이미 V1 엔드포인트를 사용해 왔다면 지원이 중단되지만 요청은 계속 수신됩니다 Send Consumption Information 엔드포인트를 사용하지 않았다면 V2 엔드포인트를 App Store Server Library와 함께 사용해 보세요 Send Consumption Information V2 엔드포인트 사용법입니다 고객이 소모성 항목 구입에 대한 환불을 요청했고 CONSUMPTION_REQUEST 알림이 서버로 전송되었다면 Send Consumption Information V2 엔드포인트로 알림에 응답하는 방법을 예로 보여드리면

경로에 transactionId를 제공합니다 CONSUMPTION_REQUEST 알림에 있습니다

새 엔드포인트는 총 5개의 입력 필드를 지원합니다 이전 버전의 12개에서 줄었죠 5개 중 3개는 필수 필드이고 2개는 선택 필드입니다 필드 수를 크게 줄여 환불 결정 참여가 더 간편해졌습니다 고객이 동의하면 customerConsented를 true로 설정해 App Store에 환불 요청과 관련된 소비 데이터를 보냅니다 ConsumptionRequestV2 본문의 모든 데이터를 포함하죠 고객이 동의하지 않았으면 CONSUMPTION_REQUEST 알림에 응답하지 마세요 필드가 false로 되어 엔드포인트가 호출되는 경우 요청이 거부됩니다 sampleContentProvided를 사용해 고객이 상품을 구매하기 전 샘플 콘텐츠를 제공했는지 명시합니다 deliveryStatus에 DELIVERED를 사용하면 됩니다 고객에게 콘텐츠를 성공적으로 전달했다면 말이죠 아니라면 UNDELIVERED 상태를 사용합니다

선택적으로 환불에 대한 기본 설정을 제공할 수 있습니다 일할계산 환불방식 설정을 제공하는 것도 고려해 봅니다 GRANT_PRORATED 값을 사용합니다 이미 지원되는 전액 환불 환불 불가 외에 추가로요 기본 설정을 제공하지 않으려면 이 필드를 설정하지 마세요 consumptionPercentage는 상품 소비율을 millipercent 단위로 알려 줍니다

값이 25,000이면 소모성 상품이 25% 소비됨을 나타냅니다 Send Consumption Information V2 는 하반기 출시 예정이죠 새로운 일할계산 환불방식 옵션을 살펴보겠습니다 최신 V2 엔드포인트에서 지원됩니다 일할계산 환불방식 설정을 제공하는 것도 고려해 보세요 고객이 상품을 부분적으로 소비하는 것도 가능하다면요

일할계산 환불방식 설정을 통해 소비율을 지정할 수 있어 App Store에서 그에 맞는 환불 금액을 지급하도록 합니다

consumptionPercentage를 지정해야 합니다 소모성, 비소모성, 비갱신 구독 상품 유형에 대한 일할계산 환불방식 설정을 제공하는 경우에는요 App Store에서 환불을 적절히 지급하도록 하기 위함이죠 자동 갱신 구독의 경우 App Store에서 대신 consumptionPercentage를 계산합니다 고객의 남은 구독 기간을 사용해서요 소비 데이터를 제출하면 App Store에서 전액 환불하거나 일할계산 환불하거나 거절하는 결정에 도움이 됩니다 REFUND 또는 REFUND_DECLINED 알림으로 결정을 압니다 REFUND_DECLINED 알림을 받으면 별도의 조치를 취하지 않아도 되지만 REFUND 알림을 수신한 경우 그에 맞는 조치를 취해야 합니다 샘플 REFUND 알림입니다 App Store에서 얼마나 환불되었는지 확인할 수 있습니다 새로운 refundPercentage 필드를 사용해서요 이 경우 75% 환불되었으므로 소비된 상품에 대한 적절한 조치를 취합니다

이 필드를 사용하는 경우 App Store Connect에서 재무 및 회계와 관련된 정보를 반드시 확인해야 합니다 구독 취소 유형을 확인할 수도 있습니다 새로운 revocationType 필드를 사용해서요 REFUND_FULL, REFUND_PRORATED 또는 FAMILY_REVOKE 소모성 항목 환불이므로 REFUND_FULL 또는 REFUND_PRORATED 전액 환불 또는 가족 공유 관련 구독이 취소된 경우 서버 콘텐츠에 대한 접근 권한을 즉시 회수합니다 REFUND_PRORATED의 경우 환불된 비율만큼 회수합니다 일할계산 환불이 포함된 환불 알림을 서버에서 처리하는 방법을 보여드리겠습니다 소모성, 비소모성 비갱신 구독 상품의 경우 refundPercentage 필드를 사용해 환불 비율에 비례해 콘텐츠의 양을 계산한 다음 고객 계정에서 회수합니다 고객이 가상 화폐를 구입했다면 환불 금액만큼 잔액을 차감할 수 있습니다 자동 갱신 구독의 경우 전액 환불 처리와 마찬가지로 일할계산 환불을 처리합니다 현재 구독 상태를 확인하고 적절한 조치를 취합니다 새 Send Consumption Information V2 를 사용해 환불 결정 절차에 참여하길 바랍니다 전에 없이 쉽고 강력해졌기 때문입니다 많은 내용을 다루었는데 간단히 요약해 보겠습니다 다양한 트랜잭션 식별자와 원스톱 트랜잭션 식별자인 appTransactionId를 소개했습니다 이어서 통합된 JWS 서명 형식을 살펴보았죠 환불 결정에 얼마나 쉽게 참여할 수 있는지 보여드렸어요 헤어지기 전에 다음에 어떻게 하면 좋은지 말씀드리면 오픈 소스 App Store Server Library에 이미 기여하셨다면 정말 감사합니다 아니라면 GitHub 페이지를 방문해 기여하는 법을 배워 App Store 커뮤니티를 지원해 주세요 새로운 기능을 도입하면서 여러분의 의견을 듣고 싶습니다 피드백 지원을 사용해 App Store server 팀에 기능 요청과 피드백을 제출해 주세요 StoreKit 업데이트에 대해 자세히 알아보려면 ‘StoreKit 및앱 내 구입의 새로운 기능’ WWDC25 세션을 확인하세요 다음 WWDC24 세션도 같이 확인해 보세요 ‘앱 내 구입을 위한 App Store Server API 살펴보기’ App Store Server에 대해 자세히 알아볼 수 있습니다 함께해 주셔서 감사합니다 다음에 또 봐요!