App Store Server Library 알아보기

♪ ♪

안녕하세요 저는 데이브 웬드랜드입니다 App Store 커머스 팀의 디벨로퍼 애드버케이트죠 제 동료인 알렉스와 함께 새로운 App Store Server Library와 그 여러 기능이 어떻게 여러분의 서버에서 다양한 능력을 발휘하게 하는지 설명하겠습니다 App Store Server API를 위한 JWT 생성부터 구입 확인을 위한 verifyReceipt 엔드포인트에서의 마이그레이션까지 말이죠 지난 역사를 돌아보면 App Store가 출시된 2008년에는 앱이 무료나 유료 둘 중 하나였죠 곧 저희는 앱 내 구입을 추가했고 그 이후로 줄곧 규모와 복잡성 면에서 전 세계의 개발자 커뮤니티가 성장해왔습니다 App Store는 계속해서 개발자와 고객을 위한 업데이트를 제공해 국제적이고 역동적인 모바일 앱 생태계를 지원합니다

2021년에 저희는 차세대 StoreKit 도구와 함께 개편된 StoreKit 프레임워크와 App Store Server API App Store Server Notifications V2를 출시했습니다 2022년과 올해의 WWDC에서도 다시금 업데이트를 추가했죠 이 도구들은 트랜잭션과 서명된 JWS 포맷인 상태 정보를 제공하는데요 이는 개발자에게 클라이언트 측과 서버 측의 풍부한 정보를 전달하기 위해서입니다 이 일련의 API는 App Store Server Library 탄생에 기여했죠 이 라이브러리는 여러 기능을 제공하여 개발자 여러분이 현재와 미래에 준비될 최신 API를 도입하고 통합하는 일이 더 편리해지게 할 겁니다 라이브러리의 베타 출시는 네 가지 언어를 지원합니다 Swift, 자바, 노드 그리고 파이썬이죠 이로써 여러분의 백엔드와 전문성을 가장 잘 지원할 언어를 유연하게 선택할 수 있습니다 GitHub에서 언어별 App Store Server Library를 이용할 수 있으며 여러분의 피드백과 재능 기부를 기다리고 있습니다 저는 라이브러리가 제공하는 기능을 크게 주요 분야 네 개로 나눴습니다 가장 강력한 첫 기능은 App Store Server API와 관련이 있는데요 JWT 생성을 간소화함으로써 App Store Server API가 제공하는 수십 가지 엔드포인트를 쓸 수 있죠

다음은 JWS 서명 데이터를 검증하는 핵심 능력으로 여러분의 트랜잭션과 서버 알림을 반드시 Apple이 생성하고 서명하도록 보증합니다 다음은 영수증 추출 트랜잭션 유틸리티입니다 이 간단한 도구는 앱 영수증에서 트랜잭션 식별자를 추출하는데요 이 기능은 verifyReceipt 엔드포인트를 쓰는 부담을 덜고 App Store Server API로 데이터를 옮겨 구입을 검증하고 추가적인 기능을 쓸 수 있게 합니다 이것은 앱의 현재 및 레거시 버전을 지원하는 명확한 경로를 제공합니다 마지막은 구독 프로모션 특가 시그니처를 만드는 유틸리티입니다 이 유틸리티는 앱 내 구입 프라이빗 키를 이용해 프로모션 특가에 서명하고 생성하는 일을 해줍니다 구독 프로모션 특가 기능을 처음 들으셨다면 '구독 프로모션 모범 사례' 세션에서 알아보세요 이 핵심 라이브러리 기능 중 세 가지를 자세히 살펴보죠 바로 App Store Server API와 서명 데이터 검증 App Store Server API로 이주하기입니다 App Store Server API부터 시작하죠

Server API의 기반은 Get Transaction History 엔드포인트인데요 트랜잭션 ID를 쓰는 것만으로도 이 API는 고객의 전체 앱 내 구입 트랜잭션 기록을 제공합니다 게다가 이 엔드포인트 외에도 더 많은 기능을 갖추고 있죠 이 API에는 수십 가지 엔드포인트가 있고 이것은 모두 일종의 인증이 필요한데 바로 JSON Web Token입니다 여러분의 JWT를 만드는 건 중요한 단계인데요 만일 이 과정에 친숙하지 않다면 바로 그때 라이브러리를 사용하는 겁니다 알렉스가 App Store Server API 사용을 위한 라이브러리 설정을 보여줄 겁니다 안녕하세요, App Store Server 엔지니어인 알렉스 베이커입니다 App Store Server Library를 어떻게 시작하는지 보여드리고 이것으로 App Store Server API를 호출하는 법을 알려드릴 건데요 이 과정에서 App Store Server Library 설정을 위해 필요 정보를 모으는 과정을 함께 보고 API 클라이언트 생성과 API 호출 예시를 보여드리겠습니다 App Store Connect로 들어가 라이브러리에서 App Store Server API 사용에 필요한 정보를 얻을 겁니다 Users and Access 모듈로 가세요

다음엔 Keys 탭을 누르고 앱 내 구입 옵션으로 가세요

여기 몇 가지 유용한 정보가 있네요 첫째로 발급자 ID를 보죠 다음으로 새 프라이빗 키를 생성할 거예요 이름을 짓고 '생성'을 클릭합니다 키를 만들면 두 가지 정보가 생깁니다 키 ID와 프라이빗 키를 다운로드하는 옵션이죠 다운로드는 한 번만 가능합니다 Apple Public Key 인프라스트럭처 사이트로 전환해서 왼쪽 위의 Apple Root Certificates 섹션을 보세요 루트 인증서를 다운받습니다

여기 Gradle 빌드 시스템을 이용한 간단한 자바 프로젝트가 있습니다 먼저 App Store Server Library에 종속성을 추가하세요

ExampleApp 클래스로 넘어가면 제가 이전에 획득한 정보 몇 가지가 보입니다 발급자 ID와 키 ID, 프라이빗 키죠 추가로 앱의 bundleID를 저장하세요

여기에서 저는 샌드박스를 쓰고 있습니다 그리고 적절한 열거형 값을 저장하세요

이러한 정보를 이용하여 AppStoreServerAPIClient를 인스턴스화합니다 이 클라이언트로 Request a Test Notification 엔드포인트를 호출하면 이것이 App Store Server에 TEST 유형을 가진 알림을 App Store Connect에서 설정한 URL로 보내라고 요청할 겁니다 마지막으로는 testNotification Token을 출력하세요 이를 실행하면 testNotification Token이 출력되고 예상대로 이 토큰이 보입니다

이로써 App Store Server Library를 사용해 App Store Server API 사용을 단순화하는 법과 App Store Connect에서 필요한 정보를 알려드렸죠 이제 데이브에게 넘기겠습니다 고마워요, 알렉스 이 시연으로 라이브러리를 이용해 Server API 사용을 위한 JWT 설정과 생성을 얼마나 빨리할 수 있는지 잘 알게 됐네요 이 라이브러리는 저희 API를 도입하며 구현 타임라인을 줄이는 데에 큰 도움을 줄 겁니다 라이브러리를 쓰면 유용하고 간단하긴 하지만 앱 내 구입 프라이빗 키를 안전하게 보관하는 것보다 더 중요한 건 없습니다 만일 키가 유출되었다는 생각이 든다면 App Store Connect에서 언제든 신규 키를 생성하세요 개발을 시작하실 때는 샌드박스와 TestFlight 트랜잭션을 먼저 써보는 걸 추천합니다 마지막으로 반드시 정기적으로 Apple 루트 인증 기관이 업데이트됐는지 확인하세요 지금부터 왜 서명 데이터의 검증이 앱 내 구입 사업에 기초적인 조치인지 알아보죠 먼저 서명 데이터에 무엇이 있으며 왜 중요한지 봅시다 StoreKit 서명 데이터는 그 자체로 App Store에서 JSON 웹 서명 포맷으로 생성하고 서명했으며 앱 구입, 앱 내 구입, 고객 이벤트 고객 구독 상태에 대한 데이터를 포함한다는 걸 나타냅니다 가장 흔한 두 가지 서명 데이터 페이로드는 JWS 트랜잭션과 JWS 갱신 정보입니다 AppTransaction은 처음에 구입한 앱 버전 및 현재 기기에 설치된 버전에 대한 세부 정보를 포함하죠 그 이외에도 App Store Server Notifications V2가 있는데 알림 그 자체가 서명 데이터로서 추가로 JWS 트랜잭션과 JWS 갱신 정보를 포함할 수 있습니다

참고로 알려드리면 여러분은 이 JWS 서명 데이터를 iOS 15 이상의 StoreKit 2와 App Store Server API 및 App Store Server Notifications V2에서만 확인할 수 있습니다

다음의 이벤트 중 하나가 일어날 경우 JWS 서명 데이터를 확인하는 걸 추천해 드립니다 첫째, 기기의 콘텐츠를 전달하거나 잠금 해제할 경우 출처가 여러분의 앱이든 다른 서버이든 아니면 App Store 서버 알림이든 서버가 서명 데이터를 수신했을 경우 마지막으로 App Store Server API에서 응답을 받을 경우입니다 JWS 서명 데이터를 검증하는 법 및 라이브러리가 이를 대신하는 법을 알렉스가 보여드릴 겁니다

이 시간에는 App Store에서 서명 데이터를 검증하는 법을 보여드리겠습니다 여러분이 수행해야 하는 검증 과정을 설명해 드릴게요 그 후엔 App Store Server Library의 SignedDataVerifier 클래스가 이 과정을 대신 수행하는 법을 살펴볼 겁니다 제가 지금 묘사하는 작업 속 프로토콜과 RFC가 익숙하지 않을 때는 App Store Server Library 같은 도구를 활용하는 것을 강력히 추천해 드립니다 여기 App Store에서 보낸 서명 데이터가 있습니다 많은 일이 벌어지고 있는 듯하죠 색깔별로 구분하니 세 가지 섹션이 보이는군요 각 섹션은 마침표로 분리되며 Base64 URL로 인코딩됐습니다 가장 큰 첫 번째 섹션이 헤더입니다 디코딩해 보니 헤더는 JSON 구조로서 JWS 사양으로 정의된 필드가 있습니다 이 경우, 헤더에는 두 가지 필드만 있는데요 첫째는 알고리즘으로 언제나 ES256로 나타나고 두 번째는 x5c라는 필드입니다 이는 인증서의 어레이로 JWS를 서명한 예상되는 공개 키를 산출하는 데 쓰이죠 인증서 체인 구성 과정을 살펴봅시다 어레이 속 첫 번째 인증서는 리프 인증서네요 이 인증서의 공개 키가 JWS에 서명했습니다 이 인증서 출처가 Apple임을 증명하기 위해 알려지고 믿을 수 있는 출처로 이어지는 신뢰 체인을 구성합니다 이 경우에는 바로 Apple 루트 인증 기관이겠죠 다음 어레이의 인증서는 Apple Worldwide Developer Relations 중간 인증 기관입니다 Apple 루트 인증 기관은 개발자에 집중된 특화 버전이라고 생각하세요 체인의 마지막 인증서는 Apple 루트 인증 기관으로 어느 Apple 기관에서 이 체인을 생성했는지 알 수 있습니다 이 인증서가 Apple의 Public Key 인프라스트럭처 사이트에서 이전에 얻은 루트 인증서와 정확히 일치하는지 검증하는 게 중요합니다 첫 단계는 각 인증서가 체인의 이전 인증서에 의해 서명되었는지 검증하는 겁니다 다음으로 추가적인 인증 단계를 수행합니다 예를 들면 각 인증서의 유효 날짜와 적절한 포맷인지 등을 확인하는 겁니다 다음엔 이 인증서들의 출처가 Apple이란 것과 목적이 App Store 데이터에 서명하는 것인지 확인합니다 반대로 관련이 없는 사용 예라면 App Store 데이터에 서명하기에는 유효하지 않겠죠 리프 인증서를 검증하려면 객체 식별자 또는 Mac App Store 영수증 서명을 위한 OID가 있는지 보고 그 목적을 확인합니다 중간 인증서의 경우 Apple Worldwide Developer Relations의 중간 인증 기관 OID를 확인하세요 마지막으로 앞서 언급했듯이 루트 인증 기관이 Apple 루트 인증 기관으로서 저장한 인증서 중 하나인지 확인하세요 이제 리프 인증서를 실제로 디코딩해 보고 이 값을 확인하는 법을 보죠

여기에 OpenSSL x509 커맨드로 생산된 인증서의 X.509 V3 확장 프로그램 섹션이 있습니다

아래쪽은 이전 슬라이드에 나열됐던 OID로서 인증서의 목적이 App Store 영수증 서명임을 나타냅니다 하지만 꼭 확인해야 하는 추가적 필드가 있습니다

여기에 보이는 건 인증 기관 정보 액세스 섹션으로 발급자에 대한 정보를 제공하며 중요하게는 인증서가 취소된 경우 확인해야 할 정보도 제공합니다 온라인 인증서 상태 프로토콜인 OCSP를 사용해서 인증 과정을 진행하기 전에 인증서가 취소됐는지 확인하세요 이를 위한 과정 및 암호화 절차는 RFC 6960에 정의돼 있습니다

인증서 체인을 검증한 후에는 JWS가 리프 인증서의 공개 키로 서명됐는지 확인하세요 이전 단계의 리프 인증서를 가져다가 그 인증서의 공개 키를 추출한 후 키와 원본 JWS를 갖고 이를 JWS 서명 검증 함수에 전달합니다 검증 함수는 데이터가 공개 키로 서명된 걸 확인하고 페이로드를 디코딩합니다 프로세스가 거의 완료됐지만 한 가지 추가 검증 단계가 있습니다 여기에 디코딩된 App Store Server TEST Notification이 있는데요 이전 단계들은 App Store에서 나온 데이터를 검증했습니다 그러나 또한 알림이 올바른 응용 프로그램과 환경을 대상으로 했는지도 확인해야 합니다

appAppleId와 bundleId로 알림이 올바른 응용 프로그램을 대상으로 하는지 확인하세요 환경이 기대하던 것과 일치하는지도 확인하시고요

검증 과정의 여타 단계처럼 App Store Server Library도 또한 검증 시 이것들을 확인합니다

이것으로 App Store의 서명 데이터를 검증하는 프로세스가 완료됩니다 다음으로 앞서 나온 프로젝트를 확장해 서명 데이터를 확인할 건데요 이때 App Store Server Library에 포함된 SignedDataVerifier 클래스를 이용하겠습니다 SignedDataVerifier 클래스는 앞서 다룬 검증 단계를 수행합니다

이번 시연에서는 먼저 요청했던 테스트 알림을 얻고 그 후엔 서명된 알림을 확인하고 디코딩할 겁니다 테스트 알림의 요청과 서버로의 알림 수신 사이에 약간 지연이 있는데요 이를 반영하여 지연 시간 5초를 추가합니다 다음은 앞에서 얻은 testNotificationToken을 이용해 Get Test Notification Status 엔드포인트를 호출합니다 마지막으로 알림의 첫 몇 글자를 출력해 성공인지 확인합니다 Get Test Notification Status 엔드포인트는 알림 페이로드뿐만 아니라 보내기 시도의 결과도 반환합니다 이 페이로드의 시작 부분이 보여야 합니다

예상대로 알림의 첫 몇 글자가 보이는군요 넘어가서 서명 데이터 검증자를 만들어 봅시다 이 작업에는 세 가지 정보가 필요한데 Apple 루트 인증 기관 목록부터 시작하죠

제가 전에 다운받은 인증서들이 리소스 폴더에 들어 있습니다 루트 인증서를 Set로 가져오죠 샌드박스를 쓰고 있기 때문에 앱의 Apple ID가 없어도 됩니다 null을 대신 샌드박스에 넘깁니다 마지막으로 취소 확인을 할지 정합니다 알림을 방금 수신했기 때문에 onlineChecks가 true일 겁니다 몇 달 또는 몇 년 전에 수신한 알림의 경우 인증서가 만료됐을 수 있기 때문에 값이 false여야 하죠 이 필드를 새로운 SignedDataVerifier에 넘깁니다 그 후엔 앞서 수신한 알림에 전달하고 결과를 출력한 다음 프로그램을 실행합니다

프로그램이 일단 완료되면 검증되고 디코딩된 알림이 보일 겁니다 이것은 테스트 알림이기 때문에 TEST 유형 및 페이로드에 포함된 앱의 번들 식별자를 다른 몇몇 필드와 함께 포함할 겁니다

예상대로 TEST 유형의 디코딩된 알림이 보이네요

이전의 시연을 확장해서 Signed DataVerifier 객체를 설명했는데요 이제 데이브가 모범 사례를 몇 개 보여드릴 겁니다 세상에, 서명 데이터를 검증하는 데 필요한 모든 단계와 라이브러리가 이 번잡한 일을 어떻게 대신해 주는지 정말 잘 알 수 있었는데요 이처럼 서버 측 확인을 위해 SignedDataVerifier를 꼭 이용해 주세요 유념해야 할 점은 데이터를 검증할 때 여전히 직접 앱과 제품 식별자를 확인해서 앱이나 서비스가 맞는지 보고 구입을 승인하거나 취소해야 한다는 겁니다 마지막으로 인증서가 만료되어 취소될 수 있으므로 클라이언트 측이든 서버 측이든 인증서를 하드 코딩 하지 말고 항상 활성화 상태인지 확인하세요 이제 서버 측 앱 영수증 확인을 verifyReceipt 엔드포인트에서 App Store Server API로 옮기는 걸 도와줄 또 다른 App Store 서버 유틸리티를 보겠습니다 App Store Server Library는 특별히 이 마이그레이션을 돕고 어떤 앱도 낙오되지 않게 하는 유틸리티를 제공합니다 App Store Server API로 옮기는 걸 고려한다면 이 작업을 여러분의 계획에서 우선시하는 이유가 많겠죠 API는 구입 검증을 지원하며 고객 지원 및 유화책과 App Store Server Notification V2 테스트에 유용한 추가 엔드포인트를 포함합니다 계속해서 업데이트하고 새 프로퍼티를 출시함에 따라 이 기능들은 오로지 JWS 서명 데이터에만 공개되며 이를 StoreKit 2와 App Store Server API 및 App Store Server Notifications V2가 지원합니다 부가적인 이점 하나는 여러분이 원본 트랜잭션 ID나 트랜잭션 ID만 기록하면 된다는 겁니다 더 이상 Base64 인코딩 영수증을 여러분의 계좌 시스템에 저장하지 않아도 됩니다 저희가 최신 API에 끊임없이 투자한 결과 verifyReceipt 엔드포인트가 지원 중단을 앞두게 되었습니다 더 알고 싶다면 'App Store Server API의 새 기능' 세션에서 자세한 업데이트와 안내를 확인하세요 이제 알렉스가 어떻게 App Store Server Library가 마이그레이션을 돕는지 설명할 겁니다 알렉스, 부탁해요 고마워요, 데이브 이제 앱 영수증에 대한 플로차트를 함께 살펴봅시다 StoreKit 2와 App Store Server API가 훌륭한 도구이긴 하지만 오래된 기기의 클라이언트나 최신으로 업데이트하지 않은 사용자를 지원하는 건 중요하죠 이 때문에 오로지 앱 영수증만이 서버에 제공될 수 있는데요 이 기기들이 어떻게 이전에 지원됐는지 보여드리고 verifyReceipt의 지원 중단 후에도 이 클라이언트를 계속 지원하는 법을 알려드리겠습니다

먼저 기기에서 여러분의 서버로 영수증을 보냅니다 오래된 모델에서는 서버가 이 영수증을 verifyReceipt에 전달하고 그 후 디코딩된 영수증을 받죠

응답은 originalTransactionId를 포함하는데 이는 App Store Server API에 있는 Get Transaction History 엔드포인트로 전달됩니다 App Store Server는 고객에게 서비스를 제공하는 데 쓰는 서명된 트랜잭션을 반환합니다 이제 verifyReceipt가 지원 중단 예정이므로 이 부분을 교체해 봅시다 App Store Server Library의 영수증 유틸리티는 영수증에서 직접 트랜잭션 ID를 추출합니다 여러분은 트랜잭션 ID를 App Store Server API에 전달하여 두 번 왕복하는 번거로움을 없앱니다 이후에는 엔드포인트의 변경 내용을 저장합니다 이로써 전체 기록을 매번 다시 파싱하지 않아도 됩니다

앱 영수증에서 추출된 값이 원본 트랜잭션 ID일 수도 아닐 수도 있기 때문에 Get Transaction History 엔드포인트를 비롯한 많은 엔드포인트가 원본 트랜잭션 ID만이 아니라 어떤 트랜잭션 ID라도 매개변수로서 지원하도록 저희가 바꾸었습니다 이제 Get Transaction History 엔드포인트 사용을 위해 App Store Server Library를 이용하여 트랜잭션 ID를 추출하는 법을 알려드릴게요 여기서 앱 영수증을 가져가 트랜잭션 ID를 추출하고 이 ID로 Get Transaction History 엔드포인트를 호출할 겁니다 먼저 앱 영수증부터 시작하죠 기기나 App Store Server Notification V1에서 앱 영수증을 받을 수 있는데요 이미 여기에 받아두었습니다 다음으로 ReceiptUtility 클래스에서 인스턴스를 생성합니다 트랜잭션 ID를 추출하려면 앱 영수증 메서드에서 트랜잭션 ID 추출을 호출합니다 모든 영수증에 트랜잭션 ID가 있지는 않을 겁니다 사용자 구입 내역이 아예 없을 수도 있죠 따라서 null 확인을 추가합니다

이 문제의 정보를 더 자세히 얻기 위해서 이 사용자의 가장 최신 소모성 제품 구입에 대한 정보를 얻고 취소된 소모성 제품 구입은 제외한다고 가정해 보죠 Transaction History Request 객체를 생성하고 소모성 유형의 제품만을 원한다고 명시하여 취소된 트랜잭션을 제외하고 데이터를 내림차순으로 반환하도록 지정합니다

두 헬퍼 객체가 필요한데 바로 응답 변수와 트랜잭션 목록입니다 do while 루프가 Transaction History 엔드포인트를 훑습니다 만일 이것이 첫 요청이 아니라면 변경 토큰을 이전 응답에서 가져와 데이터를 계속 훑습니다 그 후엔 Get Transaction History 엔드포인트를 앱 영수증의 트랜잭션 ID와 요청 객체 변경 내용으로 호출합니다 끝으로 응답 속 모든 트랜잭션을 트랜잭션 목록에 추가합니다 hasMore 필드가 응답에서 false일 때까지 이를 반복하세요 결과를 보려면 트랜잭션을 출력하세요

여기에 API에서 반환된 트랜잭션 목록이 보이는군요 이전 시연의 SignedDataVerifier를 이용해 이걸 디코딩할 수도 있습니다

App Store Server API로 앱 영수증을 쓰는 법에 대한 마지막 시연을 함께해 주셔서 감사합니다 데이브가 마무리하겠습니다 새로운 App Store Server Library가 정말 기대되는데요 신규 기능으로 API의 도입이 쉬워지고 App Store Server API로의 전환이 일어나겠죠 여기 GitHub의 App Store Server API 자바 리포지토리 캡처 화면이 있습니다 이 페이지에서 저희 문서의 링크를 찾고 끌어오기 요청을 하며 라이브러리 사용법의 예시를 찾을 수 있습니다 App Store Server Library 베타 버전도 곧 다운받아 App Store Server API 도입 계획을 시작하실 수 있습니다 여러분의 피드백과 기능 요청을 기다리겠습니다 피드백 지원과 GitHub를 통해 저희에게 연락 주세요 고맙습니다 ♪ ♪