このガイドでは、Google Play Developer API を使用して、Google Play アプリの商品カタログを作成、管理する方法について説明します。
Google Play の課金システムを使用してアプリ内でアイテムを販売するには、ユーザーが購入できるようにするすべてのアイテムを含むカタログを設定する必要があります。これは Google Play Console から行うことができます。また、Google Play Developer API を使用してカタログ管理を自動化することもできます。自動化により、カタログを常に最新の状態に保ち、手動での調整が不可能な大規模なカタログにスケーリングできます。このガイドでは、Play Developer API を使用して、Google Play アプリの商品カタログを作成、管理する方法について説明します。バックエンド統合用に Google Play Developer API を設定する方法については、準備ガイドをご覧ください。
Catalog Management API
Google Play の課金システムで販売できるさまざまなタイプのアイテムについては、アプリ内アイテムのタイプとカタログに関する考慮事項についてをご覧ください。Google では、Google Play でのカタログ管理用に、2 つの主要な商品カテゴリに対応する 2 つの主要な API セットを提供しています。
- 1 回限りのアイテム
- 定期購入商品
1 回限りのアイテム
1 回限りのアイテム(以前のアプリ内アイテム)では、1 回限りのアイテムのオブジェクト モデルを使用します。これにより、1 回限りのアイテムに複数の購入オプションと特典を設定できます。1 回限りのアイテムのオブジェクト モデルにより、アイテムの販売方法がさらに柔軟になり、管理の煩雑さが軽減されます。既存のアプリ内アイテムは、1 回限りのアイテムのオブジェクト モデルに移行されます。詳しくは、アプリ内アイテムの移行をご覧ください。
monetization.onetimeproducts エンドポイントと inappproducts エンドポイントを使用すると、バックエンドから 1 回限りのアイテムを管理できます。これには、商品の作成、更新、削除、価格と在庫状況の管理が含まれます。1 回限りのアイテムの購入をどのように処理するかに応じて、消費型アイテム(必要な回数だけ購入可能)または永続的な利用資格(同じユーザーが 2 回購入することはできない)をモデル化します。1 回限りのアイテムを消費可能にするかどうかは、デベロッパーが決定できます。
定期購入商品
monetization.subscriptions エンドポイントを使用すると、デベロッパー バックエンドから定期購入商品を管理できます。定期購入の作成、更新、削除、地域別の在庫状況と価格の管理などを行うことができます。monetization.subscriptions エンドポイントに加えて、定期購入の基本プランと特典をそれぞれ管理するための monetization.subscriptions.basePlans と monetization.subscriptions.basePlans.offers も提供しています。
バッチメソッド
onetimeproducts、inappproducts、monetization.subscriptions の各エンドポイントには、同じアプリで最大 100 個のエンティティを同時に取得または管理できるバッチメソッドが多数用意されています。
バッチメソッドは、レイテンシ許容値を有効にして使用すると、スループットが向上します。これは、大規模なカタログを扱うデベロッパーが初期カタログの作成やカタログの調整を行う場合に特に有用です。
更新の反映レイテンシとスループット
プロダクトの作成または変更のリクエストが完了した後、ネットワークまたはバックエンドの処理の遅延により、エンドユーザーのデバイスに変更がすぐに表示されない場合があります。デフォルトでは、すべてのプロダクト変更リクエストはレイテンシの影響を受けます。つまり、バックエンド システムを介した高速な伝播に最適化されており、通常は数分以内にエンドユーザーのデバイスに反映されます。ただし、このような変更リクエストの数には 1 時間あたりの上限があります。多くの商品を作成または更新する必要がある場合(たとえば、最初の大規模なカタログの作成時など)は、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定してバッチメソッドを使用できます。これにより、更新のスループットが大幅に向上します。レイテンシを許容するアップデートがエンドユーザー デバイスに反映されるまでには、最長で 24 時間かかります。
割り当ての構成
Play Developer API を使用して商品カタログを管理する際は、次の割り当て制限に注意する必要があります。
- Google Play Developer API は「バケット」と呼ばれるカテゴリに分類されており、それぞれのバケットには 1 分あたりの割り当て制限が設定されています。詳細については、割り当てをご覧ください。
- 商品変更エンドポイントでは、1 時間あたり 7,200 件のクエリ上限も適用されます。これは、1 回限りのアイテムと定期購入の両方、および作成、更新、有効化、削除を含むすべての変更リクエストに適用される単一の上限です。バッチ変更メソッド呼び出しは、含まれる個々のリクエストの数やレイテンシの感度に関係なく、この割り当ての 1 つのクエリとしてカウントされます。
- レイテンシに影響する変更には、1 時間あたり 7,200 件の変更という上限もあります。バッチメソッドの場合、この割り当ての目的で、ネストされた変更リクエストは個別にカウントされます。この割り当ては、レイテンシに敏感な更新を実行するバッチ API のユーザーにのみ実質的な影響を及ぼします。他のケースでは、割り当て 2 がこの割り当ての前または同時に使い果たされるためです。
さまざまなリクエストの割り当て使用量を理解するための例をいくつか紹介します。
- 1 つのアイテムを取得する 1 つの
getリクエストは、割り当て 1 のトークンを 1 つ消費し、割り当て 2 と 3 のトークンは消費しません(変更エンドポイントにのみ関係するため)。 - 最大 100 個のアイテムを取得するバッチ
getリクエストでも、割り当て 1 のトークンが 1 つ消費され、割り当て 2 と 3 のトークンは消費されません。 - 1 つのアイテムに対する 1 つの
modificationリクエストは、割り当て 1 のトークン 1 つと割り当て 2 のトークン 1 つを消費します。リクエストがレイテンシの影響を受けやすい場合は、割り当て 3 のトークンも 1 つ消費されます。割り当て C の上限は割り当て 2 と同じであるため、単一の変更メソッドのみを使用するユーザーには実質的な影響はありません。 - レイテンシを許容できる 100 個のアイテムに対するバッチ
modificationリクエストは、割り当て 1 のトークン 1 個と割り当て 2 のトークン 1 個を消費します。この割り当て設定では、カタログを更新するための十分なマージンを確保する必要がありますが、アルゴリズムがこの割り当てを認識せず、このレートを超えると、追加の呼び出しごとにエラーが発生する可能性があります。 - レイテンシに敏感な 100 個のアイテムに対するバッチ
modificationリクエストは、割り当て 1 のトークン 1 個、割り当て 2 のトークン 1 個、割り当て 3 のトークン 100 個を消費します。
Catalog Management API の使用に関する推奨事項
これらのガイドラインを遵守することで、API とのやり取りを最適化し、スムーズで効率的なカタログ管理エクスペリエンスを実現できます。
使用量をモニタリングする
使用量の多いプロセスに注意する必要があります。たとえば、統合の開始時に、カタログ管理エンドポイントが、完全な初期カタログを作成するために、より多くの割り当てを消費する可能性があります。全体の使用量上限に近づいている場合、これは、購入ステータス API などの他のエンドポイントの本番環境での使用に影響する可能性があります。API の割り当てを超えないように、割り当ての使用状況をモニタリングする必要があります。使用状況をモニタリングする方法はいくつかあります。たとえば、Google Cloud APIs の割り当てダッシュボードや、任意の社内またはサードパーティの API Monitoring ツールを使用できます。
API 割り当ての使用量を最適化する
API エラーの可能性を最小限に抑えるため、レート消費を最適化することを強くおすすめします。これを効果的に実装するには、次のことをおすすめします。
- 適切なカタログ管理戦略を選択します。API の割り当てを理解したら、カタログ管理の目標を効率的に達成するために、アプリケーションに適した戦略を選択する必要があります。
- 変更を反映するために必要な最小限の呼び出しのみを行います。
- API に冗長な変更呼び出しや不要な変更呼び出しを送信しないでください。この場合、バックエンド カタログにチェンジログを保持することが必要になることがあります。
- 商品変更の 1 時間あたりのクエリ数の上限(7,200 件)を超えないようにしてください。短期間に大量の商品変更を行う必要がある同期プロセス(初期カタログの作成など)を構築することがあります。これらのプロセスが 1 時間あたりの上限を超えると予想される場合は、必要に応じて待機を実装し、使用量を安全なレベルに抑えます。レイテンシが許容される更新でバッチメソッドを使用して、スループットを向上させることを検討してください。
- スケーリングに事前に備える。アプリケーションの成長に伴い、API とさまざまなエンドポイントの使用量をスケールアップする必要が生じることがあります。使用量が上限に近づいたときに割り当てを増やす方法については、Google Play Developer API の割り当てに関するドキュメントをご覧ください。
- 負荷の高いプロセスを戦略的にスケジュールします。カタログの負荷の高いプロセスは、使用量のピーク時に合わせてスケジュールすることをおすすめします。たとえば、1 週間の販売ピーク時にカタログの完全同期を実行しないようにします。
割り当てエラー処理ロジックを追加する
カタログ管理ロジックをどれほど効率的に構築しても、1 日の割り当ては統合の独立したモジュールで使用されるエンドポイントで共有されるため、予期しない割り当て上限に対してロジックを復元できるようにする必要があります。エラー処理に割り当てスロットリング エラーを含め、適切な待機を実装してください。Google Play Developer API への呼び出しごとにレスポンスが生成されます。呼び出しが失敗すると、HTTP レスポンス ステータス コードと errors オブジェクトを含む失敗レスポンスが返されます。このオブジェクトには、エラー ドメインとデバッグ メッセージに関する詳細情報が含まれています。たとえば、1 日の利用時間の上限を超えると、次のようなエラーが発生することがあります。
{
"code" : 403,
"errors" : [ {
"domain" : "usageLimits",
"message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
"reason" : "dailyLimitExceeded",
"extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
} ],
}
カタログ管理の実装
デベロッパーは、Google Play Developer API の商品公開エンドポイントを使用して、バックエンドと Google Play の間でカタログを同期します。Google Play カタログをバックエンドのカタログの最新情報で常に最新の状態に保つことで、ユーザー エクスペリエンスを向上させることができます。次に例を示します。
- 利用可能な特典のリスト全体を参照し、特典と基本プランのタグを管理して、独自の資格条件と特典の表示ロジックに影響を与えることができます。
- ユーザーに表示される価格や商品の詳細がプラットフォーム間で異なるかどうかを確認し、一貫性を保つことができます。
- 新しい購入を処理する際に、バックエンドで商品の詳細をすぐに利用できます。ユーザーの重要なフロー中に Google Play Developer API を追加で呼び出す必要がないため、レイテンシが増加したり、失敗のリスクが高まったりすることはありません。
Google Play で商品カタログを作成する際には、特定の制限事項と考慮事項に留意する必要があります。これらの制限を理解し、カタログの構造を決定したら、同期戦略を決定します。
カタログの同期戦略
Google Play Developer API の公開エンドポイントを使用すると、変更が発生したときにカタログを更新できます。場合によっては、定期的な更新アプローチを採用し、同じプロセスで一連の変更を送信する必要があります。アプローチごとに異なる設計上の選択が必要になります。各同期戦略は、他のユースケースよりも適しているユースケースがあります。状況によっては、両方を必要とする一連のニーズがある場合があります。
新しい変更に気付いた時点で、商品に更新を加えたい場合があります。たとえば、緊急の商品更新を処理する場合(間違った価格をできるだけ早く修正する必要がある場合など)です。また、定期的なバックグラウンド同期を使用して、バックエンドと Play カタログの整合性を常に確保することもできます。これらの異なるカタログ管理戦略を実装する一般的なユースケースについて確認する。
ローカル カタログの変更に伴い更新情報を送信するタイミング
不一致を最小限に抑えるため、バックエンドの商品カタログに変更があったらすぐに更新することをおすすめします。
このタイプの更新は、次のような場合に適しています。
- 商品が常に最新の状態に保たれていることを確認する必要があります。
- 毎日、商品にいくつかの変更を加える必要があります。
- すでに本番環境にあり、販売されているプロダクトを更新する必要があります。
このアプローチは実装が簡単で、カタログの同期を維持しながら、不一致ウィンドウを最小限に抑えることができます。
定期的な更新を使用するタイミング
定期的な更新は、バックエンドの商品エディションに対して非同期で実行されます。これは、次の場合に適しています。
- 商品が短期間で更新されるようにする必要はありません。
- 一括更新または調整プロセスを計画する必要があります。
- デジタル商品を処理するコンテンツ管理システムまたはカタログ管理システムがすでにあり、カタログが継続的に更新されている
大規模なカタログの場合は、レイテンシを許容する更新でバッチ メソッドを使用して、最大スループットを達成することを検討してください。
商品カタログを作成する
Google Play にアップロードするカタログが大きい場合は、最初の読み込みを自動化することをおすすめします。このタイプの重いプロセスは、レイテンシを許容するバッチメソッドと組み合わせた定期的な戦略に従う場合に最適です。
1 回限りのアイテムを作成する
最初の 1 回限りの商品カタログの作成には、monetization.onetimeproducts.batchUpdate または inapp_products.insert メソッドを使用することをおすすめします。allowMissing フィールドを true に設定し、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定します。これにより、割り当て上限内でカタログを作成するのにかかる時間を最小限に抑えることができます。
定期購入商品を作成する
サブスクリプションの大規模なカタログを最初に作成する場合は、monetization.subscriptions.batchUpdate メソッドを使用することをおすすめします。このメソッドでは、allowMissing フィールドを true に設定し、latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定します。これにより、割り当て上限内でカタログの作成にかかる時間を最小限に抑えることができます。
小規模な定期購入カタログの場合、Play Developer API には monetization.subscriptions.create メソッドが用意されています。または、プロダクトの更新セクションで説明されているように、allowMissing パラメータを指定して monetization.subscriptions.patch メソッドを使用してサブスクリプションを作成することもできます。
前述のメソッドはすべて、基本プラン(Subscription オブジェクト内で指定)とともに定期購入を作成します。これらの基本プランは、最初は無効になっています。基本プランのステータスを管理するには、monetization.subscriptions.basePlans エンドポイントを使用します。これには、基本プランを有効にして購入できるようにすることも含まれます。また、monetization.subscriptions.basePlans.offers エンドポイントを使用すると、オファーを作成して管理できます。
サービスの更新情報
次の方法を使用すると、既存のプロダクトを効率的に変更して、最新の調整内容に沿ったサービスを提供できます。
1 回限りのアイテムを更新する
既存の 1 回限りのアイテムを更新するには、次の方法を使用できます。
- monetization.onetimeproducts.batchUpdate
inappproducts.patch: patch エンドポイントは、リソースを部分的に更新するために使用されます。つまり、リクエスト本文で指定した特定のフィールドを更新できます。パッチ エンドポイントは、通常、リソースのいくつかのフィールドのみを更新する必要がある場合に使用されます。inappproducts.update: 更新エンドポイントは、リソース全体を更新するために使用されます。つまり、リクエスト本文でリソース オブジェクト全体を送信する必要があります。通常、更新エンドポイントは、リソース内のすべてのフィールドを更新する必要がある場合に使用されます。allowMissingパラメータがtrueに設定されていて、指定された商品 ID がまだ存在しない場合、エンドポイントは失敗する代わりに商品を挿入します。inappproducts.batchUpdate: これは更新エンドポイントのバッチ バージョンで、1 つのクエリで複数の商品を更新できます。latencyToleranceフィールドをPRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANTに設定して、スループットを向上させます。
定期購入商品を更新する
既存のサブスクリプションを更新するには、monetization.subscriptions.patch メソッドを使用します。このメソッドには、次の必須パラメータがあります。
packageName: 定期購入が属するアプリのパッケージ名。productId: 定期購入の一意のプロダクト ID。
regionsVersion: リージョン構成バージョン。
allowMissing パラメータを使用して新しいサブスクリプションを作成する場合を除き、updateMask パラメータを指定する必要があります。このパラメータは、更新するフィールドのカンマ区切りのリストです。
たとえば、定期購入商品の掲載情報のみを更新する場合は、updateMask パラメータに listings フィールドを指定します。
monetization.subscriptions.batchUpdate を使用すると、複数のサブスクリプションを同時に更新できます。latencyTolerance フィールドを PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT に設定して使用すると、スループットが向上します。
基本プランを有効化、無効化、削除する場合、または定期購入者を最新の基本プランの価格バージョンに移行する場合は、monetization.subscriptions.basePlans エンドポイントを使用します。
また、monetization.subscriptions.basePlans.offers.patch メソッドを使用して、基本プランの特典を更新することもできます。
カタログの調整
バックエンドのカタログが変更されるたびに Google Play カタログを更新するか、定期的に更新するかに関係なく、Google Play のカタログの外部にカタログ管理システムまたはデータベースがある場合は、Google Play のアプリ構成のカタログと同期しなくなる可能性があります。これは、コンソールでの緊急の手動カタログ変更、カタログ管理システムの停止、最新データの損失などが原因である可能性があります。
カタログ調整プロセスを構築して、不一致期間が長引かないようにすることができます。
差分システムに関する考慮事項
不整合を検出して 2 つのシステムを調整する差分システムを構築することをおすすめします。カタログの同期を維持するために差分システムを構築する際は、次の点を考慮してください。
- データモデルを理解する: 最初のステップは、デベロッパー CMS と Google Play Developer API のデータモデルを理解することです。これには、各システムに保存されているさまざまな種類のデータと、さまざまなデータ要素が相互にマッピングされる方法を把握することが含まれます。
- 差分ルールを定義する: データモデルを理解したら、差分ルールを定義する必要があります。これらのルールによって、2 つのシステムのデータがどのように比較されるかが決まります。たとえば、商品 ID を照合して、定期購入とその関連する基本プランと特典の主要な属性を比較できます。
- 差分アルゴリズムを実装する: 差分ルールを定義したら、差分アルゴリズムを実装する必要があります。このアルゴリズムは、2 つのシステムからデータを取得し、定義したルールに従って比較します。Google Play からカタログデータを取得するには、
monetization.onetimeproducts.list、monetization.onetimeproducts.batchGet、inappproducts.list、inappproducts.batchGet、monetization.subscriptions.list、monetization.subscriptions.batchGetの各メソッドを使用できます。 - 差分レポートを生成する: 差分アルゴリズムによって差分レポートが生成されます。このレポートには、両方のシステムの違いが表示されます。
- 差異を調整する: 差分レポートを生成したら、差異を解決する必要があります。これには、CMS のデータを更新するか、Developer API カタログ管理エンドポイントを使用して Google Play 側のデータを更新する必要があります。これは、通常カタログを更新する方法によって異なります。同期されていない商品を調整するには、商品情報の更新セクションで説明されているように、更新エンドポイントを使用します。
プロダクトのサポート終了
Google Play Developer API には、アイテムのサポート終了を支援する次のメソッドが用意されています。
1 回限りのアイテムの場合:
monetization.onetimeproducts.deletemonetization.onetimeproducts.batchDeleteinappproducts.deleteinappproducts.batchDelete
定期購入商品の場合:
- サブスクリプションの場合は
monetization.subscriptions.delete。1 つ以上の基本プランが有効になっている定期購入は削除できません。
次のようなさまざまなシナリオで、プロダクトの非推奨化が必要になる場合があります。
- 誤って作成した。
- 機能またはサービスの提供を終了する。
商品のサポート終了をカタログ管理戦略に組み込むことをおすすめします。