Voided Purchases API

Google Play Voided Purchases API は、ユーザーが取り消した購入に関連付けられているアプリ内注文のリストを提供します。このリストの情報を使用すると、ユーザーがアプリ内注文からアイテムにアクセスできないようにする取り消しシステムを実装できます。

この API は購入に適用されます。定期購入については、リアルタイム デベロッパー通知をご覧ください。

ユーザーは次の方法で購入を取り消すことができます。

  • 注文に対する払い戻しをリクエストする
  • 注文をキャンセルする
  • 注文をチャージバックする

この API を使用すると、特にアプリがゲームの場合、アプリのすべてのユーザーに対してより公平なエクスペリエンスを提供することができます。

アクセスを取得する

Voided Purchases API を使用するには、売上情報の表示権限が必要になります。認証には、OAuth クライアントまたはサービス アカウントを使用します。サービス アカウントを使用する場合は、アカウント内で「売上レポートの表示」権限を有効にします。

Google Play Developer API への承認済みアクセスを取得する方法について詳しくは、以下のガイドをご覧ください。

取り消し済みの購入を表示する

アプリ内注文に関連付けられている取り消し済みの購入のリストをリクエストするには、GET メソッドを使用します。リクエストには、アプリの完全修飾パッケージ名(例: com.google.android.apps.maps)と、API へのアクセスを取得する際に受け取った承認トークンを含めます。

GET https://www.googleapis.com/androidpublisher/v3/applications/
your_package_name/purchases/voidedpurchases?access_token=your_auth_token

リクエストには以下のパラメータを含めることもできます(各パラメータはオプションです)。

startTime

アプリ内アイテムの購入が取り消された時間で、応答に含める最も前の時間(Unix エポックからの経過時間(ミリ秒数))。デフォルトでは、startTime は 30 日前に設定されています。

API では、過去 30 日間に取り消された購入のみを表示できます。startTime に指定した値に関係なく、30 日より前に取り消された購入は応答に含まれません。

endTime

アプリ内アイテムの購入が取り消された時間で、応答に含める最近の時間(Unix エポックからの経過時間(ミリ秒数))。デフォルトでは、endTime は現在の時間に設定されています。

maxResults
各応答に含まれる取り消し済みの購入の最大数。デフォルト値は 1000 です(このパラメータの最大値も 1000 です)。
token
前の応答からの継続トークン。このパラメータを使用すると、表示する結果数を増やすことができます。

応答は、アプリ内注文に関連付けられている取り消し済みの購入のリストを含む JSON 文字列です。リクエストの maxResults パラメータで指定した値よりも結果数が多い場合、応答に nextPageToken の値が含まれます。この値を次のリクエストに渡すことで、表示する結果数を増やすことができます。リスト内の最初の結果には、取り消し済みのアプリ内アイテムの購入のうち最も前のものが表示されます。

{
  "tokenPagination": {
    "nextPageToken": "next_page_token"
  },
  "voidedPurchases": [
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_purchase_token",
      "purchaseTimeMillis": "1468825200000",
      "voidedTimeMillis": "1469430000000"
    },
    {
      "kind": "androidpublisher#voidedPurchase",
      "purchaseToken": "some_other_purchase_token",
      "purchaseTimeMillis": "1468825100000",
      "voidedTimeMillis": "1470034800000"
    },
  ]
}

割り当て

Voided Purchases API では、パッケージ単位で以下の割り当てが設定されます。

  • 500 クエリ / 日(1 日の開始(終了)は太平洋標準時の午前 0 時)
  • 30 秒間に 30 クエリ

最初のリクエストに関するガイドライン

最初の API リクエストでは、アプリで利用可能なデータをすべて取得することをおすすめします。可能性は低いですが、このプロセスによって 1 日の割り当てが使い果たされてしまうこともあります。取り消し済みの購入に関するデータを安全で一貫性のある方法で取得するには、以下のおすすめの方法を使用します。

  • maxResults パラメータにはデフォルト値を使用します。こうすることで、1 日のクエリの割り当てをすべて使用した場合、100,000 の取り消し済みの購入に関する詳細を取得できます。
  • 応答に nextPageToken の値が含まれている場合、次のリクエストの際にその値を token パラメータに指定します。
  • 不適切なリクエストでも各割り当てにカウントされるため、オプションのリクエスト パラメータの値を使用してテストを最小限に抑えます。

おすすめの方法

アプリでのこの API の使用方法を決定する際には、購入を取り消す理由はさまざまであること、すべてのケースで使用できる単一の解決策はないということを覚えておいてください。取り消しに関するポリシーと戦略を設計する際には、ユーザーを念頭に置く必要があります。そのためには、以下の方法を使用することをおすすめします。

  • この API は、望ましくない行動に対処するための包括的な戦略におけるさまざまな要素の 1 つとして使用します。通常、アプリ内アイテムへのアクセスを取り消すことによる効果は、アプリ内購入の価格が妥当なアプリ、望ましくない行動を防止するアプリ設計、望ましくない行動を受け入れない文化を持つ強固なユーザーベース、応答性と効率性に優れたユーザー サポート チャンネルと組み合わせることで高められます。
  • すべてのユーザーに対する公平性を確保するために、取り消しポリシーを一律に管理します。
  • 望ましくない行動に対処する場合は、段階的なポリシーを作成することを検討します。たとえば、初期の違反に対してはアプリ内で警告することから始めて、ユーザーによる望ましくない行動が続く場合には応答をエスカレーションします。最終手段として、ユーザーがアプリをまったく操作できないようにすることができます。
  • 取り消しポリシーを導入する場合は、ポリシーを更新するたびに、アプリのサポート チャンネルを使用して変更をユーザーに通知します。変更がアプリで有効になる前に、変更内容を明確に理解するための時間をユーザーに与えます。
  • ユーザーに対する透明性を維持します。アプリ内アイテムへのアクセスを取り消す場合など、措置を講じる場合は必ずユーザーに通知します。理想的には、決定事項に対してユーザーが異議申し立てを行えるようにし、そうした異議申し立てを公平に扱う必要があります。
  • フィードバック フォームとコミュニティ フォーラムを監視して、ユーザーを望ましくない方法での行動に駆り立てる要因と、そのような行動をどのようにして実行に移すのかを理解します。望ましくない行動を防止するための第一歩として、こうした洞察に基づいて対処します。