App Store Server APIの新機能

♪ ♪

みなさん こんにちは App Storeサーバチームの エンジニア Ianです 今日は 新機能や重要なアップデートを含む アプリ内課金用サーバAPIに関する エキサイティングなアップデートを 紹介します なじみのない方もいるかもしれませんが アプリ内課金をサーバ上で 最大限に活用するためのAPIを主に 2つ提供しています 一つ目は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を ポーリングすることなく 分単位のアップデートを取得できます

通知は サブスクリプションの更新 有効期限 返金など 包括的なイベントをカバーしています

これらにより アプリ内課金の ライフサイクルを完全に追跡できるため ユーザーの行動をよりよく理解し 対応することができます

App Store Server APIと App Store Server Notifications V2は 多くの優れた機能を共有しています どちらもトランザクションデータを 使い慣れた JSONフォーマットで提供し データは署名されているので Appleからであることを確信できます StoreKit 2または original StoreKit APIを使用する アプリをサポートするために 両方のAPIを使用することもできます またみなさまからのフィードバックに基づき これらのAPIを新しい機能で 積極的にサポートしています

本日App Store Server APIと App Store Server Notifications V2の 一連の最新アップデートの コレクションをお知らせします

たくさんの新機能があるので 今日のセッションではほんの少ししか 説明する時間がありません これらの新機能の詳細については デベロッパ向けドキュメントを ご覧ください それでは App Storeサーバのアップデートの 素晴らしい世界に飛び込んでみましょう 本日はアップデートを3つに分けて 紹介します まず サーバ上でトランザクションを より簡単に扱うための新機能について 詳しく説明します 次に ユーザーのサブスクリプションの ステータスを確実に判断するのに役立つ App Store Server Notificationの 機能強化について説明します そして最後に 古いAPIからの移行に関する 重要な最新情報を提供します トランザクションから始めましょう トランザクションは アプリ内課金の 核となるデータオブジェクトです これらはデバイスでのアプリ内課金を表し プロダクトID 種類 購入日など 多くの購入に関する 重要な情報が含まれています

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だけです

すべてのtransactionIdsは プロダクトタイプやユーザーのデバイス上の トランザクションの 終了ステータスに関係なく サポートされます そう このエンドポイントから完成した 消耗型トランザクションを 取得することもできます

新しいエンドポイントがどのように 機能するのか 簡単に見てみましょう App Storeサーバの この新しいエンドポイントに transactionIdをパスパラメータとして GET requestを送信します

signedTransactionInfo列を含む レスポンスを受け取ります

signedTransactionInfoを デコードすることで リクエストで 指定したIDのトランザクション情報を 見ることができます

それで終わりです 新しいGet Transaction Info エンドポイントは非常にシンプルですが サーバ上のトランザクションを扱う際の 柔軟性を高めます 様々なケースで役に立つと思います さて 柔軟性というテーマをさらに 発展させてみましょう

App Store Server APIの 評判のよい エンドポイントはご存知かもしません

これらのエンドポイントはそれぞれ originalTransactionIdを パスパラメータとして必要とします IDはどのユーザーにデータを要求または 送信しているかをサーバに示します

しかし 常にoriginalTransactionIdが 手元にあるとは限りません トランザクションIDしかない場合は どうればよいでしょうか originalTransactionIdを取得するために 新しいGet Transaction Infoエンドポイントに それを送信することができますが なぜ1つのエンドポイントを呼び出すために 別のエンドポイントを呼び出すのでしょうか 代わりに今日からこれらのエンドポイントを transactionIdで呼び出すことができます

以前と同じように リクエストのパスに IDを入力するだけです この柔軟性の向上により App Store Server APIの コアエンドポイントを これまでより簡単に 呼び出せることを期待しています また すでにこれらのエンドポイントを originalTransactionIdsで 呼び出している場合でも 同様に機能し続けるので 心配はいりません では App Store Server Notificationsに 届くアップデートに話を移しましょう アプリが自動更新サブスクリプションを 提供している場合 それらのサブスクリプションの ステータスと時間の経過とともに どのように変化するかを 追跡することが重要です ここでは サブスクリプションの 5つのステータスを見ることができます App Store Server Notifications V2を 使用すると このステータスの変化につながる イベントの通知を迅速に 受け取ることができるため 適切なタイミングでコンテンツを 迅速に有効化および無効化し スムーズなユーザーエクスペリエンスを 維持できます

通知がどのように サブスクリプションのステータスに関する 情報を知らせることができるか 見てみましょう 多くの通知イベントは それらのタイプとサブタイプを通して サブスクリプションのステータスを 直接示します 例えば このサブタイプINITIAL_BUYの SUBSCRIBED通知を見てみましょう

この通知は プロダクトへの 新しいサブスクリプションを示し サブスクリプションのステータスが アクティブであることを示します

ここに 通知タイプがEXPIREDの場合の シンプルな例があります

これは 関連するサブスクリプションの ステータスが「期限切れ」になったことを 明確に示しています

しかし 一部の通知については サブスクリプションステータスが あまり明確でない場合があります 例えば この返金の通知です この通知タイプは アプリ内課金の返金が 行われた場合に送信されます この通知のsignedTransactionInfoを チェックすることで 返金された購入品がわかります

この場合 返金は自動更新 サブスクリプションに対するものなので サブスクリプションのステータスの 記録を更新したいと思います

ステータスが "Revoked "に なったと思いがちですが 必ずしもそうではありません 同じoriginalTransactionIdを持つ より最近の サブスクリプション更新購入がある場合 サブスクリプションのステータスはまだ アクティブの可能性があります その場合は サブスクリプション コンテンツへのアクセスを 無効にすべきではありません

この状況では サブスクリプションの ステータスは単に不明確であり 通知内のデータだけでは 更新するのに十分ではありません これは理想的とは言えません App Storeサーバからサブスクリプションの 通知を受け取る際 サブスクリプションの最新の ステータスを明確に示すことで サーバ上でこの重要な情報を常に 最新の状態に保つことができます

そこで本日 App Store Server Notifications V2の データオブジェクトに新しい ステータスフィールドを導入します このフィールドは 先に詳述した サブスクリプションの 5つのコアステートのうちの 1つを示す単純な整数です

この新しいフィールドは 自動更新サブスクリプションのために送信する すべての通知に含まれます これで App Store Server APIの Get All Subscription Statusesエンドポイントを 呼び出さなくても サブスクリプションのステータスを 取得できるようになりました この新しいフィールドが 先に説明した シナリオをどう改善するか見てみましょう これで サブスクリプションの 返金通知を受け取ったときに ステータスフィールドをチェックするだけで サブスクリプションのステータスを 把握できるようになりました

この場合は1なので 関連するサブスクリプションが アクティブだとわかります

新しいステータスフィールドでは App Store Server Notificationsが これまで以上に役に立ちます とても便利なので いずれも見逃さないようにしましょう しかし サーバーに障害が発生した場合 App Storeサーバに 通知が届かない可能性があります

そのため App Store Server APIの Get Notification Historyエンドポイントを 提供しています

このエンドポイントを使用すると App Storeサーバがアプリ用に生成した バージョン2の通知を 過去6カ月分まで要求できます

そうすることで サーバーに既知の停止が発生した場合 停止期間中に このエンドポイントを呼び出し サーバーが見逃した通知を 取得することができます

しかし 使用例によっては このプロセスはあまり効率的でないと 感じるかもしれません ときには停電時以外でも 一過性のネットワークの問題などで サーバーが通知を見逃すことがあります このような状況では エンドポイントに問い合わせる 明確な期間がないため サーバがすでに受信している通知を 何ページにもわたって 選別する必要があります このユースケースに対応するため Get Notification Historyに "onlyFailures"という新しい リクエストフィールドを導入します

このオプションフィールドは 返される通知を サーバに 到達できなかったものだけに制限します 応答には 現在再試行中の通知も 含まれます

サーバがまだ確かめていない通知だけを 解析すればよいので 停電や時折発生するネットワーク問題から の復旧が格段に速くなります この新しいフィールドがどのように 機能するのか見てみましょう Get Notification Historyエンドポイントに リクエストを送信し リクエストボディに新しいフィールド onlyFailuresを含めます

これがその応答です

notificationHistory配列の各エントリは notificationを表し リクエストに 新しいonlyFailuresフィールドが 含まれているので ここにリストされている すべての通知が サーバに到達できませんでした 一つの通知項目を拡大してみましょう

ここにsignedPayloadがあります この文字列をデコードして サーバに最初に送られたのと同様に 通知の内容を見ることができます

この通知のsendAttempts配列を見てみると 各送信試行の結果を見ることができます この配列は最大6つのエントリーを 含むことができ 最初の送信試行に1つ 再試行には最大5つの エントリーを含むことができます

ここでは 2つのエントリーだけが表示され 両方とも失敗しているので 通知はまだ再試行プロセスにあるはずです 後の再試行が成功した場合 onlyFailuresフィールドを含む それ以降のリクエストでは この通知は表示されなくなります これが新しいonlyFailuresフィールドの 仕組みです Get Notification Historyがさらに 便利になることがわかると思います

最後に 古いAPIからの移行に関する 重要なアップデートです アプリ内課金を提供しているアプリであれば verifyReceipt APIをご存知でしょう

2021年に App Store Serverから アプリ内課金データを取得する 新しい方法として App Store Server APIを リリースしました この2つのAPIを比較してみましょう

verifyReceiptを使用すると StoreKitの オリジナルバージョンを実行している クライアントから受信したレシートを 検証しデコードできます App Store Server APIでは これら3つのエンドポイントを使用して レシートに記載されているのと 同じデータをすべて取得できます また App Store Server APIは 他にはない有用なデータや 強力な機能を提供する 様々な追加エンドポイントも 提供しています

通知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のすべての利点を享受するために 今すぐ移行計画を始めましょう

移行に必要なのは ほんのわずかなステップです

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通知に変更します 実装をテストするには Sandboxのみでバージョン2の通知を 受信することから始めることができます

設定を切り替えると App StoreサーバはV2形式で 新しい通知の送信を開始します リトライ処理中の V1通知がある場合 最大3日間 受信し続けることができます

移行に関するより詳細なサポートについては その他のリソースもご用意しています App Store Server APIおよび App Store Server Notifications V2は Sandbox環境で使用できます そのため本番環境に導入する前に 実装をテストできます

そして今週 App Store Server API を呼び出し App Store Server Notification V2を 解析するための 新しいオープンソースライブラリ App Store Server Libraryをリリースします これでエンドポイントを簡単に呼び出したり 受信した署名済みデータを検証したり さらにはレシートからtransactionIdsを 抽出して移行を容易にしたりできます

今年のWWDCでの専用セッション 「Meet the App Store Server Library」を ぜひチェックしてみてください また 移行方法のヒントについては WWDC22のセッション 「Explore in-app purchase integration and migration」を 参照してください

以上でこのセッションのApp Storeサーバの アップデートを終了します 本日発表した素晴らしい新機能を ぜひご活用ください また 私たちがレビューする時間がなかった さらなる機能については ドキュメントをご覧ください

すべての機能がSandboxと 本番サーバの両方で利用できますので まずSandboxでテストして 準備ができたらいつでも本番サーバーに ロールアウトすることができます

そして 皆さんからのフィードバックを お待ちしています App Storeサーバへの 機能要望がありましたら Appleのフィードバックアシスタントから お知らせください WWDC23へのご参加 ありがとうございました ♪ ♪