Google Play の課金システムは、Android アプリでデジタル商品とデジタル コンテンツを販売するためのサービスです。2022 年 5 月のリリースでは、定期購入商品の定義方法が変更されました。これは定期購入商品のアプリ内での販売方法とバックエンドでの管理方法に影響します。Google Play 請求サービスを初めて統合する場合は、統合を開始する際に準備するをお読みください。
2022 年 5 月より前に Google Play 請求サービスを利用して定期購入を販売していた場合は、既存の定期購入を維持しつつ新機能を導入する方法を理解することが重要です。
最も重要な点は、既存の定期購入、アプリ、バックエンドの統合は、すべて 2022 年 5 月のリリースより前と同様に機能するということです。今すぐ変更を行う必要はありません。時間をかけて新機能を導入できます。Google Play Billing Library の各メジャー リリースは、リリース以降 2 年間サポートされます。Google Play Developer API との既存の統合は、これまでどおり機能します。
2022 年 5 月の更新の概要は次のとおりです。
- 新しい Google Play Console では、定期購入、基本プラン、特典を作成し、管理できます。これには、新規の定期購入と移行された定期購入の両方が含まれます。
- Play Developer API には、API 形式で新しい Google Play Console UI 機能をサポートするための更新が含まれています。特に注目していただきたいのは、新しいバージョンの Subscription Purchases API です。この API では、定期購入のステータスを確認し、定期購入の購入を管理できます。
- 新しい Play Billing Library バージョン 5 を使用すると、アプリは定期購入のすべての新機能を活用できます。バージョン 5 にアップグレードする準備が整ったら、移行ガイドのガイダンスに沿って移行してください。
定期購入の構成
Google Play Console で定期購入を管理する
2022 年 5 月、Google Play Console にいくつかの変更が行われました。
単一の定期購入に、複数の基本プランと特典を設定できるようになりました。以前に作成された定期購入 SKU は、新しい定期購入、基本プラン、および特典オブジェクトとして Google Play Console に表示されます。Google Play Console 上の定期購入に関する最新の変更をまだ確認していない場合は、新しいオブジェクトの機能や構成に関する説明をご覧ください。既存の定期購入アイテムは、すべてこの新しい形式で Google Play Console に表示されます。各 SKU は、単一の基本プランと下位互換性のある特典（該当する場合）を含む定期購入オブジェクトによって表されます。
以前の統合では、各定期購入に単一の特典（SkuDetails オブジェクトで表されます）が含まれることが想定されていたため、各定期購入に下位互換性のある単一の基本プランまたは特典を含めることができます。下位互換性のない基本プランまたは特典は、非推奨になった querySkuDetailsAsync() メソッドを使用しているアプリでは、SKU の一部として返されます。下位互換性のある特典の構成方法と管理方法の詳細については、定期購入について理解するをご覧ください。アプリが queryProductDetailsAsync() のみを使用していて、まだ購入を行っている以前のバージョンのアプリがない場合、下位互換性のある特典を利用する必要はなくなりました。
Subscriptions Publishing API で定期購入を管理する
Play Developer API には、定期購入の購入のための新機能が含まれています。SKU 管理用の inappproducts API は、1 回だけの購入アイテムや定期購入の処理を含めて、これまでどおり機能します。したがって、現在使用している統合を維持するために今すぐ変更を行う必要はありません。
ただし、Google Play Console は新しい定期購入エンティティのみを使用するので、注意してください。Google Play Console で定期購入の編集を行うと、それ以降は inappproducts API を定期購入に使用できなくなります。
2022 年 5 月より前に Publishing API を使用している場合、問題が発生しないように、既存の定期購入は Google Play Console ですべて読み取り専用として表示されます。変更しようとすると、この制約に関する警告が表示される場合があります。Google Play Console で定期購入を編集する前に、新しい Subscription Publishing エンドポイントを使用できるよう、バックエンドの統合を事前に更新してください。新しい monetization.subscriptions、monetization.subscriptions.baseplans、monetization.subscriptions.offers エンドポイントを使用すると、すべての利用可能な基本プランと特典を管理できます。InAppProduct エンティティのフィールドが monetization.subscriptions の新しいオブジェクトのフィールドにどのようにマッピングされているかを、次の表に示します。
| InAppProduct | 定期購入 |
|---|---|
packageName |
packageName |
sku |
productId |
status |
basePlans[0].state |
prices |
basePlans[0].regionalConfigs.price |
listings |
リスト |
defaultPrice |
対応要素なし |
subscriptionPeriod |
basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod |
basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod |
basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings |
taxAndComplianceSettings |
この必須 API の更新は、Publishing API（SKU 管理）にのみ適用されます。
Play Billing Library の変更点
段階的な移行をサポートするため、Play Billing Library には、以前のバージョンで利用できるすべてのメソッドとオブジェクトが含まれています。SkuDetails オブジェクトと querySkuDetailsAsync() などの関数はこれまでどおり存在しているので、今すぐ既存の定期購入コードを更新しなくても、アップグレードして新機能を使用できます。また、それらのメソッドを下位互換性ありとしてマークすることにより、どの特典が利用可能かを管理できます。
従来のメソッドを保持するだけでなく、新しいエンティティと機能を処理するために、Play Billing Library 5 には新しい ProductDetails オブジェクトと、対応する queryProductDetailsAsync() メソッドが追加されています。既存のアプリ内アイテム（1 回だけの購入アイテムと消費可能アイテム）も、ProductDetails によってサポートされます。
定期購入の場合、ProductDetails.getSubscriptionOfferDetails() は、ユーザーが購入できるすべての基本プランと特典のリストを返します。つまり、下位互換性にかかわらず、ユーザーが利用できるすべての基本プランと特典にアクセスできます。getSubscriptionOfferDetails() は、定期購入以外の商品については null を返します。1 回だけの購入については、getOneTimePurchaseOfferDetails() を使用できます。
Play Billing Library 5 には、購入フローを開始する新しいメソッドと従来のメソッドの両方が含まれています。BillingClient.launchBillingFlow() に渡される BillingFlowParams オブジェクトが SkuDetails オブジェクトを使用して構成されている場合、システムは、SKU に対応した下位互換性のある基本プランまたは特典から、販売する特典の情報を抽出します。BillingClient.launchBillingFlow() に渡される BillingFlowParams オブジェクトが ProductDetailsParams オブジェクト（これには ProductDetails と、販売する特典の固有の特典トークンを表す String が含まれます）を使用して構成されている場合、システムは、ユーザーが獲得するアイテムを識別するための情報を使用します。
queryPurchasesAsync() は、ユーザーが所有するすべての購入を返します。リクエストされた商品のタイプを示すには、以前のバージョンと同様に BillingClient.SkuType 値を渡すか、または新しい定期購入エンティティを表す BillingClient.ProductType 値を含む QueryPurchasesParams オブジェクトを渡します。
これらの定期購入の新機能を活用できるように、早めにバージョン 5 のライブラリにアプリを更新することをおすすめします。
定期購入のステータスを管理する
このセクションでは、バージョン 5 への移行時に実装する必要がある Google Play 請求サービス統合のバックエンド コンポーネントの主な変更点について説明します。
リアルタイム デベロッパー通知
まもなく SubscriptionNotification オブジェクトに subscriptionId が含まれなくなります。定期購入商品の特定にこのフィールドを使用している場合は、通知を受け取ったら purchases.subscriptionv2:get を使用して更新し、定期購入のステータスからこの情報を取得する必要があります。購入ステータスの一部として返される lineItems コレクションの各 SubscriptionPurchaseLineItem 要素には、対応する productId が含まれます。
Subscriptions Purchases API: 定期購入のステータスを取得する
以前のバージョンの Subscriptions Purchases API では、purchases.subscriptions:get を使用して定期購入のステータスを照会できました。このエンドポイントは変更されておらず、下位互換性のある定期購入の購入ではこれまでどおり機能します。このエンドポイントは、2022 年 5 月にリリースされた新機能をサポートしていません。
新しいバージョンの Subscriptions Purchases API では、purchases.subscriptionsv2:get を使用して定期購入の購入ステータスを取得します。この API は、移行された定期購入、新しい定期購入（プリペイドと自動更新の両方）、およびすべてのタイプの購入と互換性があります。このエンドポイントを使用して、通知を受信したときに定期購入のステータスを確認できます。返されるオブジェクト SubscriptionPurchaseV2 には新しいフィールドが含まれていますが、既存の定期購入をサポートするために必要な従来のデータもこれまでどおり含まれています。
SubscriptionPurchaseV2 フィールド（プリペイド プランの場合）
自動更新されず、ユーザーによって延長されるプリペイド プランをサポートするため、新しいフィールドが追加されました。すべてのフィールドは、自動更新される定期購入と同様に、プリペイド プランに適用されます。ただし、次の例外があります。
- [新しいフィールド] lineItems[0].prepaid_plan.allowExtendAfterTime: ユーザーは未消費のチャージを一度に 1 つしか設定できないため、ユーザーがプリペイド プランを延長するためにもう一つチャージを購入できる時期を示します。
- [新しいフィールド] SubscriptionState: 定期購入オブジェクトのステータスを示します。プリペイド プランの場合、この値は常に
ACTIVE、PENDING、CANCELEDのいずれかになります。 - lineItems[0].expiryTime: プリペイド プランの場合、このフィールドは常に存在します。
- paused_state_context: プリペイド プランは一時停止できないため、このフィールドは存在しません。
- lineItems[0].auto_renewing_plan: プリペイド プランの場合は存在しません。
- canceled_state_context: このフィールドは定期購入を自発的に解約するユーザーにのみ適用されるため、プリペイド プランの場合は存在しません。
- lineItems[0].productId: このフィールドは、以前のバージョンの
subscriptionIdに代わるものです。
SubscriptionPurchaseV2 フィールド（定期購入の場合）
purchases.subscriptionv2 には、新しい定期購入オブジェクトに関する詳細情報を提供する新しいフィールドが含まれています。従来の定期購入エンドポイントのフィールドが、purchases.subscriptionv2 の対応するフィールドにどのようにマッピングされているかを次の表に示します。
| SubscriptionPurchase | SubscriptionPurchaseV2 |
|---|---|
countryCode |
regionCode |
orderId |
latestOrderId |
| （対応するフィールドなし） | lineItems（購入により獲得されたアイテムを表す SubscriptionPurchaseLineItem のリスト） |
| （対応するフィールドなし） | lineItems.offerDetails.basePlanId |
| （対応するフィールドなし） | lineItems.offerDetails.offerId |
| （対応するフィールドなし） | lineItems.offerDetails.offerTags |
startTimeMillis |
startTime |
expiryTimeMillis |
lineItems.expiryTime（購入により獲得された定期購入にはそれぞれ固有の expiryTime があります） |
| （対応するフィールドなし） | subscriptionState（定期購入のステータスを示します） |
| （対応するフィールドなし） | pausedStateContext（定期購入のステータスが SUBSCRIPTION_STATE_PAUSED の場合にのみ存在します） |
autoResumeTimeMillis |
pausedStateContext.autoResumeTime |
| （対応するフィールドなし） | canceledStateContext（定期購入のステータスが SUBSCRIPTION_STATE_CANCELED の場合にのみ存在します） |
| （対応するフィールドなし） | testPurchase（ライセンスを付与されたテスターの購入にのみ存在します） |
autoRenewing |
lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode、priceAmountMicros |
lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo |
（対応するフィールドなし） この情報は、購入された各定期購入の offer で確認できます。 |
| developerPayload | （対応するフィールドなし）デベロッパー ペイロードは非推奨になりました |
| paymentState | （対応するフィールドなし） 支払いステータスは次のように subscriptionState から推測できます。
|
cancelReason、userCancellationTimeMillis、cancelSurveyResult |
canceledStateContext |
linkedPurchaseToken |
linkedPurchaseToken （変更なし） |
purchaseType |
テスト: testPurchase を使用プロモーション: signupPromotion |
priceChange |
lineItems.autoRenewingPlan.priceChangeDetails |
profileName、emailAddress、givenName、familyName、profileId |
subscribeWithGoogleInfo |
acknowledgementState |
acknowledgementState (no change) |
promotionType、promotionCode |
signupPromotion |
externalAccountId、obfuscatedExternalAccountId、obfuscatedExteranlProfileId |
externalAccountIdentifiers |
定期購入管理のためのその他の関数
purchases.subscriptions:get は purchases.subscriptionsv2:get にアップグレードされましたが、現在のところ purchases.subscriptions エンドポイントではデベロッパー向けの定期購入管理のための残りの関数は変更されていないため、purchases.subscriptions:acknowledge、purchases.subscriptions:cancel、purchases.subscriptions:defer、purchases.subscriptions:refund、purchases.subscriptions:revoke はこれまでどおり使用できます。
Pricing API
monetization.convertRegionPrices エンドポイントでは、Google Play Console を使用する場合と同様に、地域ごとの価格を計算できます。このメソッドは、Google Play がサポートする任意の通貨で単一の価格を受け取り、Google Play が購入をサポートするすべての地域における換算価格（該当する場合はデフォルトの税率を含む）を返します。