技術系TIPS
PR

【Google】purchases.subscriptionsv2のAPIとv1の互換性

saratogax
記事内に商品プロモーションを含む場合があります

前回、BillingLibrary5 の登場によって定期購入アイテムの管理が大きく変わった話をしました。

これに伴い、サブスクのマルチラインプラン(以降、複数の基本プランを扱うことをこのように呼ぶこととします)やプリペイドプランなど、提供できるサービスの幅が広がります。

あわせて読みたい
【Google】BillingLibrary5で大きく変わるサブスクの定期購入アイテム
【Google】BillingLibrary5で大きく変わるサブスクの定期購入アイテム

今回は、新しく登場したサブスクリプションの状態を取得する purchases.subscriptionsv2 の API を見ていきましょう。

なお、マルチラインプランやプリペイドプランなどの新しい機能を利用しなければ、既存の purchases.subscriptions の API で対応可能です。

参考資料

新しいアイテム管理に対応したサブスクの移行方法については、以下の 2 つのドキュメントにまとめられています。

2022 年 7 月現在、ドキュメントの中で「Coming Soon」となっている箇所がいくつかありますので、慌てて移行するのは避けたいところですね。

ただ、purchases.subscriptionsv2 の API 自体は利用できる状態なので、事前確認をしておくには良いタイミング。

早速、新しい API の中身を見てみましょう。

サブスクの状態取得結果を比較する

購読中のサブスクの状態については、公式ドキュメントにもサンプルが記載されています。

よって今回は、無料トライアル中や一時停止中(Account Hold)のサブスクを、新旧 2 つの API で比較してみましょうか。

なお、現在時刻は仮に「2022年7月17日」の 0 時としておきます。

無料トライアル中の判定方法

まずは、公式ドキュメントで Coming Soon となっている無料トライアル中のレスポンスを確認してみましょう。

purchases.subscriptions から見ていきます。

有効期限内で paymentState が 2 ということでトライアル中。

このまま放置すれば、有効期限で決済されて購読状態が継続されますね。

{
    "startTimeMillis": "1657983600000",
    "expiryTimeMillis": "1659193200000",
    "autoRenewing": true,
    "priceCurrencyCode": "JPY",
    "priceAmountMicros": "1000000000",
    "countryCode": "JP",
    "developerPayload": "",
    "paymentState": 2,
    "orderId": "GPA.9999-9999-9999-9999",
    "acknowledgementState": 1,
    "kind": "androidpublisher#subscriptionPurchase"
}

では、このサブスクを purchases.subscriptionsv2 の API で見てみましょう。

購読しているアイテムの情報が lineItems の配列に入ってきているのは想定通り。

この中に「商品コード」「有効期限」「購読状態」が含まれています。

lineItems には別の基本プランや特典の情報が入ってきそうですね。

{
    "kind": "androidpublisher#subscriptionPurchaseV2",
    "startTime": "2022-07-17T00:00:00.000Z",
    "regionCode": "JP",
    "subscriptionState": "SUBSCRIPTION_STATE_ACTIVE",
    "latestOrderId": "GPA.9999-9999-9999-9999",
    "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
    "lineItems": [
        {
            "productId": "example_product",
            "expiryTime": "2022-07-31T00:00:00.000Z",
            "autoRenewingPlan": {
                "autoRenewEnabled": true
            }
        }
    ]
}

日付の項目がミリ秒から日付型になっているので、見た目はわかりやすくなりましたがシステムで扱う際には変換が必要になってくるかな。

あわせて読みたい
【Kotlin】タイムスタンプからRFC3339 UTC「Zulu」形式の日付フォーマット作成
【Kotlin】タイムスタンプからRFC3339 UTC「Zulu」形式の日付フォーマット作成
メモ

2023 年 2 月現在、autoRenewingPlan の中に recurringPrice の項目が増えていますが、公式のドキュメントにはまだ情報がありません。また第 1 階層に etag の項目も追加されていますが、こちらの使い道は思いつかないので情報待ちですね。

以下は、recurringPrice と etag が追加されたケース。

{
    "lineItems": [
        {
            "productId": "example_product",
            "expiryTime": "2022-07-31T00:00:00.000Z",
            "autoRenewingPlan": {
                "autoRenewEnabled": true,
                "recurringPrice": {
                    "currencyCode": "JPY",
                    "units": "1000"
                }
            }
        }
    ],
    "etag": "example_etag"
}

無料トライアル中が判定できない問題

親要素に「サブスクの状態」「注文ID」「承認状態」があるので、サブスクの現在の状態についてはここだけ確認しておけば良さそう。

ただ冒頭でも書いた通り、トライアル中かどうかの情報が含まれていないので、トライアル判定ができないのですよね・・・。

これは GooglePlay 側の対応を待つしかありません。

親要素の subscriptionState にトライアル状態、lineItems にトライアル特典の詳細が入るイメージかな。

GooglePlayBilling】purchases.subscriptionsv2のAPIとv1の互換性 Free trial coming soon
メモ

2022 年 11 月に、無料トライアルについては Coming Soon の記載がなくなりました。その代わりとなるものがないのですが、lineItems の中に offerDetails というオファー情報が含まれるようになりました。ここで、offerTags などを利用して無料トライアルを表現するしかないのでしょうか。

Apple の v2 や StoreKit2 にも言えますが、機能をドロップするのは自由にしてもらったらいいのですが、代替案を示してくれるといいのですけどね。

上の画像と見比べるとわかりますが、Google のドキュメントからはしれっと「Coming Soon」が消されました。

GooglePlayBilling】purchases.subscriptionsv2のAPIとv1の互換性 Free trial coming soon

一時停止中(Account Hold)

トライアル中の状態を見ておけば想像が付くと思いますが、念のため Account Hold の状態も比較しておきましょう。

まずは purchases.subscriptions から。

有効期限が過去で paymentState が 0 ということで Account Hold なのがわかりますね。

{
    "startTimeMillis": "1656601200000",
    "expiryTimeMillis": "1657983600000",
    "autoRenewing": true,
    "priceCurrencyCode": "JPY",
    "priceAmountMicros": "1000000000",
    "countryCode": "JP",
    "developerPayload": "",
    "paymentState": 0,
    "orderId": "GPA.9999-9999-9999-9999..1",
    "acknowledgementState": 1,
    "kind": "androidpublisher#subscriptionPurchase"
}

では、purchases.subscriptionsv2 の API でも確認してみます。

やはり subscriptionState の項目ができたのは大きいですね。

以前は複合的に見ないとサブスクの状態がわかりにくかったですが、一目でわかるようになりました。

{
    "kind": "androidpublisher#subscriptionPurchaseV2",
    "startTime": "2022-07-01T00:00:00.000Z",
    "regionCode": "JP",
    "subscriptionState": "SUBSCRIPTION_STATE_ON_HOLD",
    "latestOrderId": "GPA.9999-9999-9999-9999..1",
    "acknowledgementState": "ACKNOWLEDGEMENT_STATE_ACKNOWLEDGED",
    "lineItems": [
        {
            "productId": "example_product",
            "expiryTime": "2022-07-17T00:00:00.000Z",
            "autoRenewingPlan": {
                "autoRenewEnabled": true
            }
        }
    ]
}

subscriptionState が「SUBSCRIPTION_STATE_ON_HOLD」になっているように、それぞれの状態の Enum 値が用意されています。

トライアルの状態はどのように表現されるのか、ドキュメントに反映されたら要チェックですね。

・SUBSCRIPTION_STATE_UNSPECIFIED
・SUBSCRIPTION_STATE_PENDING
・SUBSCRIPTION_STATE_ACTIVE
・SUBSCRIPTION_STATE_PAUSED
・SUBSCRIPTION_STATE_IN_GRACE_PERIOD
・SUBSCRIPTION_STATE_ON_HOLD
・SUBSCRIPTION_STATE_CANCELED
・SUBSCRIPTION_STATE_EXPIRED

まとめ

GooglePlay Billing の purchases.subscriptionsv2 の API について調べてみました。

まだ完全な状態ではないので、すぐに移行する必要はないですが動向は追いかけておきたいですね。

サブスクの状態管理が楽になるのと、既存の API との互換性は保ってくれるので、Coming Soon の項目が対応されたら移行の価値ありと思っています。

新しい機能にどれくらいのビジネス的な価値があるかですが、プリペイドプランはユーザにとっては便利そうですね。

例えば WOWOW で、テニスの 4 大大会の準々決勝以降の数日間とか、錦織選手の試合だけとかが切り売りされたらお金払って見たくなりますもんね。

ABOUT ME
saratoga
saratoga
フリーランスエンジニア
仕事にも趣味にも IT を駆使するフリーランスエンジニア。技術的な TIPS や日々の生活の中で深堀りしてみたくなったことを備忘録として残していきます。
記事URLをコピーしました