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

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

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

クラスタのタイトル

ユーザーがクラスタの内容をよく理解できるような、一意かつ関連性の高いクラスタ タイトルを付けることをおすすめします。

内容に基づいた優れたクラスタ タイトルの例を以下に示します。

• ショッピング関連のクラスタ
  • タイムセール
  • 今週のマストバイ
  • Google Pixel Buds 購入関連
  • レディース レインブーツ
• 健康に関する本のクラスタ
  • 健康、心と身体
  • 健康関連のおすすめ
  • フィットネスのベストセラー

クラスタ コンテンツ

おすすめコンテンツ クラスタを公開する際は、ユーザーがデベロッパーのアプリにログインしているかどうかを考慮する必要があります。

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

ユーザーがデベロッパーのアプリにログインしている場合は、パーソナライズされたクラスタ、またはユーザー作成コンテンツ クラスタを公開することをおすすめします。パーソナライズされたコンテンツやユーザー作成コンテンツは、ユーザーのニーズに合ったものになるため、Google サーフェスからそのデベロッパーのアプリにアクセスする可能性が高くなります。

• パーソナライズされたおすすめコンテンツを公開できます。
  • パーソナライズされたおすすめコンテンツの例は次のとおりです。
    • ユーザーの再生履歴に基づいたおすすめコンテンツ。
    • ユーザーの閲覧履歴に含まれる書籍に類似した書籍。
    • ユーザーのお気に入りのアーティストの曲。
• ユーザー作成コンテンツ ライブラリを公開できます。
  • ユーザー作成コンテンツ ライブラリの例は以下のとおりです。
    • デベロッパーのアプリにあるユーザーのウォッチリスト。
    • デベロッパーのアプリでユーザーが自分で作成したお気に入りアーティストのリスト。

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

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

ユーザーがデベロッパーのアプリにログインしていない場合でも、Google サーフェスからそのアプリの利用をユーザーに促すために、クラスタを公開することをおすすめします。

• パーソナライズされていないおすすめコンテンツ クラスタを公開するとよいでしょう。
  • 以下は、パーソナライズされていないおすすめコンテンツの例です。
    • 今年読まれた書籍トップ 10。
    • 新作映画。
    • 注目のポッドキャスト。
• ログインカードを公開します。
  • ユーザーにデベロッパーのアプリへのログインを促すために、パーソナライズされていないおすすめコンテンツ クラスタとともにログインカードも公開できます。ログインカードを公開する方法について詳しくは、以下のセクションをご覧ください。

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

連続性クラスタ

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

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

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

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

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

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

ユーザー管理クラスタ

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

ログインカード

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

KotlinJava

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());

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 を呼び出すことをおすすめします。

KotlinJava

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

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> タグを使用して、実装を静的に宣言します。これにより、アプリが実行されていないときでもブロードキャスト インテントを受信し、コンテンツを公開できるようになります。