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

Google Play 2026年のリアルタイムデベロッパー通知

ブログ チュートリアル

リアルタイムデベロッパー通知(RTDN)は、購入に何かが起きたことをGoogle Playがバックエンドに伝える仕組みです。WebhookのダッシュボードもアプリごとのAPIキーも存在しません。Playはお客様自身のGoogle Cloudプロジェクト内のCloud Pub/Subトピックにメッセージを発行し、サーバーはそれをHTTPSプッシュで受け取るか、ポーリングで取得します。収益運用が依然としてDeveloper APIをポーリングする定期ジョブに依存しているなら、RTDNはアップグレードです。Googleのドキュメントは、Play Developer APIの非効率な使用が「APIクォータ制限につながる可能性がある」と明記しています。

このチュートリアルは、実際の作業順に沿って進めます。トピックを作成し、Playの公開権限を付与し、プッシュかプルの方式を選び、Play Consoleで通知を有効化し、その後ペイロードをデコードして処理します。以下のフィールド名、通知タイプ、コンソールの手順はすべてGoogleの2つの公式ページに基づいており、末尾に引用元を示します。

RTDNを一行で言うと:購入状態の変化ごとに届くメッセージで、1通知あたり約1KB、publishとpullを合わせて約2KB。さらに、通知は「購入に関する完全な情報を提供するものではない」ため、受信後にGoogle Play Developer APIを呼び出す恒久的な義務が伴います。

ステップ1 — 自分のGCPプロジェクトにPub/Subトピックを作成する

RTDNはAndroidアプリごとに設定しますが、メッセージング層はご自身で用意します。Cloud Pub/Sub APIを有効化したGoogle Cloudプロジェクトと、Playがパブリッシュするトピックが必要です。Play Developer APIで既に使用しているプロジェクトを再利用しても、別のプロジェクトを新規作成してもかまいません。複数アプリを運用する場合はPlay Developer APIに同じGoogle Cloudプロジェクトを使う必要がありますが、アプリごとに個別のプロジェクトへパブリッシュできます。

構築前にサイズを見積もってください。通知のデータ部分はリクエストあたり約1 KBで、公開と取得がそれぞれ別のリクエストとなるため、通知1件あたり約2 KBになります。月間の量は請求サイクルとユーザー行動によって異なりますが、少なくともユーザー1人あたり請求サイクルごとに1件の通知を見込んで計画し、その数値についてPub/Subの料金と割り当てを確認してください。

ステップ2 — Google Playに公開権限を付与する

新しいトピックは、アクセス権を付与するまでPlayのパブリッシュを黙って拒否します。ここが見落とされがちなポイントです。Google Cloud Consoleでプロジェクトを選択し、Pub/Subを開いてトピックを見つけ、権限の詳細を開いてサービスアカウントを追加します

google-play-developer-notifications@system.gserviceaccount.com

そしてPub/Sub Publisherのロールを付与します。保存してトピックの設定を完了します。企業での注意点が一つあります。組織のドメイン制限付き共有設定がこの付与をブロックしている場合、Playが何かを公開できるようにする前に、そのGoogle Playサービスアカウントの例外を追加する必要があります。

ステップ3 — サブスクリプションにプッシュかプルかを選ぶ

トピックは読めるメールボックスではありません。トピックにはサブスクリプションを紐付ける必要があります。プッシュサブスクリプションでは、Cloud Pub/SubがセキュアなバックエンドにHTTPSリクエストを送信します。プルサブスクリプションでは、バックエンドがPub/Subにリクエストを送信してメッセージを取得する必要があります。RTDNに関するGoogleのガイダンスは次のとおりです。迷ったらプッシュを使用してください。「一般に実装が容易」だからです。プルは、大量のメッセージを処理する際にリソース使用率を最適化する目的でよく使われます。

この選択から2つの運用ルールが導かれます。プルの場合、取得したすべてのメッセージを確認応答してください。そうしないとPub/Subが再配信を続けます。プッシュの場合、エンドポイントからの成功レスポンスコードが確認応答となり、エンドポイントが遅い、または失敗すると配信が繰り返されます。

ステップ4 — Play ConsoleでRTDNを有効化し、テストを送信する

  1. Google Play Consoleを開き、アプリを選択して収益化 → 収益化の設定に進みます。
  2. そのページ上部のリアルタイムデベロッパー通知セクションで、リアルタイム通知を有効にするにチェックを入れます。
  3. トピック名フィールドに、projects/{project_id}/topics/{topic_name}の形式で完全なトピック名を入力します。
  4. テストメッセージを送信をクリックします。プルの場合はCloud Consoleでサブスクリプションを開き、メッセージを表示をクリックして取得し、確認応答します。プッシュの場合は、テストメッセージがエンドポイントに届いたか確認します。
  5. 通知の範囲を選択します。サブスクリプションとすべての無効化された購入は、サブスクリプションと無効化された購入のイベントのみを提供します。サブスクリプションと単発商品のすべての通知は、ONE_TIME_PRODUCT_PURCHASEDやONE_TIME_PRODUCT_CANCELEDなどの単発商品の購入イベントも送信します。
  6. 変更を保存をクリックします。

テスト公開が失敗すると、コンソールにエラーが表示されますが、現実的な原因は2つだけです。トピック名が間違っているか、google-play-developer-notifications@system.gserviceaccount.comにそのトピックのPub/Subパブリッシャーの権限がないかのどちらかです。修正すべきは権限であり、アプリではありません。

メッセージに実際に含まれる内容

トピックへのパブリッシュはすべて同じエンベロープを持ちます。attributesマップ、base64でエンコードされたdataフィールド、messageId、そしてsubscriptionパスです。dataをデコードすると、4つの情報——version、packageName、eventTimeMillis——に加え、ちょうど1つのペイロードフィールドを持つDeveloperNotificationが得られます。これらのペイロードフィールドは相互に排他的です。subscriptionNotification、oneTimeProductNotification、voidedPurchaseNotification、またはtestNotificationのいずれかです。

messageIdは通知の一意の識別子であり、リファレンスガイドでは、重複した通知を処理して不要なバックエンドAPI呼び出しを行わないよう、この一意性を確認することを推奨しています。それはRTDNが保護するために存在するAPIクォータをまさに無駄にします。

サブスクリプション通知の種類

subscriptionNotificationには、notificationTypeの整数値、purchaseToken、そして独自のversionが含まれます。現在の一覧は次のとおりです。

  • 1 — SUBSCRIPTION_RECOVERED:アカウント保留から回復、または一時停止から再開。
  • 2 — SUBSCRIPTION_RENEWED:有効なサブスクリプションが更新された。
  • 3 — SUBSCRIPTION_CANCELED:自主的または非自主的にキャンセルされた状態。自主的なキャンセルの場合はユーザーが解約した時点で送信されます。
  • 4 — SUBSCRIPTION_PURCHASED:新しいサブスクリプションが購入されました。
  • 5 — SUBSCRIPTION_ON_HOLD:アカウントホールドに入りました(有効にしている場合)。
  • 6 — SUBSCRIPTION_IN_GRACE_PERIOD:有効にしていれば猶予期間に入った状態。
  • 7 — SUBSCRIPTION_RESTARTED:ユーザーが解約済みのサブスクリプションを、有効期限切れ前にPlay → アカウント → サブスクリプションから再開したケース。
  • 9 — SUBSCRIPTION_DEFERRED:更新時期が延長されました。
  • 10 — SUBSCRIPTION_PAUSED / 11 — SUBSCRIPTION_PAUSE_SCHEDULE_CHANGED:一時停止中、または一時停止スケジュールが変更されました。
  • 12 — SUBSCRIPTION_REVOKED:有効期限前に取り消されました。
  • 13 — SUBSCRIPTION_EXPIRED:サブスクリプションの有効期限が切れています。
  • 17 — SUBSCRIPTION_ITEMS_CHANGED:サブスクリプションのバンドル内の項目が変更された状態。
  • 18 — SUBSCRIPTION_CANCELLATION_SCHEDULED:分割払いのコミット期間終了時に解約が予定されています。
  • 19 — SUBSCRIPTION_PRICE_CHANGE_UPDATED:サブスクリプション項目の価格変更の詳細が更新されました。
  • 20 — SUBSCRIPTION_PENDING_PURCHASE_CANCELED:保留中のサブスクリプション取引がキャンセルされました。
  • 22 — SUBSCRIPTION_PRICE_STEP_UP_CONSENT_UPDATED:値上げ同意期間が開始された、またはユーザーが同意したことを示します。値上げ同意が必要な地域でのみ送信されます。

タイプ8(SUBSCRIPTION_PRICE_CHANGE_CONFIRMED)はリファレンスで非推奨とされているため、新しいロジックをこれに載せないでください。また、これらの番号は推測できるライフサイクルではない点に注意してください。イベントは状態が変わったことを伝えるだけで、結果の状態は決して伝えません。

単発商品の通知

より広いスコープを選択した場合にのみ送信されます。oneTimeProductNotificationはトークンにskuフィールドを追加し、2つのタイプがあります。1 — ONE_TIME_PRODUCT_PURCHASED(単発商品の購入が成功)と2 — ONE_TIME_PRODUCT_CANCELED(保留中の単発購入がユーザーによってキャンセルされた)です。どちらの場合も、購入通知だけでは商品を消費または確認済みにしたかどうかはわからないため、Developer APIの呼び出しが必要です。

無効化された購入とrefundTypeフィールド

voidedPurchaseNotificationは、収益チームが最も気にするRTDNであり、2026年には単なる通知以上の意味を持ちます。ペイロードはpurchaseToken、orderId、productType、refundTypeです。productTypeはサブスクリプションなら1、都度購入なら2です。refundTypeは1 — REFUND_TYPE_FULL_REFUNDまたは2 — REFUND_TYPE_QUANTITY_BASED_PARTIAL_REFUNDで、後者は複数数量の購入にのみ適用され、複数回にわたって一部無効化されることがあります。残りの合計数量がすべて返金されると、種類は全額返金として報告されます。

リファレンスガイドは、権利を調整する対象の購入と注文を特定するには通知自体で十分であると明言しており、Google Play Voided Purchases APIはプル型の補完として、タイムスタンプ範囲の無効化購入データを返します。複数数量の一部返金の場合、purchases.productsv2のrefundableQuantityフィールドで、購入済み商品のうち無効化されていない残数が分かります。これは2026年Play返金・チャージバックガイドで扱ったチャージバックと返金の会計処理の変更に直結します。

パイプラインを正しく保つサーバー側のルール

  • 通知は答えではなく問いとして扱ってください。RTDNのたびにDeveloper APIを呼び出し、権利を付与・延長・取り消す前に完全なステータスを取得してください。
  • messageIdで重複排除します。Pub/Subは少なくとも1回配信するため、重複処理はAPI呼び出しの重複と状態遷移の重複を招きます。
  • 必ず確認応答してから処理します。プルの場合:取得したメッセージに確認応答を返します。プッシュの場合:成功コードを返します。処理に確認応答より時間がかかる場合は、再配信を受け入れ、ハンドラーを冪等にしてください。
  • ユーザーごとに複数のイベントが発生する想定を。1つのpurchaseTokenから、同じ購読者に対して購入済み、キャンセル済み、期限切れの通知が順に発生することがあります。ハンドラは繰り返し実行しても安全でなければなりません。
  • ポーリングで補完しないこと。 RTDNと併用してDeveloper APIをポーリングするのは、割り当て制限を招く典型的な失敗パターンです。

設定を確認しています

コンソールのテストメッセージを送信は、エンドツーエンドで確認できる最速の手段です。サブスクリプションを紐付けていれば、必ず受信するはずです。testNotificationの本文にはversionフィールドしか含まれないため、ハンドラのテストスイートでアサートする際に安全なペイロードです。バックエンドがまだない場合は、gcloudコマンドラインでサブスクリプションからメッセージを取得してください——そしてacknowledgeするのを忘れずに。健全なパイプラインは、packageNameが自分のアプリと一致し、eventTimeMillisが実際の購読者のアクティビティを追跡するイベントの流れとして現れます。

スケジュールに関する注意:サーバー側のRTDN対応は、クライアント側のBilling Libraryの期限と並行して進みます。すべての新規アプリとアップデートはBilling Libraryバージョン8以降を使用する必要があり、延長の道筋は2026年11月1日まで続きます — RTDNを消費するサーバー検証も同時に準備しておくべきです。

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

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

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

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

✔ 送信済み

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


← 編集に戻る