このページは Cloud Translation API によって翻訳されました。

Engage SDK Cluster の公開ガイドライン

このガイドには、デベロッパーが Engage SDK を統合する際に使用できるクラスタ公開に関するガイドラインが記載されています。

おすすめコンテンツのタイプ	コンテンツの更新頻度に関する戦略	コンテンツの更新頻度に関するガイドライン
パーソナライズされたおすすめコンテンツ	緩め 1 日 1 回更新して、ユーザーが毎日新しいおすすめコンテンツを確認できるようにすることを推奨します。	どのようなおすすめコンテンツが表示されるか、ユーザーが正確にわかっているわけではないため、コンテンツの更新頻度に関する戦略は緩めでかまいません。
ユーザー作成コンテンツライブラリ	厳格ユーザーがデベロッパーのアプリを閉じるたびにコンテンツライブラリを更新することをおすすめします。	この種のコンテンツは、Google サーフェスに表示されるデータと同期させることが重要です。ユーザー作成コンテンツは、パーソナライズされたおすすめコンテンツとは異なり、ユーザーがコンテンツの内容を正確に把握しているためです。公開に大幅な遅れが生じると、ユーザーの混乱を招きます。そのため、コンテンツの更新頻度に関する戦略は厳格にする必要があります。

おすすめコンテンツのタイプ	コンテンツの更新頻度に関する戦略	コンテンツの更新頻度に関するガイドライン
パーソナライズされていないおすすめコンテンツ	緩めおすすめコンテンツは 1 日に 1 回更新することを推奨します。	どのようなおすすめコンテンツが表示されるか、ユーザーが正確にわかっているわけではないため、コンテンツの更新頻度に関する戦略は緩めでかまいません。
おすすめコンテンツとともに表示されるログインカード	厳格ユーザーがデベロッパーのアプリを閉じたら、ログインカードのステータスを更新することをおすすめします。ユーザーのログイン後、`deleteUserManagementCluster()` API を呼び出してカードを削除する必要があります。	ログインステータスは、Google サーフェスと同期させることが重要です。ユーザーがすでにログインしているのに、Google サーフェスにログインカードが表示されると混乱が生じます。そのため、コンテンツの更新頻度に関する戦略は厳格にする必要があります。

連続性クラスタ

連続性クラスタを公開する際は、ユーザーが対象のアプリケーションにログインしているかどうかを考慮する必要があります。

ユーザーがログインしているとき

ユーザー作成の連続性クラスタを公開する必要があります。
- ユーザー作成の連続性クラスタの例は次のとおりです。
  - 前回中断したところから視聴を再開する。
  - 前回中断したところから閲覧を再開する。

連続性のタイプ	コンテンツの更新頻度に関する戦略	コンテンツの更新頻度に関するガイドライン
ユーザー作成の連続性クラスタ	厳格ユーザーがデベロッパーのアプリを閉じるたびにコンテンツライブラリを更新することをおすすめします。	この種のコンテンツは、Google サーフェスに表示されるデータと同期させることが重要です。ユーザー作成コンテンツは、パーソナライズされたおすすめコンテンツとは異なり、ユーザーがコンテンツの内容を正確に把握しているためです。公開に大幅な遅れが生じると、ユーザーの混乱を招きます。そのため、コンテンツの更新頻度に関する戦略は厳格にする必要があります。

連続性のタイプ

コンテンツの更新頻度に関する戦略

コンテンツの更新頻度に関するガイドライン

ユーザー作成の連続性クラスタ

厳格

ユーザーがデベロッパーのアプリを閉じるたびにコンテンツライブラリを更新することをおすすめします。

ユーザーがログインしていないとき

連続性の処理は、主にログインユーザーを対象としています。ただし、アプリがゲストセッションをサポートしている場合は、ログアウトしたユーザーの連続性クラスタを公開することもできます。

ユーザー管理クラスタ

ユーザー管理クラスタの主な目的は、プロバイダのアプリでユーザーに特定のアクションを行うように促すことです。ログインアクションにより、ユーザーをアプリのログインページに誘導し、アプリでコンテンツを公開（または、よりカスタマイズされたコンテンツを提供）できるようにします。

属性	必須 / 任意	説明
アクション URI	必須	アクションへのディープリンク（アプリのログインページへの移動など）
画像	省略可 - 指定しない場合は、タイトルを指定する必要があります	カードに表示される画像解像度 1264×712 でアスペクト比 16×9 の画像
タイトル	省略可 - 指定しない場合は、画像を指定する必要があります	カード上のタイトル
アクションテキスト	任意	行動を促すフレーズ（ログインなど）で表示されるテキスト
字幕	任意	カードの字幕（省略可）

Kotlin


var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

appEngagePublishClient.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java


SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

appEngagePublishClient.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

ユーザーのログイン後、deleteUserManagementCluster() API を呼び出してカードを削除する必要があります。

公開ステータスを更新

社内の業務上の理由でいずれのクラスタも公開されていない場合は、updatePublishStatus API を使用して公開ステータスを更新することを強くおすすめします。公開ステータスの更新が必要な理由は:

ダッシュボードではこのステータスの値に基づいて、統合の健全性などの指標が追加されるため、コンテンツが公開されている（STATUS == PUBLISHED）場合でも公開ステータスを明示する必要があります。
コンテンツは未公開でも統合ステータスが壊れていなければ（STATUS == NOT_PUBLISHED）、アプリの健全性ダッシュボードでアラートがトリガーされるのを回避できます。未公開ステータスを明示することで、プロバイダにとって想定済みの理由からコンテンツが非公開であるという確認がとれます。
デベロッパーは、データの公開状況に関する情報を提供できます。
Google が、ステータスコードを使用してアプリ内で特定のアクション（コンテンツの表示や制覇など）を行うようユーザーに促すことがあります。

利用可能な公開ステータスコードは、次のとおりです。

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

ユーザーがログインしていないためにコンテンツが公開されていない場合は、ログインカードを公開することをおすすめします。なんらかの理由でプロバイダがログインカードを公開できない場合は、ステータスコード NOT_PUBLISHED_REQUIRES_SIGN_IN を使用して updatePublishStatus API を呼び出すことをおすすめします。

Kotlin


client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java


client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

クラスタ公開用の WorkManager

クラスタの公開には WorkManager を使用することをおすすめします。待機的かつ確実な実行が必要になるバックグラウンド処理に推奨されるソリューションだからです。

WorkManager は、バックグラウンド処理を可能な限り早く実行します。
WorkManager は、ユーザーがアプリから離脱した場合も含め、さまざまな条件下でロジックを実行して処理を開始します。

ユーザーがアプリから離脱した場合は、おすすめコンテンツクラスタとともに連続性クラスタを公開するバックグラウンドジョブを開始することをおすすめします。このロジックを処理する場所には、Activity.onStop() が適しています。ユーザーがアプリから離脱したときに呼び出されます。

PeriodicWorkRequest を使用して、24 時間ごとにクラスタを公開する繰り返しジョブのスケジュールを設定することをおすすめします。処理をトリガーするために CANCEL_AND_REENQUEUE ポリシーを使用することで、ユーザーがアプリから離脱するたびに WorkManager から更新されたデータが送信されるようになります。これにより、ユーザーに古いデータが表示されるのを防ぐことができます。

例は次のとおりです。

// Define the PublishClusters Worker requiring input
public class PublishClusters extends Worker {

   public PublishClusters(Context appContext, WorkerParameters workerParams) {
       super(appContext, workerParams);
   }

   @NonNull
   @Override
   public Result doWork() {
       // publish clusters
   }
   ...
}

public static void schedulePublishClusters(Context appContext) {
// Create a PeriodicWorkRequest to schedule a recurring job to update
// clusters at a regular interval
PeriodicWorkRequest publishClustersEntertainmentSpace =
// Define the time for the periodic job
       new PeriodicWorkRequest.Builder(PublishClusters.class, 24, TimeUnit.HOURS)
// Set up a tag for the worker.
// Tags are Unique identifier, which can be used to identify that work
// later in order to cancel the work or observe its progress.
          .addTag("Publish Clusters to Entertainment Space")
          .build();

// Trigger Periodic Job, this will ensure that the periodic job is triggered
// only once since we have defined a uniqueWorkName
WorkManager.getInstance(appContext).enqueueUniquePeriodicWork(
// uniqueWorkName
     "publishClustersEntertainmentSpace",
// If a work with the uniqueWorkName is already running, it will cancel the
// existing running jobs and replace it with the new instance.
// ExistingPeriodicWorkPolicy#CANCEL_AND_REENQUEUE
     ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
// Recurring Work Request
publishClustersEntertainmentSpace);

}

ブロードキャストインテントを処理する

ジョブを介してコンテンツ公開 API の呼び出しを行うだけでなく、コンテンツ公開のリクエストを受信するために BroadcastReceiver を設定する必要もあります。

ただし、ブロードキャストだけに頼らないよう注意する必要があります。ブロードキャストは、特定のシナリオ（主にアプリの再開とデータ同期の強制）でのみトリガーされるためです。ブロードキャストは、Engage のサービスによって、コンテンツが古くなっている可能性があると判定された場合にのみトリガーされます。そうすることで、アプリを長期間開いていなくても、最新のコンテンツエクスペリエンスをユーザーに提供できます。

BroadcastReceiver は、次の 2 つの方法で設定する必要があります。

Context.registerReceiver() を使用して、BroadcastReceiver クラスのインスタンスを動的に登録します。これにより、メモリ内でまだアクティブになっているアプリからの通信が可能になります。
AndroidManifest.xml ファイルで <receiver> タグを使用して、実装を静的に宣言します。これにより、アプリが実行されていないときでもブロードキャストインテントを受信し、コンテンツを公開できるようになります。

Engage SDK Cluster の公開ガイドライン

おすすめコンテンツクラスタ

クラスタのタイトル

クラスタコンテンツ

ユーザーがログインしているとき

ユーザーがログインしていないとき

連続性クラスタ

ユーザーがログインしているとき

ユーザーがログインしていないとき

ユーザー管理クラスタ

Kotlin

Java

公開ステータスを更新

Kotlin

Java

クラスタ公開用の WorkManager

ブロードキャストインテントを処理する

Engage SDK Cluster の公開ガイドライン

おすすめコンテンツ クラスタ

クラスタのタイトル

クラスタ コンテンツ

ユーザーがログインしているとき

ユーザーがログインしていないとき

連続性クラスタ

ユーザーがログインしているとき

ユーザーがログインしていないとき

ユーザー管理クラスタ

ログインカード

Kotlin

Java

公開ステータスを更新

Kotlin

Java

クラスタ公開用の WorkManager

ブロードキャスト インテントを処理する

おすすめコンテンツクラスタ

クラスタコンテンツ

ブロードキャストインテントを処理する