App Store Serverライブラリについて

♪ ♪

こんにちは Dave Wendlandです App Store Commerceチームで デベロッパアドボカシーを推進しています 同僚のAlexと私は 新しい App Store Serverライブラリと その一連の機能が App Store Server API用のJWTの 生成から購入検証のための verifyReceiptエンドポイントからの 移行まで サーバが一連の機能を 利用できるようにする方法について 説明します 振り返ってみると App Storeがスタートした2008年は アプリが無料か有料かのどちらかでした すぐにアプリ内課金が追加され それ以来 デベロッパコミュニティは世界中で 規模を拡大し 複雑さを増しています App Storeは グローバルでダイナミックな モバイルアプリのエコシステムを サポートするため デベロッパとカスタマーに アップデートを提供し続けています

2021年 StoreKit Framework App Store Server API App Store Server Notifications v2を 刷新し StoreKitツールの次世代を リリースしました 2022年にさらなるアップデートがあり WWDC23でも再びアップデートがありました これらのツールは 署名された JWSフォーマットで トランザクションとステータスを提供します また クライアントサイド サーバサイドを問わず デベロッパに 堅固な情報を提供するように 設計されています この一連のAPIが App Store Server ライブラリに新たな利点を与え 現在および将来的に利用できる最新APIを デベロッパコミュニティが簡単に採用し 統合できるようにするための一連の機能を このライブラリが提供します ライブラリのベータ版は Swift Java Node Pythonの 4つの言語をサポートします バックエンドやデベロッパの専門知識に 適した言語を柔軟に選択できます 各言語のApp Storeサーバライブラリは GitHubで公開していますので フィードバックや投稿を お待ちしています ライブラリが提供するものを 4つの主要機能に 分類してみました 最初の そして最も堅固な機能は App Store Server APIです JWTの作成を効率化することで App Store Server APIが提供する 何十種類ものエンドポイントの どれでも使うことができます

次に JWS署名付きデータを検証する コア機能です これにより トランザクションと サーバ通知がAppleによって生成され 署名されていることを確認できます 次に レシート トランザクションの 抽出ユーティリティです このシンプルなツールは アプリの レシートから取引識別子を抽出します こうすることで verifyReceipt エンドポイントを使用する 必要性を軽減し 購入検証や 追加機能のために App Store Server APIに移行できます これで アプリの現バージョンと 旧バージョンに対応する明確な道が開けます 最後にサブスクリプションのプロモーション 署名を生成するユーティリティです このユーティリティは アプリ内課金の 秘密鍵を使用して オファーの署名と生成の 難しいタスクを行います サブスクリプションのプロモーション オファーについてご存じない方は 詳細を"Subscription Offers Best Practices"でご確認ください では ライブラリのコア機能のうち3つを 深く掘り下げてみよう App Store Server API 署名付きデータ検証 App Store Server APIへの移行です さっそくApp Store Server APIから 始めましょう

Server APIの基本は Get Transaction Historyエンドポイントです トランザクションIDを使用するだけで このAPIはカスタマーの完全な アプリ内課金トランザクション履歴を 提供します そして このエンドポイント以外にも さらに多くの機能を備えています このAPIには12個のエンドポイントがあり そのすべてにJSON Web Tokenという 認証が必要です JWTの生成は重要なステップであり このプロセスに慣れていない場合は ライブラリの出番となります AlexがApp Store Server APIで 使用するためのライブラリの セットアップを実演してくれます こんにちは Alex Bakerです App Store Serverのエンジニアです ここでは App Store Serverライブラリの 始め方と それを使ってApp Store Server APIを 呼び出す方法を紹介します このデモでは App Store Server ライブラリを構成するために 必要な情報を収集し APIクライアントを作成してAPIを 呼び出す例を実地検証します ライブラリを使用してApp Store Server APIを使用するために 必要な情報を取得するため App Store Connectから始めます 「ユーザーとアクセス」セクションに 移動します

次に「キー」タブをクリックし アプリ内課金オプションを選択します

ここには有益な情報がいくつかあります まず 発行者IDです 次に 新しい秘密鍵を生成します 名前を付けて Generateをクリックします 鍵を生成すると 2つの情報が提供されます： キーIDと秘密鍵をダウンロードする オプションです ダウンロードは1回のみ可能です Apple Public Key infrastructureの Webサイトに移動し 左上のApple Root Certificates セクションに注目します ルート証明書をダウンロードしてください

これは Gradleビルドシステムを使った シンプルなJavaプロジェクトです まず App Store Serverライブラリへの 依存関係を追加します

ExampleAppクラスに移ると ここに先ほど取得した数個の情報 issuerId keyId 秘密鍵があります さらに アプリのbundleIdを保存します

このデモでは Sandboxを使って 適切な列挙値を格納します

これらの情報を使用して AppStoreServer- APIClientをインスタンス化します このクライアントでRequest a Test Notificationエンドポイントを呼び出し App Store Connectで設定したURLに TESTタイプの通知を送信するよう App Storeサーバに要求します 最後に testNotificationToken を表示します これを実行すると testNotificationTokenが出力され 予想通りこのトークンが表示されます

これは App Store Server APIと App Store Connectから必要な情報を 簡単に使用するために App Store Serverライブラリの 使用方法を示したものです さて Daveに話を戻します Alex ありがとう このデモは このライブラリが いかに素早くセットアップでき Server APIで使用するためのJWTを 生成するかを如実に示しています このライブラリは AppleのAPIを採用する際 実装のタイムラインを短縮する上で 有意義な効果をもたらします ライブラリの利用は便利で簡単ですが アプリ内課金の秘密鍵を 安全に保管することほど 重要なことはありません また キーが不正アクセスされたと 思われる場合は App Store Connectでいつでも 新しいキーを生成できます 開発を始める際には Sandboxと TestFlightトランザクションから 始めることをおすすめします そして最後に Appleの ルート証明機関の最新情報を 定期的にチェックしてください では なぜ署名付きデータ確認が アプリ内課金での ビジネスの基本的アクションなのかを 説明しましょう まず 署名付きデータの内容と その重要性を説明しましょう StoreKit Signedデータとは App Storeによって JSON Web Signature形式で 生成および署名され アプリ購入 アプリ内課金 カスタマー イベントやサブスクリプション状況に関する データが含まれていることを意味します 最も一般的な2つの 署名付きデータペイロードは JWS Transactionと JWS Renewal Infoです そしてappTransactionには 最初に購入したアプリのバージョンと 現在デバイスにインストールされている バージョンの 詳細が含まれます そして App Store Server Notifications V2 があり 通知自体は署名付きデータで さらにJWS Transactionと JWS Renewal Infoを含むことがあります

そして注意事項として iOS 15以降のStoreKit 2および App Store Server APIと App Store Server Notifications v2 でのみ このJWS署名付きデータを見ることが できます

以下のいずれかの事象が 発生した後に JWS署名付きデータを 検証することを推奨します： デバイス上でコンテンツを 配信またはロック解除する場合 または ご自身のアプリ 他のサーバ またはApp Storeサーバの 通知からであるかにかかわらず デベロッパのサーバが署名付きデータを 受信した場合 そして最後に App StoreサーバAPIから レスポンスを受信した場合 ではここでAlexが JWSの署名付きデータを検証する方法と ライブラリがこれをどのように処理するかを デモします

このセクションでは App Storeから 署名付きデータを検証する方法を 紹介し 実施すべき検証プロセスについて 説明します 次に App Store Serverライブラリの SignedDataVerifierクラスが どうこの処理を行うかを説明します これから説明する操作の背後にあるRFCや プロトコルに精通していない場合は App Store Serverライブラリのような ツールを使用することを強くおすすめします これはApp Storeの署名付きデータです いろいろなことが起こっているようです 色分けにより 3つのセクションが あることがわかります 各セクションはピリオドで区切られ Base64 URLエンコードされています 最初で最大のセクションはヘッダーです デコードされると ヘッダーはJWS仕様で定義された フィールドを持つJSON構造となります この場合 ヘッダーには 2つのフィールドのみがあります まずアルゴリズム これは常にES256です 次にx5cというフィールドがあります これは JWSに署名した公開鍵を 計算するために使用される 証明書の配列です 証明書チェーンの構築プロセスを 復習しましょう 配列の最初の証明書がリーフ証明書です この証明書の公開鍵はJWSに署名しました この証明書がAppleから 発行されたものだと確認するには 既知の信頼できるソース この場合は Appleのルート認証局にさかのぼって 信頼の連鎖を構築します 配列の次の証明書は Apple Worldwide Developer Relations 中間認証局です これは デベロッパ向けに特化した Apple Root Certificate Authorityの より専門的なバージョンだと考えてください チェーンの最後の証明書はAppleの ルート認証局であり どのApple認証局が このチェーンを生成したかを 理解できるようになっています この証明書が 以前Apple's Public Key Infrastructure Webサイトから取得した ルート証明書と正確に一致していることを 確認することが重要です 最初のステップは 各証明書が チェーン内の前の証明書によって 署名されているかを検証することです その後 各証明書の日付が有効であること 書式が適切であることなどを 確認するような 追加の検証ステップを実行します 次に これらの証明書が Appleのものであること および その目的がApp Storeデータへの 署名であることを検証します これは App Storeデータへの署名が無効な 無関係なユースケースでは ないことを確認します リーフ証明書を検証するには Mac App Store Receipt Signingの オブジェクト識別子（OID）の存在を 確かめることで その目的を確認します 中間証明書については Apple Worldwide Developer Relationsの 中間機関のOIDを確認してください 最後に 前述したように ルート認証局が Apple Root Certificate Authorityとして 保存した証明書の1つであることを 確認してください では実際にリーフ証明書をデコードして これらの値をチェックする方法を 観察してみましょう

これは OpenSSL x509コマンドによって 生成された証明書のX.509 v3 拡張セクションです

一番下には 前のスライドに記載した OIDがあり 証明書の目的がApp Storeの レシート署名であることを示しています しかし チェックすべき重要な 追加フィールドがいくつかあります

ここには 発行者についての情報を提供する 権威情報アクセスセクションがあり 重要な点として 証明書が失効したかどうかを 確認するための情報を提供しています Online Certificate Status Protocol （OCSP）を使用します 検証プロセスを進める前に 証明書が失効していないかを確認します そのためのプロセスと暗号化手順は RFC 6960で定義されています

証明書チェーンを検証した後 JWSがリーフ証明書の公開鍵によって 署名されていることを確認します 先ほどのリーフ証明書を取り出し リーフ証明書の公開鍵を抽出し 鍵とオリジナルのJWSを取り出し JWS署名検証機能に渡します 検証機能は データが公開鍵によって 署名されていることをチェックし ペイロードをデコードします プロセスはほぼ完了しましたが 1つ追加の確認ステップがあります これは デコードされたApp Store Server TEST Notificationです これまでの手順で データが App Storeから来たことを確認しました ただし その通知が 正しいアプリと環境を 対象としていることも確認してください

appAppleIdとbundleIdをチェックして 通知が正しいアプリを 対象にしていることを確認してください 環境が期待される環境と 一致していることを確認します

検証プロセスの他のステップと同様に App Store Serverライブラリも 検証を実行する際にこれらをチェックします

これで App Storeから署名付きデータを 確認するプロセスは完了です 次に App Store Serverライブラリの SignedDataVerifierクラスを使って 署名付きデータを検証するために 先ほどのプロジェクトを発展させてみます SignedDataVerifierクラスは 以前に説明した検証ステップを実行します

このデモでは 先にリクエストした テスト通知を取得し 署名付き通知を検証してデコードします テスト通知をリクエストしてから 私のサーバで通知が受信されるまでに 少し遅延があります そのため 5秒の遅延を追加します 次に 先ほど取得した testNotificationTokenを使用して Get Test Notification Status エンドポイントを呼び出します 最後に 通知の最初の数文字を印刷して 成功を確認します Get Test Notification Status エンドポイントは 通知ペイロードと同様に 送信試行の結果を返します そのペイロードの冒頭が 表示されているべきです

予想通り 通知の最初の数文字が見えます 続いて 署名付きデータのverifierを 作成します これには3つの情報が必要で まずAppleルート認証局のリストから 始めます

先ほどダウンロードした証明書が リソースフォルダに入っています ルート証明書をセットにインポートします Sandboxを使っているので アプリのApple IDは必要ありません Sandboxでは代わりにnullを渡します 最後に 失効チェックを行うかどうかを 指定します 通知を受け取ったばかりなので onlineChecksはtrueでなければいけません 数カ月あるいは数年前に受け取った 通知については 証明書の有効期限が切れている可能性が あるため これはfalseとすべきです これらのフィールドを新しい SignedDataVerifierに渡します そして 先ほど受け取った通知を渡し 結果をプリントして プログラムを実行します

プログラムが完了すると 検証されデコードされた通知が 表示されます これはテスト通知なので ペイロードにはTESTタイプと アプリのバンドルIDがあり その他いくつかのフィールドがあります

予想通り デコードされた TESTタイプの通知が表示されました

前回のデモを発展させ SignedDataVerifier オブジェクトの実証を行いました ここでDaveがベストプラクティスを 復習します 素晴らしいですね 署名付きデータを検証するために 必要なすべてのステップと ライブラリがその複雑性をどのように 処理できるか明確になりました サーバサイドの検証には SignedDataVerifierを 利用してください 重要な注意事項として データを確認する際には アプリIDやプロダクトIDを検証して アクセス許可や取り消しが 正しいアプリやサービスの購入を対象に 行われていることを確認してください 最後に 証明書は失効し 取り消される可能性があるため クライアント側でもサーバ側でも 証明書をハードコードせず 常に証明書が有効であることを 検証してください ここで サーバ側のアプリのレシート検証を verifyReceiptエンドポイントから App Store Server APIに移行するための もう1つのApp Storeサーバ ユーティリティを確認します App Store Serverライブラリは この移行に特化した ユーティリティを提供し 取り残されたアプリがないようにします App Store Server APIへの 移行を検討する際 ロードマップの中でこの作業を 優先すべき理由はたくさんあります このAPIは、購入の検証をサポートし カスタマーサポート 緩和 App Store Server Notifications V2の テストに役立つ追加のエンドポイントを 含んでいます 今後もアップデートを続け 新しい プロパティをリリースする予定ですが これらはStoreKit 2 App Store Server API および App Store Server Notifications V2 でサポートされている JWS署名付きデータでのみリリースされます 追加の利点として 記録する必要がある唯一のデータは オリジナルのトランザクションID またはトランザクションIDのみです Base64エンコードされた領収書のアカウント システムへの保存が不要になりました また 最新のAPIへの継続的な投資により verifyReceiptエンドポイントが 非推奨となったことを発表しました 詳細については、"What's new in App Store server APIs"で 最新情報とガイダンスをご確認ください さて ここでAlexが App Store サーバライブラリが 移行をどのように サポートするかを紹介します ではAlex ありがとう Dave では App Receiptsのフロー図を 見てみましょう StoreKit 2とApp Store Server APIは 素晴らしいツールですが 古いデバイスのクライアントや 最近アップデートしていないユーザーを サポートすることが重要です また App Receiptsのみがサーバに 提供される場合もあります これらのデバイスが以前は どのようにサポートされていたのか そしてverifyReceiptの非推奨化に伴い これらのクライアントのサポートを どのように継続できるのかを紹介します

まず デバイスはレシートを サーバに送信します 旧モデルでは サーバはこのレシートを verifyReceiptに渡し デコードされたレシートを受け取ります

レスポンスには originalTransactionIdが含まれ これはApp Store Server APIの Get Transaction History エンドポイントに渡されます App Store Serverは カスタマーへのサービス提供に使用する 署名付きトランザクションを返します verifyReceiptが非推奨になったので このセクションを置き換えましょう App Store Serverライブラリの レシートユーティリティは レシートからトランザクションIDを 直接抽出します トランザクションIDを App Store Server APIに渡すことで 2往復する必要がなくなります この後 エンドポイントから リビジョンを保存します これにより 毎回全履歴を 再パースする必要がなくなります

アプリのレシートから抽出された値は オリジナルトランザクションIDの場合と そうでない場合がありますが 今回 Get Transaction History エンドポイントを含む オリジナルトランザクションID以外の 多くのトランザクションIDも パラメータとして サポートするようになり 皆さんに朗報です 次に App Store Serverライブラリの Get Transaction History― エンドポイントで 使用する トランザクションIDの抽出デモを行います ここでは アプリのレシートを受け取り トランザクションIDを抽出して そのIDを使ってGet Transaction Historyエンドポイントを呼び出します まず App Receiptです デバイスまたはApp Store Server Notifi- cation V1からApp Receiptを取得できます すでに1つここにあります 次に ReceiptUtilityクラスの インスタンスを作成します トランザクションIDを抽出するには アプリのレシートからトランザクションIDを 抽出するメソッドを呼び出します すべてのレシートにトランザクションIDが あるわけではありません ユーザーが購入していない可能性もあります そのため nullチェックを追加します

この問題にもう少し深みを持たせるために このユーザーの最新の消耗型プロダクトに 関する情報を取得し アクセスが失効した消耗型プロダクトを 除外したいとします Transaction Historyオブジェクトを 作成し 失効したトランザクションを 除外するために CONSUMABLEタイプの プロダクトのみを要求し データを降順で返すように指定します

2つのヘルパーオブジェクト レスポンス変数と トランザクションのリストが必要です Transaction History エンドポイントからの レスポンスにループする間実行します これが最初のリクエストでない場合 データをページングし続けるために 前のレスポンスからリビジョントークンを フェッチします 次に アプリレシートのトランザクションIDと リクエストオブジェクト そしてリビジョンを 使用して Transaction History エンドポイントを呼び出します 最後にレスポンスから全トランザクションを トランザクションリストに追加します レスポンスのhasMoreフィールドが falseになるまで繰り返します トランザクションをプリントアウトして 結果を確認します

ここにAPIから返された トランザクションのリストがあります これは 前のデモの SignedDataVerifierを使って デコードすることができます

App Store Server APIで App Receiptsの使用方法を紹介する 最後のデモにご参加いただき ありがとうございました 最後にDaveに話を戻します 新しいApp Store Serverライブラリには 本当に期待しています これらの機能により AppleのAPIの採用や App Store Server APIへの移行が 容易になると考えています 以下は Github上の App Store Server APIの Javaリポジトリのスクリーンショットです このページでは 私たちのドキュメントへのリンク プルリクエストの提出 ライブラリの 使用例を見つけることができます App Store Serverライブラリの ベータ版をすぐにダウンロードして App Store Server APIの採用計画を 始めることができます みなさまからのご意見 ご要望を お待ちしています ぜひ フィードバックアシスタントや Githubにご連絡ください ご視聴ありがとうございました ♪ ♪