Engage SDK Listen: サードパーティの技術的統合手順

Google が構築しているオンデバイス サーフェスでは、ユーザーのアプリがカテゴリ別に整理され、パーソナライズされたアプリ コンテンツの使用や発見における没入感のある新しいエクスペリエンスが提供されます。デベロッパー パートナーは、この全画面エクスペリエンスを活用することで、アプリ外の専用チャネルで良質なリッチ コンテンツをアピールできます。

このガイドでは、Engage SDK を使用してオーディオ コンテンツを統合し、この新しいサーフェス領域と既存の Google サーフェスの両方にコンテンツを表示する手順を説明します。

統合の詳細

用語

この統合には、おすすめコンテンツ、継続、注目コンテンツの 3 種類のクラスタがあります。

• おすすめコンテンツ クラスタには、個々のデベロッパー パートナーが提供する書籍コンテンツについて、パーソナライズされたおすすめ情報が表示されます。

  おすすめコンテンツの構成は次のとおりです。

  • おすすめコンテンツ クラスタ: 同一のデベロッパー パートナーが提供するおすすめコンテンツのグループが表示される UI ビュー。

    

    図 1. 単一のパートナーが提供するおすすめコンテンツ クラスタが表示されているエンターテイメント スペースの UI。

  • エンティティ: クラスタ内の単一のアイテムを表すオブジェクト。エンティティには、再生リスト、オーディオブック、ポッドキャストなどがあります。サポートされているエンティティ タイプの一覧については、エンティティ データを提供するセクションをご覧ください。

    

    図 2. 単一のパートナーのおすすめコンテンツ クラスタ内のエンティティが 1 つ表示されているエンターテイメント スペースの UI。

• 継続クラスタでは、複数のデベロッパー パートナーが提供する、ユーザーが最近反応を示したオーディオ コンテンツが、1 つの UI グループに表示されます。各デベロッパー パートナーは、継続クラスタ内で最大 10 個のエンティティをブロードキャストできます。

  

  図 3. 複数のパートナーが提供する未読了のおすすめコンテンツを含む継続クラスタが表示されているエンターテイメント スペースの UI（現時点ではおすすめコンテンツが 1 つのみ表示されます）。

• 注目コンテンツ クラスタでは、複数のデベロッパー パートナーが提供するアイテムのセレクションが 1 つの UI グループに表示されます。1 つの注目コンテンツ クラスタが UI の上部付近に、どのおすすめコンテンツ クラスタよりも優先されて表示されます。各デベロッパー パートナーは、注目コンテンツ クラスタ内で最大 10 個のエンティティをブロードキャストできます。

  

  図 4. 複数のパートナーが提供するおすすめコンテンツを含む注目コンテンツ クラスタが表示されているエンターテインメント スペースの UI（現時点ではおすすめコンテンツが 1 つのみ表示されます）。

事前作業

最小 API レベル: 19

アプリに com.google.android.play:engage ライブラリを追加します。

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.4.0'
}

概要

この設計は、バインドされたサービスの実装に基づいています。

クライアントが公開できるデータには、各種クラスタに関する次の上限が適用されます。

クラスタタイプ	クラスタ数の上限	クラスタ内のエンティティ数の上限
おすすめコンテンツ クラスタ	最大 5 個	最大 50 個
継続クラスタ	最大 1 個	最大 10 個
注目コンテンツ クラスタ	最大 1 個	最大 10 個

ステップ 1: エンティティ データを提供する

この SDK では、各アイテムタイプを表すさまざまなエンティティを定義しています。オーディオ カテゴリでは、次のエンティティがサポートされています。

1. MusicAlbumEntity
2. MusicArtistEntity
3. MusicTrackEntity
4. MusicVideoEntity
5. PlaylistEntity
6. PodcastSeriesEntity
7. PodcastEpisodeEntity
8. LiveRadioStationEntity
9. AudiobookEntity

下記の表に、各タイプで使用可能な属性と、必須か任意かをまとめています。

MusicAlbumEntity

MusicAlbumEntity オブジェクトは音楽アルバムを表します（Taylor Swift の『Midnights』など）。

属性	必須 / 任意	備考
名前	必須	音楽アルバムのタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
情報ページ URI	必須	音楽アルバムの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
アーティスト	必須	音楽アルバム内のアーティストのリスト。
再生 URI	任意	プロバイダ アプリでアルバムの再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
説明	任意	指定する場合は 200 文字以内にする必要があります。
曲数	任意	音楽アルバムの曲の数。
ジャンル	任意	音楽アルバムのジャンルのリスト。
アルバムの形式	任意	アルバム（LP と 2 枚組 LP を含む） EP シングル ミックステープ
音楽レーベル	任意	アルバムに関連付けられている音楽レーベルのリスト。
デバイスにダウンロード	任意	音楽アルバムがデバイスにダウンロードされたかどうかを示すブール値。
露骨な表現	任意	コンテンツが露骨な表現を含むかどうかを示すブール値 露骨な表現を含むアイテム、またはペアレンタル アドバイザリーの警告があるアイテムでは、TRUE に設定する必要があります。露骨な表現を含むアイテムには「E」タグが表示されます。
リリース日	任意	アルバムのリリース日（エポックミリ秒単位）。
所要時間	任意	アルバムの再生時間（ミリ秒単位）。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位
進捗率	任意	継続クラスタ内のアイテムに推奨されます。 0～100 の整数

MusicArtistEntity

MusicArtistEntity オブジェクトは、音楽アーティスト（Adele など）を表します。

属性	必須 / 任意	備考
名前	必須	音楽アーティストの名前。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
情報ページ URI	必須	音楽アーティストの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
再生 URI	任意	プロバイダ アプリでアーティストの曲の再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
説明	任意	指定する場合は 200 文字以内にする必要があります。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位

MusicTrackEntity

MusicTrackEntity オブジェクトは音楽トラックを表します（Coldplay の「Yellow」など）。

属性	必須 / 任意	備考
名前	必須	音楽トラックのタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
再生 URI	必須	プロバイダ アプリで音楽トラックの再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
情報ページ URI	任意	音楽トラックの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
説明	任意	指定する場合は 200 文字以内にする必要があります。
時間	任意	トラックの再生時間（ミリ秒単位）。
アルバム	任意	曲が入っているアルバムの名前。
アーティスト	必須	音楽トラックのアーティストのリスト。
デバイスにダウンロード	任意	音楽トラックがデバイスにダウンロードされたかどうかを示すブール値。
露骨な表現	任意	コンテンツが露骨な表現を含むかどうかを示すブール値 露骨な表現を含むアイテム、またはペアレンタル アドバイザリーの警告があるアイテムでは、TRUE に設定する必要があります。露骨な表現を含むアイテムには「E」タグが表示されます。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位
進捗率	任意	継続クラスタ内のアイテムに推奨されます。 0～100 の整数

MusicVideoEntity

MusicVideoEntity オブジェクトはミュージック ビデオを表します（The Weeknd - Take My Breath（公式ミュージック ビデオ）など）。

属性	必須 / 任意	備考
名前	必須	ミュージック ビデオのタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
再生 URI	必須	プロバイダ アプリでミュージック ビデオの再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
情報ページ URI	任意	ミュージック ビデオの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
所要時間	任意	動画の再生時間（ミリ秒単位）。
視聴回数	任意	動画の視聴回数（自由形式のテキスト）。
アーティスト	任意	ミュージック ビデオのアーティストのリスト。
コンテンツのレーティング	任意	トラックのコンテンツのレーティングのリスト。
説明	任意	指定する場合は 200 文字以内にする必要があります。
デバイスにダウンロード	任意	ミュージック ビデオがデバイスにダウンロードされたかどうかを示すブール値。
露骨な表現	任意	コンテンツが露骨な表現を含むかどうかを示すブール値 露骨な表現を含むアイテム、またはペアレンタル アドバイザリーの警告があるアイテムでは、TRUE に設定する必要があります。露骨な表現を含むアイテムには「E」タグが表示されます。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位
進捗率	任意	継続クラスタ内のアイテムに推奨されます。 0～100 の整数

PlaylistEntity

PlaylistEntity オブジェクトは音楽の再生リストを表します（米国の再生リストのトップ 10 など）。

属性	必須 / 任意	備考
名前	必須	再生リストのタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
再生 URI	必須	プロバイダ アプリで音楽プレイリストの再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
情報ページ URI	任意	音楽プレイリストの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
所要時間	任意	再生リストの再生時間（ミリ秒単位）。
曲数	任意	音楽の再生リスト内の曲数。
説明	任意	指定する場合は 200 文字以内にする必要があります。
デバイスにダウンロード	任意	再生リストがデバイスにダウンロードされたかどうかを示すブール値。
露骨な表現	任意	コンテンツが露骨な表現を含むかどうかを示すブール値 露骨な表現を含むアイテム、またはペアレンタル アドバイザリーの警告があるアイテムでは、TRUE に設定する必要があります。露骨な表現を含むアイテムには「E」タグが表示されます。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位
進捗率	任意	継続クラスタ内のアイテムに推奨されます。 0～100 の整数

PodcastSeriesEntity

PodcastSeriesEntity オブジェクトは、ポッドキャスト シリーズを表します（「This American Life」など）。

属性	必須 / 任意	備考
名前	必須	ポッドキャスト シリーズのタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
情報ページ URI	必須	ポッドキャスト シリーズの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
再生 URI	任意	プロバイダ アプリでポッドキャスト シリーズの再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
エピソード数	任意	ポッドキャスト シリーズのエピソード数。
制作会社名	任意	ポッドキャスト シリーズの制作会社名。
ホスト	任意	ポッドキャスト シリーズのホストのリスト。
ジャンル	任意	ポッドキャスト シリーズのジャンルのリスト。
デバイスにダウンロード	任意	ポッドキャストがデバイスにダウンロードされたかどうかを示すブール値。
説明	任意	指定する場合は 200 文字以内にする必要があります。
露骨な表現	任意	コンテンツが露骨な表現を含むかどうかを示すブール値 露骨な表現を含むアイテム、またはペアレンタル アドバイザリーの警告があるアイテムでは、TRUE に設定する必要があります。露骨な表現を含むアイテムには「E」タグが表示されます。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位

PodcastEpisodeEntity

PodcastEpisodeEntity オブジェクトは、ポッドキャスト シリーズを表します（Spark Bird のエピソード 754「This American Life」など）。

属性	必須 / 任意	備考
名前	必須	ポッドキャスト エピソードのタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
再生 URI	必須	プロバイダ アプリでポッドキャスト エピソードの再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
制作会社のシリーズのタイトル	必須	エピソードが属するポッドキャスト シリーズの名前。
時間	必須	ポッドキャスト エピソードの再生時間（ミリ秒単位）。
公開日	必須	ポッドキャストの公開日（エポックミリ秒単位）
情報ページ URI	任意	ポッドキャスト エピソードの詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
制作会社名	任意	ポッドキャスト シリーズの制作会社名。
エピソードの索引	任意	シリーズ内のエピソードの索引（最初のエピソードの索引は 1）。
ホスト	任意	ポッドキャスト エピソードのホストのリスト。
ジャンル	任意	ポッドキャスト エピソードのジャンルのリスト。
デバイスにダウンロード	任意	ポッドキャスト エピソードがデバイスにダウンロードされたかどうかを示すブール値。
説明	任意	指定する場合は 200 文字以内にする必要があります。
動画ポッドキャスト	任意	ポッドキャスト エピソードに動画コンテンツがあるかどうかを示すブール値
露骨な表現	任意	コンテンツが露骨な表現を含むかどうかを示すブール値 露骨な表現を含むアイテム、またはペアレンタル アドバイザリーの警告があるアイテムでは、TRUE に設定する必要があります。露骨な表現を含むアイテムには「E」タグが表示されます。
次の再生の種類	任意	継続クラスタ内のアイテムに推奨 TYPE_CONTINUE - 聞き終えていないオーディオ アイテムを再開します。 TYPE_NEXT - シリーズの新しいアイテムに進みます。 TYPE_NEW - 新しいリリースです。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位
進捗率	任意	継続クラスタ内のアイテムに推奨されます。 0～100 の整数

LiveRadioStationEntity

LiveRadioStationEntity オブジェクトは、ライブのラジオ放送局を表します（98.1 The Breeze など）。

属性	必須 / 任意	備考
名前	必須	ライブのラジオ放送局のタイトル。
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
再生 URI	必須	プロバイダ アプリでラジオ局の再生を開始するディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
情報ページ URI	任意	ラジオ局の詳細に関するプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
周波数	任意	ラジオ放送局の周波数（「98.1 FM」など）。
番組のタイトル	任意	ラジオ放送局で現放送中の番組。
ホスト	任意	ラジオ放送局のホストのリスト。
説明	任意	指定する場合は 200 文字以内にする必要があります。
前回のエンゲージメント時間	任意	継続クラスタ内のアイテムに推奨されます。ランキングに使用される場合があります。 エポックミリ秒単位

AudiobookEntity

AudiobookEntity オブジェクトはオーディオブックを表します（Michelle Obama のオーディオブック『Becoming』など）。

属性	必須 / 任意	備考
名前	必須
ポスター画像	必須	画像を少なくとも 1 つ指定する必要があります。詳しくは、画像の仕様をご覧ください。
作者	必須	作者名を少なくとも 1 つ指定する必要があります。
ナレーター	必須	少なくとも 1 人のナレーターの名前を指定する必要があります。
アクション リンク URI	必須	オーディオブックのプロバイダ アプリへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。よくある質問をご覧ください
公開日	任意	エポックミリ秒単位（指定する場合）。
説明	任意	指定する場合は 200 文字以内にする必要があります。
料金	任意	自由形式のテキスト
所要時間	任意	指定する場合は正の値にする必要があります。
ジャンル	任意	書籍に関連付けられているジャンルのリスト。
シリーズ名	任意	オーディオブックが属するシリーズの名前（ハリー・ポッターなど）。
シリーズ ユニットの索引	任意	シリーズもののオーディオブックの索引（1 はシリーズの最初のオーディオブック）。たとえば、『ハリー・ポッターとアズカバンの囚人』が同シリーズの 3 番目の書籍の場合は、3 に設定します。
書籍の継続の種類	任意	TYPE_CONTINUE - 読み終えていない書籍を再開します。 TYPE_NEXT - シリーズの新しいアイテムに進みます。 TYPE_NEW - 新しいリリースです。
前回のエンゲージメント時間	条件付きで必須	アイテムが継続クラスタ内にある場合は指定する必要があります。 エポックミリ秒単位。
進捗率	条件付きで必須	アイテムが継続クラスタ内にある場合は指定する必要があります。 *新規に*取得したオーディオブックは、「続けて読む」クラスタの一部にできます。 0 より大きく 100 より小さい値を指定してください。
DisplayTimeWindow - コンテンツがサーフェスに表示される時間帯を設定します
開始タイムスタンプ	任意	このエポック タイムスタンプ以降にコンテンツがサーフェスに表示されます。 設定されていない場合、コンテンツはサーフェスに表示されます。 エポックミリ秒単位。
終了タイムスタンプ	任意	このエポック タイムスタンプ以降は、コンテンツがサーフェスに表示されなくなります。 設定されていない場合、コンテンツはサーフェスに表示されます。 エポックミリ秒単位。

画像の仕様

画像アセットの要件となる仕様は次のとおりです。

アスペクト比	必須 / 任意	最小ピクセル数	推奨ピクセル数
スクエア（1×1）	必須	300×300	1200×1200
横向き（1.91×1）	任意	600×314	1200×628
縦向き（4×5）	任意	480×600	960×1200

ファイル形式

PNG、JPG、静止 GIF、WebP

最大ファイルサイズ

5120 KB

その他の推奨事項

• 画像のセーフエリア: 重要なコンテンツは、画像の中央 80% の範囲内に配置してください。

例

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();

AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

ステップ 2: クラスタデータを提供する

WorkManager などを使用して、コンテンツ公開ジョブをバックグラウンドで実行し、定期的に、またはイベントごとに（ユーザーがアプリを開いたときや、カートに商品を追加したときなど）スケジュールを設定することをおすすめします。

AppEngagePublishClient はクラスタの公開を行います。クライアントでは、次の API を使用できます。

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

この API は、サービスを統合に使用できるかどうか、コンテンツをデバイスに表示できるかどうかを確認するために使用されます。

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content
          // publish calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

注: 定期的なジョブをスケジュールしておいて、サービスが利用可能になるかどうかをそのたびに確認することを強くおすすめします。Android バージョンのアップグレード、アプリのアップグレードやインストール、アンインストールによって、サービスの利用可否が変わる可能性があります。一定の間隔で定期的にジョブを確認することで、サービスが利用可能になったときにデータを公開できます。

publishRecommendationClusters

この API は、RecommendationCluster オブジェクトのリストを公開するために使用されます。

重要: 公開 API は既存のコンテンツを置き換える upsert API です。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。

Kotlin

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

• デベロッパー パートナーが提供した既存の RecommendationCluster データが削除されます。
• リクエストのデータが解析されて、更新されたおすすめコンテンツ クラスタに保存されます。

エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

publishFeaturedCluster

この API は、FeaturedCluster オブジェクトのリストを公開するために使用されます。

重要: 公開 API は既存のコンテンツを置き換える upsert API です。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。

Kotlin

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

• デベロッパー パートナーが提供した既存の FeaturedCluster データが削除されます。
• リクエストのデータが解析されて、更新された注目コンテンツ クラスタに保存されます。

エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

publishContinuationCluster

この API は、ContinuationCluster オブジェクトを公開するために使用されます。

重要: publish API は既存のコンテンツを置き換える upsert API です。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。

Kotlin

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

Java

client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

• デベロッパー パートナーが提供した既存の ContinuationCluster データが削除されます。
• リクエストのデータが解析されて、更新された継続クラスタに保存されます。

エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

publishUserAccountManagementRequest

この API は、ログインカードを公開するために使用されます。ログイン アクションにより、ユーザーをアプリのログインページに誘導し、アプリでコンテンツを公開（または、よりパーソナライズされたコンテンツを提供）できるようにします。

次のメタデータはログインカードの一部です。

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

重要: publish API は既存のコンテンツを置き換える upsert API です。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。

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

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

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

サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。

• デベロッパー パートナーが提供した既存の UserAccountManagementCluster データが削除されます。
• リクエストのデータが解析されて、更新済みのユーザー アカウント管理クラスタに保存されます。

エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

updatePublishStatus

社内の業務上の理由でいずれのクラスタも公開されていない場合は、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

ユーザーがログインしていないためにコンテンツが公開されていない場合、Google は、ログインカードを公開することをおすすめします。なんらかの理由でプロバイダがログインカードを公開できない場合は、ステータス コード 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());

deleteRecommendationClusters

この API は、おすすめコンテンツ クラスタのコンテンツを削除するために使用されます。

重要: delete API は、公開するコンテンツがない場合にのみ呼び出します。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。delete API を使用する前に、engage-developers@ までご連絡ください。

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

サービスがリクエストを受信すると、おすすめコンテンツ クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

注: この API は、バージョン 1.1.0 以降で使用できます。

deleteFeaturedCluster

この API は、注目コンテンツ クラスタのコンテンツを削除するために使用されます。

重要: delete API は、公開するコンテンツがない場合にのみ呼び出します。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。delete API を使用する前に、engage-developers@ までご連絡ください。

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

サービスがリクエストを受信すると、注目コンテンツ クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

注: この API は、バージョン 1.1.0 以降で使用できます。

deleteContinuationCluster

この API は、継続クラスタのコンテンツを削除するために使用されます。

重要: delete API は、公開するコンテンツがない場合にのみ呼び出します。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。delete API を使用する前に、engage-developers@ までご連絡ください。

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

サービスがリクエストを受信すると、継続クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

注: この API は、バージョン 1.1.0 以降で使用できます。

deleteUserManagementCluster

この API は、ユーザー アカウント管理クラスタのコンテンツを削除するために使用されます。

重要: delete API は、公開するコンテンツがない場合にのみ呼び出します。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。delete API を使用する前に、engage-developers@ までご連絡ください。

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

サービスがリクエストを受信すると、ユーザー アカウント管理クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

注: この API は、バージョン 1.1.0 以降で使用できます。

deleteClusters

この API は、特定のクラスタタイプのコンテンツを削除するために使用されます。

重要: delete API は、公開するコンテンツがない場合にのみ呼び出します。publish API だけでコンテンツの削除と挿入を行うので、コンテンツを置き換えるために delete API に続けて publish API を呼び出すことはしないでください。delete API を使用する前に、engage-developers@ までご連絡ください。

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      ...
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                ...
                .build());

サービスがリクエストを受信すると、指定したクラスタタイプに一致するすべてのクラスタから既存のデータが削除されます。クライアントは、1 つまたは複数のクラスタタイプを渡すこともできます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。

エラー処理

publish API のタスク結果をリッスンすることで、フォローアップ処理を行い、正常なタスクを復元して再送信できるようにすることを強くおすすめします。

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

このエラーは AppEngageException として返されます。原因はエラーコードとして含まれます。

エラーコード	注
SERVICE_NOT_FOUND	そのデバイスではこのサービスを利用できません。
SERVICE_NOT_AVAILABLE	サービスをそのデバイスで利用することはできますが、呼び出し時には利用できません（明示的に無効になっている場合など）。
SERVICE_CALL_EXECUTION_FAILURE	スレッドに関する問題が発生し、タスクを実行できませんでした。その場合は再試行できます。
SERVICE_CALL_PERMISSION_DENIED	呼び出し元がサービスの呼び出しを行うことができません。
SERVICE_CALL_INVALID_ARGUMENT	リクエストに無効なデータが含まれています（クラスタ数が許容数を超えているなど）。
SERVICE_CALL_INTERNAL	サービス側でエラーが発生しています。
SERVICE_CALL_RESOURCE_EXHAUSTED	サービスの呼び出し頻度が高すぎます。

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

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

ブロードキャスト インテントの主目的は、アプリの再有効化とデータ同期の強制です。ブロードキャスト インテントは、頻繁に送信されることを想定した設計にはなっていません。Engage のサービスが、コンテンツが古い可能性がある（1 週間前など）と判断した場合にのみトリガーされます。そうすることで、アプリが長時間実行されていない場合でも、より確実にユーザーに新しいコンテンツを提供できます。

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

• Context.registerReceiver() を使用して、BroadcastReceiver クラスのインスタンスを動的に登録します。これにより、メモリ内でまだアクティブになっているアプリからの通信が可能になります。

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));


// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

• AndroidManifest.xml ファイルで <receiver> タグを使用して、実装を静的に宣言します。これにより、アプリが実行されていないときでもブロードキャスト インテントを受信し、コンテンツを公開できるようになります。

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

サービスによって次のインテントが送信されます。

• com.google.android.engage.action.PUBLISH_RECOMMENDATION このインテントを受信したときに、publishRecommendationClusters の呼び出しを開始することをおすすめします。
• com.google.android.engage.action.PUBLISH_FEATURED このインテントを受信したときに、publishFeaturedCluster の呼び出しを開始することをおすすめします。
• com.google.android.engage.action.PUBLISH_CONTINUATION このインテントを受信したときに、publishContinuationCluster の呼び出しを開始することをおすすめします。

統合ワークフロー

統合完了後に検証を行う手順のガイドについては、デベロッパー向けの Engage 統合ワークフローをご覧ください。

よくある質問

よくある質問については、Engage SDK に関するよくある質問をご覧ください。

お問い合わせ

統合プロセスについてご不明な点がありましたら、[e-mail] までお問い合わせください。担当チームができる限り速やかに返信いたします。

次のステップ

この統合が完了した後のステップは次のとおりです。

• Google によるテストの準備が整った統合済みの APK を添付して、[e-mail] にメールを送信します。
• Google が社内で検証とレビューを行い、統合が適切に機能するか確認します。変更が必要な場合は、Google から詳細をご連絡いたします。
• テストが完了し、変更の必要もない場合は、更新された統合済みの APK を Play ストアに公開できるようになったことを Google からお知らせします。
• 更新された APK が Play ストアに公開されていることを Google が確認したら、おすすめコンテンツ、注目コンテンツ、継続の各クラスタが公開され、ユーザーに表示されます。