このガイドでは、デベロッパーが Engage SDK を使用してアプリの定期購入と利用資格のデータを Google TV と共有する手順について説明します。ユーザーは、利用できるコンテンツを見つけ、Google TV でテレビ、モバイル、タブレットの Google TV エクスペリエンス内で、ユーザーに最も関連性の高いコンテンツの推奨事項を直接提供できるようにします。
前提条件
デバイス利用資格 API を使用するには、メディア アクション フィードのオンボーディングが必要です。まだ完了していない場合は、メディア アクション フィードのオンボーディング プロセスを完了します。
事前作業
始める前に、次の手順を完了してください。 この統合でアプリが API レベル 19 以降を対象にしていることを確認する
アプリに
com.google.android.engageライブラリを追加します。統合で使用する SDK は、モバイルアプリ用とテレビアプリ用の 2 つに分かれています。
モバイルの場合
dependencies { implementation 'com.google.android.engage:engage-core:1.5.5 }テレビ
dependencies { implementation 'com.google.android.engage:engage-tv:1.0.2 }AndroidManifest.xmlファイルで Engage サービスの環境を本番環境に設定します。モバイル APK の場合
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>テレビ用 APK
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>APK を Google に送信する前に、AndroidManifest.xml ファイルでエンゲージメント サービス環境を本番環境に設定します。最適なパフォーマンスと将来の互換性を確保するため、アプリがフォアグラウンドにあり、ユーザーがアプリを起動したり、ログイン後にアプリをアクティブに使用したりするなど、アプリを積極的に操作している場合にのみデータを公開します。バックグラウンド プロセスからの公開は推奨されません。
次のイベントで定期購入情報を公開します。
- ユーザーがアプリにログインします。
- ユーザーがプロファイルを切り替えます（プロファイルがサポートされている場合）。
- ユーザーが新しい定期購入を購入します。
- ユーザーが既存の定期購入をアップグレードする。
- ユーザーの定期購入の有効期限が切れます。
統合
このセクションでは、さまざまなサブスクリプション タイプを管理するために AccountProfile と SubscriptionEntity を実装する際に必要なコードサンプルと手順について説明します。
ユーザー アカウントとプロフィール
Google TV でパーソナライズされた機能を利用するには、アカウント情報を入力します。AccountProfile を使用して、次の情報を指定します。
- アカウント ID: ユーザーのアカウントを表す一意の識別子。実際のアカウント ID または適切に難読化されたバージョンを指定できます。
// Set the account ID to which the subscription applies.
// Don't set the profile ID because subscription applies to account level.
val accountProfile = AccountProfile.Builder()
.setAccountId("user_account_id")
.setProfileId("user_profile id")
.build();
一般的な階層の定期購入
メディア プロバイダ サービスの基本サブスクリプション（すべての有料コンテンツへのアクセス権を付与する 1 つのサブスクリプション ティアがあるサービスなど）をご利用のユーザー向けに、次の重要な詳細情報を提供します。
定期購入のタイプ: ユーザーが利用している特定の定期購入プランを明確に示します。
SUBSCRIPTION_TYPE_ACTIVE: ユーザーが有効な有料サブスクリプションを利用している。SUBSCRIPTION_TYPE_ACTIVE_TRIAL: ユーザーがトライアル サブスクリプションを利用している。SUBSCRIPTION_TYPE_INACTIVE: ユーザーはアカウントを持っているが、有効な定期購入やトライアルがない。
有効期限: オプションのミリ秒単位の時間。定期購入の有効期限を指定します。
プロバイダ パッケージ名: 定期購入を処理するアプリのパッケージ名を指定します。
サンプル メディア プロバイダ フィードの例。
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Basic common name",
"commonTier": true
}
次の例では、ユーザーの SubscriptionEntity を作成します。
val subscription = SubscriptionEntity
.Builder()
setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build();
プレミアム定期購入
アプリが、一般的な階層を超える拡張コンテンツや機能を含む、複数階層のプレミアム サブスクリプション パッケージを提供している場合は、Subscription に 1 つ以上の利用資格を追加して、これを表します。
この利用資格には次のフィールドがあります。
- 識別子: この利用資格に必要な識別子文字列。これは、Google TV に公開されたメディア プロバイダのフィードで提供される利用資格 ID のいずれかと一致する必要があります（ID フィールドではありません）。
- 名前: 補助情報であり、利用資格の照合に使用されます。省略可能ですが、人が読める利用資格名を指定すると、デベロッパーとサポートチームの両方がユーザーの利用資格を理解しやすくなります。例: Sling Orange。
- Expiration TimeMillis: サブスクリプションの有効期限と異なる場合は、この利用資格の有効期限をミリ秒単位で指定します。デフォルトでは、利用資格はサブスクリプションの有効期限とともに期限切れになります。
次のサンプル メディア プロバイダ フィード スニペットの場合:
"actionAccessibilityRequirement": [
{
"@type": "ActionAccessSpecification",
"category": "subscription",
"availabilityStarts": "2022-06-01T07:00:00Z",
"availabilityEnds": "2026-05-31T07:00:00Z",
"requiresSubscription": {
"@type": "MediaSubscription",
// Don't match this string,
// ID is only used to for reconciliation purpose
"@id": "https://www.example.com/971bfc78-d13a-4419",
// Don't match this, as name is only used for displaying purpose
"name": "Example entitlement name",
"commonTier": false,
// match this identifier in your API. This is the crucial
// entitlement identifier used for recommendation purpose.
"identifier": "example.com:entitlementString1"
}
次の例では、定期購入ユーザーの SubscriptionEntity を作成します。
// Subscription with entitlements.
// The entitlement expires at the same time as its subscription.
val subscription = SubscriptionEntity
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
// matches with the identifier in media provider feed
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
.build()
)
.build();
// Subscription with entitlements
// The entitement has different expiration time from its subscription
val subscription = SubscriptionEntity
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds
.setExpirationTimeMillis(1767052800000)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setEntitlementId("example.com:entitlementString1")
.setDisplayName("entitlement name1")
// You may set the expiration time for entitlement
// December 15, 2025 10:00:00 AM in milliseconds
.setExpirationTimeMillis(1765792800000)
.build())
.build();
リンクされたサービス パッケージのサブスクリプション
通常、定期購入は元のアプリのメディア プロバイダに属しますが、定期購入内でリンクされたサービス パッケージ名を指定することで、リンクされたサービス パッケージに定期購入を関連付けることができます。
次のコードサンプルは、ユーザー サブスクリプションを作成する方法を示しています。
// Subscription for linked service package
val subscription = SubscriptionEntity
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("com.google.android.example")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.build();
また、ユーザーが子会社のサービスを別途定期購入している場合は、別の定期購入を追加し、リンクされたサービス パッケージ名を適宜設定します。
// Subscription for linked service package
val linkedSubscription = Subscription
.Builder()
.setSubscriptionType(
SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE
)
.setProviderPackageName("linked service package name")
// Optional
// December 30, 2025 12:00:00AM in milliseconds since epoch
.setExpirationTimeMillis(1767052800000)
.addBundledSubscription(
BundledSubscription.Builder()
.setBundledSubscriptionProviderPackageName(
"bundled-subscription-package-name"
)
.setSubscriptionType(SubscriptionType.SUBSCRIPTION_TYPE_ACTIVE)
.setExpirationTimeMillis(111)
.addEntitlement(
SubscriptionEntitlement.Builder()
.setExpirationTimeMillis(111)
.setDisplayName("Silver subscription")
.setEntitlementId("subscription.tier.platinum")
.build()
)
.build()
)
.build();
必要に応じて、リンクされたサービス サブスクリプションにも利用資格を追加します。
定期購入セットを提供する
アプリがフォアグラウンドにある間にコンテンツ公開ジョブを実行します。
AppEngagePublishClient クラスの publishSubscriptionCluster() メソッドを使用して、SubscriptionCluster オブジェクトを公開します。
isServiceAvailable を使用して、サービスを統合に使用できるかどうかを確認します。
client.publishSubscription(
PublishSubscriptionRequest.Builder()
.setAccountProfile(accountProfile)
.setSubscription(subscription)
.build();
)
setSubscription() を使用して、ユーザーがサービスへのサブスクリプションを 1 つだけ持つようにします。
リンクされた定期購入のリストを受け取る addLinkedSubscription() または addLinkedSubscriptions() を使用して、ユーザーが 0 個以上のリンクされた定期購入を持つことができるようにします。
サービスがリクエストを受信すると、新しいエントリが作成され、古いエントリは 60 日後に自動的に削除されます。システムは常に最新のエントリを使用します。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
サブスクリプションを最新の状態に保つ
- 変更時に即座に更新を提供するには、ユーザーの定期購入の状態（有効化、無効化、アップグレード、ダウングレードなど）が変更されるたびに
publishSubscriptionCluster()を呼び出します。 継続的な精度を定期的に検証するには、少なくとも月に 1 回
publishSubscriptionCluster()を呼び出します。動画検出データを削除するには、標準の 60 日間の保持期間が経過する前に、Google TV サーバーからユーザーのデータを手動で削除します。この場合は、
client.deleteClusters()メソッドを使用します。これにより、指定されたDeleteReasonに応じて、アカウント プロファイルまたはアカウント全体の既存の動画検出データがすべて削除されます。ユーザーの定期購入を削除するコード スニペット
// If the user logs out from your media app, you must make the following call // to remove subscription and other video discovery data from the current // google TV device. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile( AccountProfile .Builder() .setAccountId() .setProfileId() .build() ) .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT) .build() ) ``` Following code snippet demonstrates removal of user subscription when user revokes the consent. ```Kotlin // If the user revokes the consent to share across device, make the call // to remove subscription and other video discovery data from all google // TV devices. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile( AccountProfile .Builder() .setAccountId() .setProfileId() .build() ) .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT) .build() ) ``` Following code demonstrates how to remove subscription data on user profile deletion. ```Kotlin // If the user delete a specific profile, you must make the following call // to remove subscription data and other video discovery data. client.deleteClusters( new DeleteClustersRequest.Builder() .setAccountProfile( AccountProfile .Builder() .setAccountId() .setProfileId() .build() ) .setReason(DeleteReason.DELETE_REASON_ACCOUNT_PROFILE_DELETION) .build() )
テスト
このセクションでは、定期購入の実装をテストする手順を説明します。リリース前にデータの正確性と適切な機能を確認します。
統合の公開チェックリスト
公開は、アプリがフォアグラウンドにあり、ユーザーがアプリを操作しているときに行う必要があります。
公開するタイミング:
- ユーザーが初めてログインします。
- ユーザーがプロフィールを変更する（プロフィールがサポートされている場合）。
- ユーザーが新しい定期購入を購入します。
- ユーザーがサブスクリプションをアップグレードします。
- ユーザーの定期購入の有効期限が切れます。
ログキャットで、アプリが公開イベントで
isServiceAvailable()API とpublishClusters()API を正しく呼び出しているかどうかを確認します。検証用アプリにデータが表示されていることを確認します。検証用アプリでは、サブスクリプションが別々の行として表示されます。公開 API が呼び出されると、検証用アプリにデータが表示されます。
- アプリの Android マニフェスト ファイルで、Engage Service Flag が本番環境に設定されていないことを確認します。
- Engage Verification アプリをインストールして開きます。
- 検証アプリで
isServiceAvailableの値がfalseの場合は、検証アプリ内のToggleボタンをクリックしてtrueに設定します。 - アプリのパッケージ名を入力します。公開されたデータが自動的に表示されます。
アプリに移動し、次の操作を行います。
- ログインします。
- プロファイルを切り替える（サポートされている場合）。
- 新しい定期購入を購入します。
- 既存の定期購入をアップグレードします。
- サブスクリプションの有効期限が切れます。
統合を検証する
統合をテストするには、を使用します。
検証用アプリは、デベロッパーが統合が適切に機能しているか確認するための Android アプリです。このアプリには、データやブロードキャスト インテントを検証する際に役立つ機能が含まれています。これにより、リリース前にデータの精度と適切な機能を検証できます。
- 各イベントについて、アプリが
publishSubscriptionAPI を呼び出したかどうかを確認します。検証用アプリで公開されたデータを確認します。 検証用アプリですべてが緑色になっていることを確認する エンティティのすべての情報が正しい場合は、すべてのエンティティに「All Good」の緑色のチェックマークが表示されます。
図 1. サブスクリプションの登録が完了しました 問題は確認アプリでもハイライト表示されます
図 2.登録に失敗しました バンドルされたサブスクリプションの問題を確認するには、テレビのリモコンを使用してその特定のバンドルされたサブスクリプションにフォーカスし、クリックして問題を表示します。まず行にフォーカスを合わせてから右に移動して、バンドル サブスクリプション カードを見つける必要がある場合があります。図 3 に示すように、問題は赤色でハイライト表示されます。また、リモコンを使用して下に移動し、バンドルされたサブスクリプション内の利用資格の問題を確認します。
図 3.サブスクリプション エラー 利用資格の問題を確認するには、テレビのリモコンを使用してその利用資格にフォーカスし、クリックして問題を表示します。問題は赤色でハイライト表示されます。
図 4.サブスクリプション エラーの詳細
ダウンロード
ダウンロードする前に、次の利用規約に同意する必要があります。