App Store 서버 API의 새 기능

♪ ♪

여러분, 안녕하세요 저는 App Store 서버 팀의 엔지니어인 이언입니다 오늘은 앱 내 구입을 위한 서버 API의 새로운 기능과 중요한 최신 정보를 포함한 업데이트를 알려드리겠습니다 저희는 여러분의 서버에서 앱 내 구입을 최대한 활용하도록 돕는 주요 API 두 가지를 제공하는데요 첫 번째는 App Store Server API입니다 App Store Server API를 서버에서 주문형으로 호출하면 이것이 필요한 모든 데이터를 반환하여 여러분 앱의 앱 내 구입을 효과적으로 관리하게 해줍니다 API는 앱 내 구입 데이터를 회수하고 심지어 수정할 수도 있는 다양하고 강력한 엔드포인트를 제공합니다

저희가 제공하는 다른 주요 API는 App Store Server Notifications V2입니다

App Store Server Notifications V2를 이용하면 App Store의 서버가 여러분의 앱에서 일어난 앱 내 구입에 대한 업데이트를 주도적으로 보내줍니다 즉 App Store Server API에 폴링할 필요 없이 분 단위로 업데이트를 받을 수 있다는 뜻입니다

Notifications는 이벤트를 종합적으로 알려주는데 여기에는 구독 갱신, 만료와 환불 및 그 이상이 포함되죠

이러한 이벤트는 앱 내 구입의 전체 수명 주기를 추적하게 해주어 사용자 행동을 더 잘 이해하고 그에 맞춰 반응할 수 있게 됩니다

App Store Server API와 App Store Server Notifications V2는 많은 훌륭한 기능을 공유합니다 둘 다 거래 데이터를 익숙한 JSON 형식으로 제공하고 데이터는 서명되기 때문에 출처가 Apple임을 확신할 수 있습니다 또한 두 API를 써서 StoreKit 2를 이용하거나 기존의 StoreKit API를 이용하는 앱을 지원할 수 있습니다 저희는 여러분의 피드백을 기반으로 이 API에 새 기능을 적극 지원하고 있습니다

오늘 저는 여러분에게 기쁘게도 다양한 최신 업데이트를 소개하게 되었는데요 App Store Server API와 App Store Server Notifications V2의 소식입니다

정말 많은 신규 기능이 있지만 오늘은 시간 관계상 그중 몇 개만 소개해 드리겠습니다 이 신규 기능의 모든 자세한 사항에 관해서는 개발자 문서를 확인해 주세요 이제 App Store 서버 업데이트 중 엄선된 기능들을 살펴봅시다 세 부분으로 나눠서 업데이트를 소개할 텐데요 첫째로 여러분의 서버에서 더 쉽게 거래 내역을 다루게 돕는 신규 기능을 자세히 설명하겠습니다 다음 내용은 사용자의 구독 상태를 명확히 확인하도록 도와줄 App Store Server Notifications의 개선점입니다 마지막으로는 기존 API에서 신규 API로 마이그레이션하는 것에 대해 중요한 소식을 알려드립니다 트랜잭션부터 시작하죠 트랜잭션은 앱 내 구입에서 핵심적인 데이터 객체입니다 기기의 앱 내 구입을 나타내며 구매 내역에 관해 중요한 정보를 포함합니다 여기엔 제품 식별자와 종류 구매 날짜 등이 있죠

App Store Server는 트랜잭션을 JWS로 서명된 JSON 객체를 통해 표시합니다 이는 안전하고 표준화된 형식으로 App Store Server API와 App Store Server Notifications V2에서 볼 수 있죠

서명된 트랜잭션을 회수하는 주요 방식은 App Store Server API의 Get Transaction History 엔드포인트를 이용하는 겁니다

이 엔드포인트는 지정된 사용자의 전체 트랜잭션 기록을 반환하므로 과거부터 현재까지 사용자의 모든 구매 내용을 최신 상태로 유지할 수 있습니다 하지만 때로 서버에서 이미 트랜잭션을 인식하고 있기도 하죠 예를 들면 앱에서 서버로 간 호출로 인해서요 여러분은 서버 쪽에서 그 트랜잭션을 더 검증하고 여기에 대한 가장 최신 정보를 확실히 받아야 합니다

이전에는 이 사용 예를 보려면 Get Transaction History를 호출하고 일치하는 트랜잭션에 대한 응답을 일일이 살펴봐야 했습니다 사용 예를 발견하고 나면 응답에 나온 데이터를 가지고 기록을 수정할 수 있었죠

이 과정이 지루하게 느껴질 수도 있습니다 특히 사용자의 트랜잭션 기록 범위가 몇 장에 걸쳐 있고 엔드포인트를 여러 번 호출해야 한다면요 게다가 이미 완료된 소모성 트랜잭션을 찾고 있다면 이 방법도 소용이 없는데요 Get Transaction History 응답에 이 내역이 보이지 않기 때문입니다 이런 사용 예는 좀 더 구체적인 해결책이 필요합니다

그래서 오늘 이 사용 예를 직접 다루게 될 새 엔드포인트를 소개하겠습니다 새로운 Get Transaction Info 엔드포인트로 단일 구매에 대해 서명된 트랜잭션 정보를 요청할 수 있으며 오로지 transactionID만 제공하면 됩니다

모든 transactionID가 지원되며 제품 유형이나 사용자 기기에서 트랜잭션 상태가 완료됐는지 여부는 영향을 미치지 않습니다 맞습니다, 여러분은 이 엔드포인트에서 완료된 소모성 구입까지 가져올 수 있습니다

신규 엔드포인트의 작동 방식을 빠르게 살펴보죠 App Store 서버로부터 새 엔드포인트에 GET 요청을 보내고 이때 경로 매개변수로서 transactionID를 포함합니다

그러면 signedTransactionInfo 문자열이 있는 응답을 받을 겁니다

signedTransactionInfo를 디코딩하여 요청에 포함한 ID에 대해 거래 정보를 볼 수 있습니다

그러면 끝입니다 새 Get Transaction Info 엔드포인트는 상당히 간단하지만 서버에서 거래 내역을 다룰 때는 훨씬 더 유연한 장점을 가집니다 앞으로 다양한 사용 예에 유용하게 쓰실 수 있을 겁니다 이제 유연성이라는 주제를 더 확장해 봅시다

여러분은 App Store Server API의 이 인기 있는 엔드포인트가 이미 친숙할지도 모릅니다

각각의 엔드포인트는 originalTransactionId를 경로 매개변수로서 요구합니다 이 id는 여러분이 서버에 어느 사용자를 요청하는지 또, 어느 사용자를 위해 데이터를 보내는지 표시하죠

하지만 언제나 originalTransactionId를 이용할 수 있는 건 아닙니다 만일 transactionID만 갖고 있다면 어떨까요? 이를 새로운 Get Transaction Info 엔드포인트에 보내어 originalTransactionId를 받을 수도 있습니다 하지만 왜 굳이 엔드포인트로 다른 엔드포인트를 불러야 할까요? 오늘부터는 아무 transactionID만으로도 엔드포인트를 호출할 수 있습니다

전에 했던 것처럼 요청 경로에 ID를 넣기만 하세요 더 커진 유연성으로 App Store Server API의 이 핵심 엔드포인트를 호출하는 일이 어느 때보다도 더 쉬워지기를 바랍니다 여러분이 이미 이 엔드포인트를 originalTransactionID로 호출하고 있다면 걱정하지 마세요 이 방식도 계속 작동할 겁니다 이제 App Store Server Notifications에 등장할 업데이트로 넘어가죠 만일 여러분의 앱에 자동 구독 갱신 기능이 있다면 구독 상태와 시간에 따른 구독 상태 변화를 추적하는 것이 중요합니다 여기서 보듯 구독 상태에는 다섯 가지가 있는데요 App Store Server Notifications V2가 있으면 이 상태를 변하게 하는 이벤트에 대해 프롬프트 알림을 받을 수 있기 때문에 적절한 시기에 신속히 콘텐츠를 활성화하거나 비활성화하여 사용자가 원활하게 이용하도록 도울 수 있습니다

알림을 통해 어떻게 구독 상태를 알 수 있는지 살펴보죠 많은 알림 이벤트는 그 유형이나 하위 유형을 통해 구독 상태를 직접 나타냅니다 이를테면 여기 SUBSCRIBED 알림과 그 하위 유형인 INITIAL_BUY를 보세요

이 알림은 여러분의 제품에 새 구독자가 생긴 걸 나타내어 구독이 활성화 상태임을 알 수 있습니다

더 쉬운 예시를 보여드리죠 알림 유형이 EXPIRED인 예시입니다

이 알림은 명백하게 연관된 구독 상태가 만료된 걸 나타냅니다

하지만 어떤 알림의 경우 구독 상태가 그다지 명확하지 않을 수 있습니다 이 REFUND 알림을 예시로 들어보죠 이 알림 유형이 뜨는 것은 여러분의 앱에서의 앱 내 구입에 대한 환불이 승인되었을 때입니다 이 알림의 signedTransactionInfo를 확인하면 어떤 구매가 환불됐는지 알 수 있습니다

이 경우에 환불이 자동으로 갱신되는 구독에서 이루어졌으니 따라서 구독 상태 기록을 업데이트해야겠죠

이제 구독이 '취소' 상태라고 가정하고 싶을지도 모르지만 꼭 그렇지는 않습니다 만일 같은 originalTransactionID를 가진 더 최근의 구독 갱신 구매가 있다면 구독이 여전히 활성화 상태일 수도 있습니다 만일 그렇다면 구독 콘텐츠로의 접근을 비활성화하면 안 됩니다

이 상황에서는 구독 상태가 불명확한 것일 뿐이고 알림에 나온 데이터만으로는 이를 업데이트하기에 충분하지 않습니다 이상적인 상황이 아니죠 여러분이 구독에 대해 App Store 서버 알림을 받을 때 저희는 이 알림이 구독의 최신 상태를 명확히 나타내서 여러분의 서버에 이 중요한 정보가 빠르게 업데이트되기를 바랐습니다

그래서 저희는 App Store Server Notifications V2의 데이터 객체에 새로운 상태 필드를 도입했습니다 이 필드는 간단한 정수로서 앞서 소개한 구독의 다섯 가지 핵심 상태 중 하나를 표시합니다

이 새로운 필드는 자동으로 갱신되는 구독에 대해 저희가 보내는 모든 알림에 포함될 겁니다 이제부터 여러분은 구독 상태를 알 수 있습니다 Get All Subscription Statuses 엔드포인트를 App Store Server API에서 호출하지 않아도요 앞서 말한 상황을 이 신규 필드가 어떻게 개선하는지 살펴보죠 이제부터는 여러분이 구독에 대해 REFUND 알림을 받을 때 간단히 상태 필드를 체크하여 구독 상태를 알 수 있습니다

이 경우에는 숫자 1이 보이는데 연관된 구독이 활성화 상태인 걸 알 수 있죠

새로운 상태 필드 덕분에 App Store Server Notifications가 어느 때보다도 더 유용해졌는데요 하나도 놓치고 싶지 않을 만큼 유용한 기능이 매우 많아졌답니다 하지만 만일 여러분의 서버가 사용 불능 상태를 겪는다면 App Store 서버에서 보낸 알림이 닿지 않을 수 있습니다

그래서 저희가 Get Notification History 엔드포인트를 App Store Server API에서 제공하는 겁니다

이 엔드포인트는 최대 지난 6개월까지 App Store 서버가 앱에 대해 생성했던 버전 2 알림을 요청할 수 있게 해줍니다

이 방식으로 여러분의 서버가 불능 상태에 빠질 경우 이 엔드포인트를 사용 불능 기간에 호출하여 서버에서 누락된 알림을 다 받을 수 있습니다

그러나 어떤 사용 예의 경우 이 과정이 그리 효율적이지 않아 보일 수 있습니다 때로는 서버가 고장 나지 않더라도 알림을 놓칠 수 있습니다 예를 들면 일시적인 네트워크 문제 때문에요 이 경우에는 엔드포인트를 쿼리할 명확한 시간을 알지 못하므로 서버에서 이미 받은 수십 쪽의 알림을 일일이 살펴봐야 할 수 있죠 이러한 이용 문제를 해결하기 위해 Get Notification History에 onlyFailures라는 신규 요청 필드를 도입합니다

이 선택적 필드는 반환되는 알림을 여러분의 서버에 도달하지 못한 알림으로만 제한할 겁니다 응답은 현재 재시도 과정에 있는 알림까지도 포함하죠

이제 여러분은 서버 불능 상태와 우발적인 네트워크 문제에서 훨씬 더 빨리 회복할 수 있고 서버가 이미 받지 못한 알림만 파싱하면 됩니다 이 신규 필드가 어떻게 작동하는지 살펴봅시다 Get Notification History 엔드포인트에 요청을 보내고 신규 필드인 onlyFailures를 요청 본문에 포함합니다

응답은 이렇게 표시됩니다

notificationHistory 어레이의 각 입력 내용은 알림을 나타내며 여러분이 새 onlyFailures 필드를 요청에 포함했으므로 여기에 나열된 모든 알림이 서버에 도달하지 못하게 됩니다 단일 알림 입력 내용을 한번 자세히 보죠

여기에 signedPayload가 있는데요 이 문자열을 디코딩해서 알림의 내용을 볼 수 있습니다 서버에 본래 보내졌던 형식대로요

이 알림에 대한 sendAttempts 어레이를 보면 보내기 시도의 결과를 각각 알 수 있습니다 이 어레이에 포함되는 입력은 최대 여섯 개인데 하나는 최초의 보내기 시도를 표시하고 나머지 다섯 개는 재시도를 표시합니다

여기서는 두 개의 입력만 보이는데 둘 다 실패했죠 따라서 알림이 아직 재시도 과정에 있을 겁니다 만일 이후에 재시도가 성공한다면 이 알림은 onlyFailures 필드를 포함하는 차후의 요청에 나타나지 않습니다 onlyFailures 필드의 작동 방식을 보여드렸는데요 이 필드가 Get Notification History의 유용성을 훨씬 더 증가시킨다는 걸 알게 되실 겁니다

마지막으로 기존 API로부터의 마이그레이션에 관한 중요 업데이트입니다 여러분의 앱이 앱 내 구입을 한동안 제공했다면 verifyReceipt API를 아마 잘 아실 겁니다

2021년에 App Store Server API를 App Store Server로부터 앱 내 구입 데이터를 얻는 새 방법으로 발표했는데요 이 두 API를 비교해 보죠

verifyReceipt가 있으면 StoreKit의 본래 버전을 돌리는 클라이언트에게서 받는 영수증을 검증하고 디코딩할 수 있습니다 App Store Server API가 있으면 영수증 등에 든 같은 정보를 이 세 가지 엔드포인트를 이용해 가져올 수 있죠 App Store Server API는 또한 어디에서도 찾지 못할 유용한 데이터와 강력한 기능을 제공하는 추가적인 엔드포인트를 다양하게 제공합니다

notification API 얘기로 넘어가자면 저희는 아직 App Store Server Notifications V1을 지원합니다

하지만 2021년에 App Store Server Notifications V2를 도입했죠 이제 두 API를 비교해 봅시다

App Store Server Notifications V1과 V2는 둘 다 여러분의 서버로 직접 전송된 앱 내 구입 이벤트를 실시간으로 알려줍니다 하지만 V2는 유형과 하위 유형을 이용해 이벤트를 정의함으로써 정보를 더 명확히 했죠 차이점은 이게 다가 아닙니다 V2는 또한 추가적인 이벤트에 대한 알림과 테스트 알림을 요청하는 능력 알림 기록에 대한 접근과 사용자의 구독 상태를 추적하는 완전히 새로운 상태 필드를 제공하죠

App Store Server API와 App Store Server Notifications V2를 도입하면 서버에서 앱 내 구입 데이터를 안전하고 효율적으로 관리하게 해주는 다양한 신규 기능을 발견하실 겁니다 궁극적으로 여러분의 고객들이 더 향상된 앱 내 구입 경험을 하게 되는 거죠 따라서 오늘 저희는 verifyReceipt와 App Store Server Notifications V1의 지원 중단을 발표합니다 오늘부터 이 API는 지원이 중단되고 더 이상 기능 업데이트를 받지 못하게 됩니다

지금부터 마이그레이션을 계획하시고 신규 API의 모든 이점을 누리세요

몇 개의 짧은 단계만 거치면 새 API로 이동할 수 있습니다

verifyReceipt에서 App Store Server API로 옮기려면 여러분의 앱을 대표하기 위해 JWT를 먼저 서명해야 하는데 이 간단한 과정은 저희 문서에 기술되어 있습니다 App Store Server API를 호출할 때마다 여러분은 이 JWT를 헤더로 제공하게 됩니다 이는 여러분이 요청된 앱 데이터의 소유자라는 걸 증명할 겁니다

다음으로는 각 사용자를 위한 transactionID를 저장해야 합니다 여러분은 이 transactionID를 경로 매개변수로 제공하게 되는데 그 시기는 Get Transaction History와 Get All Subscription Statuses 같은 핵심 엔드포인트를 호출할 때마다입니다 어떤 transactionId라도 작동할 겁니다 만일 데이터베이스를 유지한다면 이미 하나를 저장해 두셨을 겁니다 그렇지 않다면 각 사용자의 영수증에서 데이터베이스를 추출할 수 있습니다

그러면 끝입니다 이후에는 verifyReceipt에서 받던 모든 데이터에 접근할 수 있고 더 많은 일도 할 수 있습니다

App Store Server Notifications V1에서 V2로 이동하는 건 훨씬 더 간단합니다 먼저 여러분의 서버가 새 V2 형식을 파싱하도록 준비합니다 이미 여러분이 App Store Server API를 이용 중이라면 이 단계가 어렵지 않을 겁니다 App Store Server Notifications V2 또한 똑같은 JWS 트랜잭션 형식을 사용하기 때문이죠

일단 여러분의 서버가 준비되면 App Store Connect에 방문하여 여러분의 환경설정을 V1에서 V2 알림으로 바꾸세요 바뀐 환경설정을 시험하려면 여러분은 버전 2 알림을 샌드박스에만 받기로 설정해서 시작하면 됩니다

환경설정을 바꾼 후에는 App Store 서버가 새로운 알림을 V2 형식으로 보내기 시작할 겁니다 재시도 과정에 있는 V1 알림이 있다면 최대 3일까지 이 알림을 계속 받을 수 있습니다

마이그레이션에 대해 도움이 더 필요할 경우 추가 자료가 준비돼 있습니다 App Store Server API와 App Store Server Notifications V2는 샌드박스 환경에서 이용할 수 있기 때문에 마이그레이션 후 프로덕션을 본격적으로 시작하기 전에 기능을 시험해 볼 수 있습니다

이번 주에는 App Store Server Library를 출시하는데요 App Store Server API를 호출하고 App Store Server Notifications V2를 파싱하는 데에 쓰이는 신규 오픈 소스 라이브러리입니다 엔드포인트를 간편하게 호출하고 수신한 서명 데이터를 검증하며 심지어는 마이그레이션이 쉬워지도록 영수증에서 transactionID를 추출하는 걸 돕습니다

여기에 관한 세션을 올해의 WWDC에서 확인해 보시길 바랍니다 제목은 'App Store Server Library 알아보기'입니다 또한 마이그레이션에 관한 팁을 더 원하시면 WWDC22 세션에서 '앱 내 구입 통합과' '마이그레이션 살펴보기'라는 제목의 세션을 보세요

이로써 App Store 서버의 업데이트 소개를 마칩니다 여러분이 오늘 발표된 훌륭한 최신 기능을 활용하고 시간상 보여드리지 못한 더 많은 내용을 문서에서 확인하시기를 바랍니다

이제 샌드박스와 프로덕션 과정 둘 다에서 모든 기능을 이용할 수 있으며 따라서 샌드박스에서 먼저 테스트한 후에 여러분의 프로덕션 서버에 준비되는 즉시 개시할 수 있습니다

여러분의 피드백은 언제든 환영합니다 만일 App Store 서버에 대한 기능 요청이 있다면 Apple의 피드백 지원을 통해서 알려주세요 WWDC23에서 함께해 주셔서 고맙습니다! ♪ ♪