Google Play Billing Library 4 から 5 への移行ガイド

このトピックでは、Google Play Billing Library 4 から Google Play Billing Library 5 に移行する方法と、定期購入の新機能を使用する方法について説明します。

概要

Google Play Billing Library 5 では、「定期購入の基本プラン」と「定期購入の特典」という機能が導入されました。これらの機能により、以前のバージョンより定期購入の販売方法の幅がさらに広がるとともに、統合の複雑さも軽減されました。

基本プランは Google Play Console または Play Developer API を使用して設定します。1 つの定期購入に複数の基本プラン（それぞれに複数の特典付き）を設定できます。定期購入の特典では、柔軟な価格モデルと利用資格オプションを提供することが可能です。さまざまな自動更新プランとプリペイドプランを使用して、定期購入ライフサイクル全体を通して複数の特典を作成できます。詳しくは、統合ガイドをご覧ください。

移行手順

Google Play Billing Library を更新する

アプリの build.gradle ファイルで、既存の Play Billing Library の依存関係を更新後のバージョンに置き換えます。

dependencies {
    def billingVersion = "5.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

メソッドの呼び出しを修正していなくても、プロジェクトはすぐにビルドされます。これは、Play Billing Library 5 で下位互換性が追加されたためです。ただし、SKU というコンセプトは使用しないことになりました。

BillingClient を初期化し、Google Play への接続を確立する

Android アプリから購入を開始するための最初のステップに変更はありません。

購入可能なアイテムを表示する

ユーザーが購入できるすべての特典を取得するには:

SkuDetailsParams を QueryProductDetailsParams に置き換えます。
BillingClient.querySkuDetailsAsync() の呼び出しを、BillingClient.queryProductDetailsAsync() を使用するように切り替えます。

クエリ結果が SkuDetails から ProductDetails に変化しているはずです。個々の ProductDetails アイテムには、アイテムに関する情報（ID、タイトル、タイプなど）が含まれています。定期購入アイテムの場合、ProductDetails には List<ProductDetails.SubscriptionOfferDetails>（定期購入の特典の詳細を示すリスト）が含まれています。1 回だけの購入アイテムの場合、ProductDetails には ProductDetails.OneTimePurchaseOfferDetails が含まれています。これらを使用して、どの特典をユーザーに表示するかを決定できます。

次の例は、アプリの変更前と変更後のコードを示しています。

変更前

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS)

billingClient.querySkuDetailsAsync(params.build()) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS);

billingClient.querySkuDetailsAsync(params.build(),
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

変更後

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList)

billingClient.queryProductDetailsAsync(params.build()) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

queryProductDetailsAsync のコールバックは List<ProductDetails> を返します。個々の ProductDetails アイテムには、アイテムに関する情報（ID、タイトル、タイプなど）が含まれています。主な違いは、定期購入アイテムには、ユーザーが購入できるすべての特典を含む List<ProductDetails.SubscriptionOfferDetails> も表示されるようになったことです。

以前のバージョンの Play Billing Library は新しいオブジェクト（定期購入、基本プラン、特典など）をサポートしていないため、新しいシステムではこれまでの定期購入 SKU をそれぞれ下位互換性のある基本プランと特典に変換します。在庫のある 1 回だけ購入アイテムも ProductDetails オブジェクトに移行されています。1 回だけの購入アイテムの特典の詳細にアクセスするには、getOneTimePurchaseOfferDetails() メソッドを使用します。

特典購入フローを開始する

特典購入フローを開始する方法は、SKU のフローを開始する方法と非常によく似ています。バージョン 5 で購入リクエストを開始する方法は次のとおりです。

BillingFlowParams には、SkuDetails でなく ProductDetailsParams を使用します。
特典の詳細は SubscriptionOfferDetails オブジェクトを使用して取得できます。

ユーザーが選択した特典付きでアイテムを購入するには、選択された特典の offerToken を取得して ProductDetailsParams オブジェクトに渡します。

BillingFlowParams オブジェクトの作成後、BillingClient で請求フローを開始する方法に変更はありません。

次の例は、アプリの変更前と変更後のコードを示しています。

変更前

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

変更後

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;
// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
val offerToken = productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken

val productDetailsParamsList =
    listOf(
        BillingFlowParams.ProductDetailsParams.newBuilder()
            .setProductDetails(productDetails)
            .setOfferToken(offerToken)
            .build()
    )
val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(productDetailsParamsList)
        .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// Retrieve a value for "productDetails" by calling queryProductDetailsAsync()
// Get the offerToken of the selected offer
String offerToken = productDetails
                     .getSubscriptionOfferDetails()
                     .get(selectedOfferIndex)
                     .getOfferToken();
// Set the parameters for the offer that will be presented
// in the billing flow creating separate productDetailsParamsList variable
ImmutableList<ProductDetailsParams> productDetailsParamsList =
        ImmutableList.of(
                 ProductDetailsParams.newBuilder()
                     .setProductDetails(productDetails)
                     .setOfferToken(offerToken)
                     .build()
        );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(productDetailsParamsList)
            .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

購入を処理する

Google Play Billing Library 5 で購入を処理する方法は、以前のバージョンと似ています。

ユーザーが所有するアクティブな購入をすべて取得して新しい購入を照会するには、次の手順を実施します。

BillingClient.SkuType 値を queryPurchasesAsync() に渡す代わりに、BillingClient.ProductType 値を含む QueryPurchasesParams オブジェクトを渡します。

次の例は、アプリの変更前と変更後のコードを示しています。

変更前

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java


billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List&lt;Purchase> purchases) {
            // process the result
        }
    }
);

変更後

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

アプリ外で行われた購入と保留中の取引を管理する手順に変更はありません。

定期購入のステータスを管理する

ステータスを確認し、定期購入の購入を管理する定期購入ステータス管理コンポーネントがバックエンドに存在する場合は、Subscription Purchases API を使用する必要があります。以前のバージョンからの変更点の詳細については、2022 年 5 月の定期購入の新機能に関するガイドをご覧ください。