KappSナレッジベース · ブログ

2026年のApp Storeサーバー通知V2

ブログ チュートリアル

Appleはバージョン1の経路を閉鎖しました。バージョン1の通知とApp Store Receiptsエンドポイントは非推奨化され、現在は「サーバーにバージョン2のエンドポイントを実装する」という指示に変わっています。稼働中のサブスクリプションがあるアプリにとって、これは見た目だけの移行ではありません。通知ストリームは、更新が成功したこと、返金が行われたこと、課金が再試行されていること、あるいはAppleが返金リクエストの正当性の説明を求めていることをサーバーが知る手段だからです。このチュートリアルでは、App Store Connectでバージョン2を有効化し、JWSを検証し、すべての通知タイプとサブタイプをマッピングし、通知がある時点の状態を説明するだけの情報をApp Store Server APIで補う、2026年版のセットアップ全体を解説します。

一行でまとめると: App Store ConnectはJWS署名されたJSONブロブをあなたのHTTPS URLにPOSTします。署名チェーンを検証し、signedPayloadをデコードし、notificationTypeとsubtypeに基づいて処理し、200-206をすばやく返し、イベントの状態ではなく現在の状態が必要なときはいつでもApp Store Server APIを呼び出します。

ステップ1 — App Store Connectに触れる前に、2つのエンドポイントを修正する

You need one HTTPS URL for production and, optionally, a second one for sandbox; Apple explicitly allows you to use the same URL for both environments. Your server must support TLS 1.2 or later. If the URL contains a port, it must be either 443 or 1024 and above — https://example.com:1234/notifications is a valid shape, a low privileged port is not. And if your edge terminates behind an IP allow list, add Apple's 17.0.0.0/8 subnet, which applies to sandbox and production alike. All of this is documented in Enabling App Store Server Notifications.

ステップ2 — 環境ごとにバージョン2を有効にする

App Store Connectでアプリを開き、アプリ情報 > App Storeサーバー通知に進みます。本番環境とサンドボックス環境は別々に設定され、それぞれがバージョン2または非推奨のバージョン1を独立して選択できます。これにより、本番環境では新しい形式を運用しながら、他の環境では引き続き旧形式を動作させる、あるいはその逆も可能になります。Appleが示す移行手順は、まずサンドボックス環境でバージョン2をテストすることで、その後になってから本番環境を移行します。デバッグを始める前に知っておきたい挙動として、TEST通知は、設定したURLがどのバージョンを想定していても、常にバージョン2形式で送信されます。

ステップ3 — 正しいステータスコードで応答し、その後は非同期で作業する

Respond with an HTTP status code of 200-206 if the POST was handled successfully. If it was not handled, send a 50x or 40x to have the App Store retry the notification. The practical pattern is: read the body, verify it, enqueue it, reply 200, and do the real work in a worker. Do not hold the connection open while you call your own database, your email provider, or the App Store Server API. Retries are there to protect you from infrastructure failure, not from a slow handler — and every retry you trigger is a duplicate event you then have to suppress.

ステップ4 — ペイロードを解読する

ボディはresponseBodyV2オブジェクトで、意味のあるフィールドはJWSであるsignedPayloadのみです。これをヘッダー、ペイロード、署名の各表現にパースし、ペイロードをBase64URLデコードしてresponseBodyV2DecodedPayloadを取得します。この階層ではnotificationType、subtype、version、signedDate、notificationUUIDが得られます。4つのデータオブジェクトのうち必ず1つが存在します。アプリ内課金イベント用のdataはsignedTransactionInfoを、自動更新サブスクリプションの場合はさらにsignedRenewalInfoを含みます。summaryはSUMMARYサブタイプを伴うRENEWAL_EXTENSIONの場合にのみ現れます。appData、またはEXTERNAL_PURCHASE_TOKEN通知でのみ現れるexternalPurchaseTokenもあります。

ステップ5 — 外側だけでなくすべての署名を検証する

署名付きの3つのペイロード——signedPayload、signedTransactionInfo、signedRenewalInfo——はそれぞれ独自のJWS署名を持ち、個別に検証する必要があります。使用するアルゴリズムはヘッダーのalgパラメータで指定されたものを使用します。実際には、Appleが公開しているルート証明書までx5c証明書チェーンを検証することを意味し、このルート証明書はApple認証局ページからダウンロードします(本サービスにおける現在のルート証明書はAppleRootCA-G3.cerです)。これを自前で実装しないでください。AppleはPython、Java、Node.js、Swift向けにApp Store Server Libraryを公開しており、検証とデコードを代行します。ペイロードをBase64でデコードするだけで検証を省略するハンドラは、容易になりすましが可能です。通知URLを知った人物が誰でも、自分にサブスクリプションを付与できてしまいます。

ステップ6 — notificationTypeとsubtypeを権利情報にマッピングする

バージョン2のenumは23種類の通知タイプと、その一部を修飾する19種類のサブタイプを定義しており、両方のリストはnotificationTypeとsubtypeで公開されています。有料顧客がアクセスを維持できるかどうかを左右するのは次のとおりです。

  • SUBSCRIBED — サブタイプはINITIAL_BUY、RESUBSCRIBE、UPGRADE、DOWNGRADEです。「サブスクリプション登録済み」とだけ記録するのではなく、アクセスを付与し、プロダクトIDを記録してください。
  • DID_RENEW — サブタイプはBILLING_RECOVERYとBILLING_RETRYです。支払い問題の後に届いた更新もここに届くため、通常のアクセス延長として扱います。
  • DID_FAIL_TO_RENEW — 顧客が猶予期間内にある場合はGRACE_PERIODサブタイプ付き。通常ここではアクセスが継続され、それが猶予期間の趣旨そのものです。
  • GRACE_PERIOD_EXPIRED — 猶予期間が終了しました。ダウングレードすべきはこの時点であり、課金失敗時ではありません。
  • EXPIRED — サブタイプはVOLUNTARY、BILLING_RETRY、PRODUCT_NOT_FOR_SALEです。最後のものは、ユーザーがまだ保有している商品を販売停止にする場合に重要になります。
  • DID_CHANGE_RENEWAL_STATUS(AUTO_RENEW_ENABLED / AUTO_RENEW_DISABLED)およびDID_CHANGE_RENEWAL_PREF(UPGRADE / DOWNGRADE)——自動更新をオフにした顧客も期間終了までは権利を有するため、AUTO_RENEW_DISABLEDで権利を取り消さないでください。
  • REFUND、REFUND_DECLINED、REFUND_REVERSED、REVOKE、RESCIND_CONSENT — 権利取り消し側です。返金が取り消されたということはお金があなたに戻ってきたということなので、権利も顧客に戻さなければなりません。
  • CONSUMPTION_REQUEST — Appleが購入の利用状況に関する証拠を求めています。手順7を参照してください。
  • OFFER_REDEEMED、PRICE_CHANGE、PRICE_INCREASE(ACCEPTED / PENDING)、RENEWAL_EXTENDED、そしてRENEWAL_EXTENSION(SUMMARY / FAILURE)—いずれもアクセス権の変更ではなく、通常は顧客への通知を必要とする商業条件や日付の変更です。
  • METADATA_UPDATE、MIGRATION、ONE_TIME_CHARGE、TEST、そしてEXTERNAL_PURCHASE_TOKEN(Appleが報告対象のないトークンを生成した場合はUNREPORTEDサブタイプ付き)。

最新の追加項目を含む完全なカタログは通知の変更履歴にあります。Appleは随時フィールドや値を追加するため、実装が完了したと判断する前に必ず再確認してください。

ステップ7 — 12時間以内にCONSUMPTION_REQUESTに回答する

顧客が任意の製品タイプ(消耗型、非消耗型、非更新型、自動更新型)について返金をリクエストすると、AppleはCONSUMPTION_REQUESTを送信します。顧客が同意していれば、Appleが求める利用データを添えてSend Consumption Informationを呼び出すことで応答でき、Appleは通知の到着時点から12時間の応答期間を明記しています。顧客が同意していない場合は、一切応答しません。間違えやすいルールが2つあります。このAPIに必要な同意は、トラッキングや広告のために収集した同意とは別物です。また、利用データをAppleと共有する前に有効な同意を取得する責任はあなたにあります。

ステップ8 — 状態管理にはApp StoreサーバーAPIを使い、イベントには使わない

通知はある瞬間を伝えるものです。権限を書く前に、まず現状を確定させましょう。

  • 取引情報を取得 — 取り消し理由と日付を含む、単一の取引の情報。
  • 顧客のサブスクリプションを正式に確認するにはGet All Subscription Statusesを使用してください。
  • 返金履歴を取得は、元のトランザクション識別子に対する返金情報が必要なときに使用します。
  • サブスクリプションの更新日を延長するで、サービス障害を補償する場合。この操作が一方通行になる理由は2つあります。延長が反映された後は取り消す方法が一切ないこと、そしてファミリーメンバーのサブスクリプションは自動的に延長される一方、ファミリーメンバーのサブスクリプションに対する直接のリクエストには対応していないことです。また、延長期間は、Appleが手数料率を計算する際に用いる有料サービス1年には算入されません。

ステップ9 — 依存する前にパイプが機能することを証明する

Call Request a Test Notification and the App Store sends a TEST notification to your endpoint. That call returns a token you pass to Get Test Notification Status within six months to see how your server actually answered. Separately, if your endpoint was down at 3am, Get Notification History returns the version 2 notifications the App Store attempted to send: 180 days in production, 30 days in the sandbox, 20 records per page with a continuation token, and full notification contents. Remember what that history is: each record reflects the state at the time the notification was originally sent, not the current state.

ステップ10 — パイプラインを正しく保つ運用ルール

  • 何かを書く前に環境を読み取ります。サンドボックスのトラフィックはサンドボックスのURLに届きます。共有ハンドラーがサンドボックスのイベントから本番のエンタイトルメントを書き込むと、テストがデータインシデントになってしまいます。
  • notificationUUIDで重複排除します。リトライや自前の再処理によって同じイベントが複数回発生するため、識別子を保存して重複を破棄してください。
  • 通知をレシートとして扱ってはいけません。 SUBSCRIBEDとDID_RENEWだけを監視し、REFUND、REVOKE、REFUND_REVERSEDを無視するビルドは、有料アクセスを恒久的に漏らし続けます。ライフサイクル全体を処理するか、検証をAppleのライブラリに任せてServer APIに問い合わせてください。
  • 独自のイベントログを保持してください。 顧客がアクセス権について異議を唱えたとき、通知履歴と独自ログがあれば判断の経緯を再現できます。
  • エンドポイントが本番環境の一部であることを前提に計画しましょう。 監視、接続予算をはるかに下回るリクエストタイムアウト、そしてキューが必要です。課金システムへの同期呼び出しチェーンにしてはいけません。

情報源

デベロッパーアカウントを大規模に運用中ですか? 運用面は当社が対応します。

クリックしてファイルを選択 · 右クリック→貼り付け、またはCtrl/⌘+Vでスクリーンショットを貼り付け

このボックスにファイルをドラッグすることもできます。

ご提供いただいたメールに返信します。お客様の情報はKappS内に留まります。

✔ 送信済み

メッセージを受け付けました。24時間以内に返信します。


← 編集に戻る