Google は、ユーザーのアプリをカテゴリ別に整理し、没入感のある新しいエクスペリエンスによってアプリ コンテンツの使用や発見をパーソナライズできるオンデバイス サーフェスを構築しています。デベロッパー パートナーは、この全画面エクスペリエンスを活用することで、アプリ外の専用チャネルで良質なリッチ コンテンツをアピールできます。このガイドでは、Engage SDK を使用して健康とフィットネスのコンテンツを統合し、この新しいサーフェス領域にコンテンツを表示する手順を説明します。
統合の詳細
用語
この統合には、おすすめコンテンツ、注目コンテンツ、継続の 3 種類のクラスタがあります。
おすすめコンテンツ クラスタには、個々のデベロッパー パートナーが提供する、パーソナライズされた健康とフィットネスに関するおすすめ情報が表示されます。これらのおすすめは、ユーザーに合わせてパーソナライズすることも、一般的なもの(フィットネスや健康のトレンドなど)にすることもできます。健康やフィットネスに関連する記事や人物を表示するために使用します。
- おすすめコンテンツ クラスタは、
ArticleEntity
、PersonEntity
、またはEventEntity
のリスティングで構成できますが、異なるタイプのエンティティを組み合わせることはできません。
おすすめコンテンツの構成は次のとおりです。
おすすめコンテンツ クラスタ: 同一のデベロッパー パートナーが提供するおすすめコンテンツのグループが表示される UI ビュー。
エンティティ: クラスタ内の単一のアイテムを表すオブジェクト。この統合では、おすすめコンテンツ クラスタを使用して表示されるエンティティがいくつか提供されます。
ArticleEntity: ArticleEntity は、健康とフィットネスに関連するテキストベースのコンテンツのレコメンデーションを表します。記事、ブログ投稿、マーケティング コンテンツ、ニュース スニペットなどに使用できます。
PersonEntity: PersonEntity は人物を表します。おすすめには、コーチや健康やフィットネスに関連する人物などをハイライト表示できます。
EventEntity: EventEntity は、将来発生するイベントを表します。イベントの開始時間は、ユーザーに伝える必要がある重要な情報です。このエンティティは、健康とフィットネスに関連するイベント(献血キャンプ、トレーニング セッション、ジム、ヨガ教室など)を表示するために使用できます。
- おすすめコンテンツ クラスタは、
連続性クラスタでは、複数のデベロッパー パートナーが提供する、ユーザーが最近反応を示したコンテンツが、1 つの UI グループに表示されます。各デベロッパー パートナーは、継続クラスタ内で最大 10 個のエンティティをブロードキャストできます。
連続コンテンツの構造は次のとおりです。
ArticleEntity: ArticleEntity は、健康とフィットネスに関連するテキストベースのコンテンツのおすすめを表します。このエンティティは、閲覧途中のニュース記事や、ユーザーが続きから読みたいコンテンツを表す場合に使用できます。例: 健康やフィットネス関連のトピックに関するニュース スニペット、ブログ投稿スニペット。
EventReservationEntity: EventReservationEntity はイベントの予約を表し、ユーザーが今後のフィットネス イベントや健康イベントの予約を追跡するのに役立ちます。例: トレーニング セッション
注目コンテンツ クラスタでは、複数のデベロッパー パートナーが提供するエンティティのセレクションが 1 つの UI グループに表示されます。1 つの注目クラスタが UI の上部付近に、どのおすすめコンテンツ クラスタよりも優先されて表示されます。各デベロッパー パートナーは、注目コンテンツ クラスタ内で最大 10 個のエンティティをブロードキャストできます。
GenericRecommendedEntity: GenericRecommendedEntity は、デベロッパーの 1 つのトップ コンテンツ用として使用し、ユーザーにとって興味深く関連性のある単一の最も重要なコンテンツを表す必要があるという点で、おすすめアイテムと異なります。
事前作業
最小 API レベル: 19
アプリに com.google.android.engage:engage-core
ライブラリを追加します。
dependencies {
// Make sure you also include that repository in your project's build.gradle file.
implementation 'com.google.android.engage:engage-core:1.5.2'
}
概要
この設計は、バインドされたサービスの実装に基づいています。
クライアントが公開できるデータには、各種クラスタに関する次の上限が適用されます。
クラスタタイプ | クラスタ数の上限 | クラスタ内のエンティティ数の下限 | クラスタ内のエンティティ数の上限 |
---|---|---|---|
おすすめコンテンツ クラスタ | 最大 5 個 | 5 以上 | 最大 25 個(ArticleEntity 、PersonEntity 、または EventEntity ) |
継続クラスタ | 最大 1 個 | 1 以上 | 最大 10 個(ArticleEntity 、または EventReservationEntity ) |
注目コンテンツ クラスタ | 最大 1 個 | 1 以上 | 最大 10 個(GenericFeaturedEntity ) |
ステップ 1: エンティティ データを提供する
この SDK では、各アイテムタイプを表すさまざまなエンティティを定義しています。健康とフィットネス カテゴリでは、次のエンティティがサポートされています。
GenericFeaturedEntity
ArticleEntity
PersonEntity
EventEntity
EventReservationEntity
下記の表に、各タイプで使用可能な属性と、必須か任意かをまとめています。
GenericFeaturedEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 よくある質問をご覧ください |
URI |
ポスター画像 | 必須 | 複数の画像が指定されている場合、1 つの画像のみが表示されます。 推奨されるアスペクト比は 16:9 です 注: バッジを使用する場合は、画像の上部と下部の両方に 24 dps のセーフゾーンを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
タイトル | 任意 | エンティティのタイトル。 | 自由形式のテキスト 推奨テキストサイズは 50 文字 |
説明 | 任意 | エンティティを説明する 1 つの段落のテキスト。 注: 説明または字幕リストのどちらかがユーザーに表示されますが、両方が表示されることはありません。 |
自由形式のテキスト 推奨テキストサイズ: 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各サブタイトルに 1 行のテキスト)。 注: ユーザーには、説明リストまたは字幕リストの両方ではなく、いずれかが表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 | 各バッジは、自由形式のテキスト(最大 15 文字)または小さな画像です。 画像や動画の上に特別な UX 処理を適用する(画像にバッジを重ねて表示するなど)
|
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 15 文字 |
バッジ - 画像 | 任意 | 小さい画像 画像 / 動画のサムネイルにバッジ オーバーレイを表示するなど、特別な UX 処理。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 列挙型のリスト ガイダンスについては、コンテンツ カテゴリのセクションをご覧ください。 |
ArticleEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 よくある質問をご覧ください |
URI |
タイトル | 必須 | エンティティのタイトル。 | 自由形式のテキスト 推奨テキストサイズ: 最大 50 文字 |
ポスター画像 | 任意 | 複数の画像が指定されている場合、画像は 1 つだけ表示されます。 推奨されるアスペクト比は 16:9 です 注: 画像を使用することを強くおすすめします。バッジを使用する場合は、画像の上部と下部の両方に 24 dps のセーフゾーンを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
ソース - タイトル | 任意 | 作成者、組織、または報告者の名前 | 自由形式のテキスト 推奨テキストサイズ: 25 文字未満 |
ソース - 画像 | 任意 | ソースの画像(著者、組織、記者など) | 詳しくは、画像の仕様をご覧ください。 |
説明 | 任意 | エンティティを説明する 1 つの段落のテキスト。 注: 説明または字幕リストのどちらかがユーザーに表示されますが、両方が表示されることはありません。 |
自由形式のテキスト 推奨テキストサイズ: 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各サブタイトルに 1 行のテキスト)。 注: ユーザーには、説明リストまたは字幕リストの両方ではなく、いずれかが表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 | 各バッジは、自由形式のテキスト(最大 15 文字)または小さな画像です。 画像や動画の上に特別な UX 処理を適用する(画像にバッジを重ねて表示するなど)
|
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 15 文字 |
バッジ - 画像 | 任意 | 小さい画像 画像 / 動画のサムネイルにバッジ オーバーレイを表示するなど、特別な UX 処理。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
コンテンツの公開日時 | 任意 | アプリでコンテンツが公開 / 更新されたときのエポック タイムスタンプ(ミリ秒単位)。 | エポック タイムスタンプ(ミリ秒) |
前回のエンゲージメント時間 | 条件付き必須 | ユーザーがこのエンティティを最後に操作したときのエポック タイムスタンプ(ミリ秒単位)。 注: このエンティティが連続性クラスタの一部である場合、このフィールドは必須です。 |
エポック タイムスタンプ(ミリ秒) |
進捗率 | 条件付き必須 | ユーザーがこれまでに視聴したコンテンツの割合。 注: このエンティティが連続性クラスタの一部である場合、このフィールドは必須です。 |
0~100 の整数値。 |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 列挙型のリスト ガイダンスについては、コンテンツ カテゴリのセクションをご覧ください。 |
PersonEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 よくある質問をご覧ください |
URI |
プロフィール - 名前 | 必須 | プロフィール名または ID またはハンドル(「John Doe」、「@TeamPixel」など) | 文字列 推奨テキストサイズ: 最大 50 文字 |
プロフィール - アバター | 必須 |
ユーザーのプロフィール写真またはアバター画像。 注: 1:1 の正方形の画像にする必要があります。 |
詳しくは、画像の仕様をご覧ください。 |
プロフィール - 追加テキスト | 任意 | プロフィール ハンドルのような自由形式のテキスト。 | 自由形式のテキスト 推奨テキストサイズ: 最大 15 文字 |
プロフィール - 追加の画像 | 任意 | 認証済みバッジなどの小さな画像。 | 詳しくは、画像の仕様をご覧ください。 |
ヘッダー画像 | 任意 | 複数の画像が指定されている場合、画像は 1 つだけ表示されます。 推奨されるアスペクト比は 16:9 です 注: 画像を使用することを強くおすすめします。バッジを使用する場合は、画像の上部と下部の両方に 24 dps のセーフゾーンを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
人気度 - 数 | 任意 |
フォロワー数または人気度を表します(例:「370 万人」)。 注: [Count] と [Count Value] の両方を指定した場合は、[Count] が使用されます。 |
文字列 推奨テキストサイズ: カウントとラベルを合わせて最大 20 文字 |
人気度 - カウント値 | 任意 | フォロワー数または人気度。 注: アプリで、さまざまなディスプレイ サイズに合わせて大きな数値を最適化するロジックを処理しない場合は、カウント値を指定します。Count と Count Value の両方が指定されている場合は、Count が使用されます。 |
Long |
人気度 - ラベル | 任意 | 人気ラベルの内容を指定します(例:「高評価」)。 | 文字列 推奨テキストサイズ: 合計数とラベルを合わせて 20 文字以内 |
人気度 - ビジュアル | 任意 |
インタラクションの目的を表します。例: 高評価アイコンや絵文字の画像。 複数の画像を指定できますが、すべてのフォーム ファクタにすべての画像が表示されるとは限りません。 注: 1:1 の正方形の画像である必要があります |
詳しくは、画像の仕様をご覧ください。 |
評価 - 最大値 | 必須 | 段階別評価の最高値。 現在の評価値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 現在の値 | 必須 | 段階別評価の現在の値。 評価の最高値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 件数 | 任意 | エンティティの評価の件数。 注: アプリでユーザーに表示されるカウントの表示方法を制御する場合は、このフィールドを指定します。簡潔な文字列を使用します。 たとえば、数値が 1,000,000 の場合は、1M などの省略形を使用して、小さいディスプレイサイズで数値が切り捨てられないようにすることを検討してください。 |
文字列 |
評価 - 件数 | 任意 | エンティティの評価の件数。 注: 表示の省略形のロジックを自分で処理しない場合は、このフィールドを指定します。[Count] と [Count Value] の両方が存在する場合、[Count] がユーザーに表示されます。 |
Long |
場所 - 国 | 任意 | 社員が居住している国または勤務している国。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 市区町村 | 任意 | 担当者が勤務している都市。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
ロケーション - 住所を表示 | 任意 | ユーザーの所在地または勤務地の住所がユーザーに表示されます。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 番地 | 任意 | 担当者が勤務している場所または担当地域の住所(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
住所 - 都道府県 | 任意 | その人物の所在地またはサービス提供地域(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
所在地 - 郵便番号 | 任意 | 担当者が居住または勤務している地域の郵便番号(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 近隣 | 任意 | 担当者が勤務している地域(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは 20 文字以下 |
バッジ | 任意 |
各バッジは、自由形式のテキスト(最大 15 文字)または小さな画像です。 |
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 15 文字 |
バッジ - 画像 | 任意 | 小さい画像 画像 / 動画のサムネイルにバッジ オーバーレイを表示するなど、特別な UX 処理。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
説明 | 任意 | エンティティを説明する 1 つの段落のテキスト。 注: 説明または字幕リストのどちらかがユーザーに表示されますが、両方が表示されることはありません。 |
自由形式のテキスト 推奨テキストサイズ: 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各サブタイトルに 1 行のテキスト)。 注: ユーザーには、説明リストまたは字幕リストの両方ではなく、いずれかが表示されます。 |
自由形式のテキスト 各字幕の推奨テキストサイズ: 最大 50 文字 |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 対象となる列挙型のリスト
ガイダンスについては、コンテンツ カテゴリのセクションをご覧ください。 |
EventEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 よくある質問をご覧ください |
URI |
タイトル | 必須 | エンティティのタイトル。 | 文字列 推奨テキストサイズ: 最大 50 文字 |
開始時刻 | 必須 |
イベントの開始予定時間のエポック タイムスタンプ。 注: ミリ秒単位で表示されます。 |
エポック タイムスタンプ(ミリ秒) |
イベントモード | 必須 | イベントがオンライン、対面、またはその両方であるかどうかを示すフィールド。 |
列挙型: VIRTUAL、IN_PERSON、HYBRID |
ポスター画像 | 必須 | 複数の画像が指定されている場合、画像は 1 つだけ表示されます。 推奨されるアスペクト比は 16:9 です 注: 画像を使用することを強くおすすめします。バッジを使用する場合は、画像の上部と下部の両方に 24 dps のセーフゾーンを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
場所 - 国 | 条件付き必須 | イベントが開催される国。 注: これは、IN_PERSON または HYBRID のイベントに必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 市区町村 | 条件付き必須 | イベントが開催される都市。 注: これは、IN_PERSON または HYBRID のイベントに必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 表示住所 | 条件付き必須 | ユーザーに表示するイベント会場の住所または会場名。 注: これは、IN_PERSON または HYBRID のイベントに必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 番地 | 任意 | イベントが開催される場所の住所(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
住所 - 都道府県 | 任意 | イベントが開催されている州または都道府県(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
所在地 - 郵便番号 | 任意 | イベントを開催する場所の郵便番号(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 近隣 | 任意 | イベントが開催される地域(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは 20 文字以下 |
終了時間 | 任意 |
イベントが終了すると予想されるエポック タイムスタンプ。 注: ミリ秒単位で表示されます。 |
エポック タイムスタンプ(ミリ秒) |
説明 | 任意 | エンティティを説明する 1 つの段落のテキスト。 注: 説明または字幕リストのどちらかがユーザーに表示されますが、両方が表示されることはありません。 |
自由形式のテキスト 推奨テキストサイズ: 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各サブタイトルに 1 行のテキスト)。 注: ユーザーには、説明リストまたは字幕リストの両方ではなく、いずれかが表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 |
各バッジは、自由形式のテキスト(最大 15 文字)または小さな画像です。 |
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 15 文字 |
バッジ - 画像 | 任意 | 小さい画像 画像 / 動画のサムネイルにバッジ オーバーレイを表示するなど、特別な UX 処理。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
価格 - CurrentPrice | 条件付きで必須 |
イベントのチケット / パスの現在の価格。 取り消し線が引かれた価格を指定する場合は必須です。 |
自由形式のテキスト |
価格 - StrikethroughPrice | 任意 | イベントのチケット / パスの元の価格。 | 自由形式のテキスト |
価格のコールアウト | 任意 | プロモーション、イベント、メンバー割引(利用可能な場合)をアピールするための価格のコールアウト。 | 自由形式のテキスト 推奨テキストサイズは 45 文字未満(長すぎるテキストは省略記号が表示されます) |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 有効な列挙型のリスト
ガイダンスについては、コンテンツ カテゴリのセクションをご覧ください。 |
EventReservationEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 よくある質問をご覧ください |
URI |
タイトル | 必須 | エンティティのタイトル。 | 文字列 推奨テキストサイズ: 最大 50 文字 |
開始時刻 | 必須 |
イベントの開始予定時間のエポック タイムスタンプ。 注: ミリ秒単位で表示されます。 |
エポック タイムスタンプ(ミリ秒) |
イベントモード | 必須 | イベントがオンライン、対面、またはその両方であるかどうかを示すフィールド。 |
列挙型: VIRTUAL、IN_PERSON、HYBRID |
場所 - 国 | 条件付き必須 | イベントが開催される国。 注: これは、IN_PERSON または HYBRID のイベントに必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 市区町村 | 条件付き必須 | イベントが開催される都市。 注: これは、IN_PERSON または HYBRID のイベントに必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 表示住所 | 条件付き必須 | ユーザーに表示するイベント会場の住所または会場名。 注: これは、IN_PERSON または HYBRID のイベントに必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 番地 | 任意 | イベントが開催される場所の住所(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
住所 - 都道府県 | 任意 | イベントが開催されている州または都道府県(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
所在地 - 郵便番号 | 任意 | イベントを開催する場所の郵便番号(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズ: 最大 20 文字 |
場所 - 近隣 | 任意 | イベントが開催されている地域(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは 20 文字以下 |
ポスター画像 | 任意 | 複数の画像が指定されている場合、画像は 1 つだけ表示されます。 推奨されるアスペクト比は 16:9 です 注: 画像を使用することを強くおすすめします。バッジを使用する場合は、画像の上部と下部の両方に 24 dps のセーフゾーンを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
終了時間 | 任意 |
イベントが終了すると予想されるエポック タイムスタンプ。 注: ミリ秒単位で表示されます。 |
エポック タイムスタンプ(ミリ秒) |
サービス プロバイダ - 名前 | 任意 |
サービス プロバイダの名前。 注: サービス プロバイダにはテキストまたは画像が必要です。 |
自由形式のテキスト。例: イベント主催者 / ツアーの名前 |
サービス プロバイダ - 画像 | 任意 |
サービス プロバイダのロゴまたは画像。 注: サービス プロバイダにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
説明 | 任意 | エンティティを説明する 1 つの段落のテキスト。 注: 説明または字幕リストのどちらかがユーザーに表示されますが、両方が表示されることはありません。 |
自由形式のテキスト 推奨テキストサイズ: 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各サブタイトルに 1 行のテキスト)。 注: ユーザーには、説明リストまたは字幕リストの両方ではなく、いずれかが表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 |
各バッジは、自由形式のテキスト(最大 15 文字)または小さな画像です。 |
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズ: 最大 15 文字 |
バッジ - 画像 | 任意 | 小さい画像 画像 / 動画のサムネイルにバッジ オーバーレイを表示するなど、特別な UX 処理。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
予約 ID | 任意 | イベント予約の予約 ID。 | 自由形式のテキスト |
価格 - CurrentPrice | 条件付きで必須 |
イベントのチケット / パスの現在の価格。 取り消し線が引かれた価格を指定する場合は必須です。 |
自由形式のテキスト |
価格 - StrikethroughPrice | 任意 | イベントのチケット / パスの元の価格。 | 自由形式のテキスト |
価格のコールアウト | 任意 | プロモーション、イベント、メンバー割引(利用可能な場合)をアピールするための価格のコールアウト。 | 自由形式のテキスト 推奨テキストサイズは 45 文字未満(長すぎるテキストは省略記号が表示されます) |
評価 - 最高値 | 任意 | 段階別評価の最高値。 現在の評価値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 現在の値 | 任意 | 段階別評価の現在の値。 評価の最高値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 件数 | 任意 | イベントの評価の件数。 注: アプリでユーザーへの表示方法を制御する場合は、このフィールドを指定します。ユーザーに表示できる簡潔な文字列を指定してください。たとえば、数値が 1,000,000 の場合は、1M などの略語を使用して、小さいディスプレイサイズで切り捨てられないようにします。 |
文字列 |
評価 - 件数 | 任意 | イベントの評価の件数。 注: 表示名のロジックをご自身で処理しない場合は、このフィールドを指定します。[カウント] と [カウント値] の両方が存在する場合は、[カウント] がユーザーに表示されます。 |
Long |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 有効な列挙型のリスト
ガイダンスについては、コンテンツ カテゴリのセクションをご覧ください。 |
画像の仕様
画像アセットの要件となる仕様は次の表のとおりです。
アスペクト比 | 最小ピクセル数 | 推奨ピクセル数 |
---|---|---|
スクエア(1×1) 推奨 |
300×300 | 1200×1200 |
横向き(1.91×1) | 600×314 | 1200×628 |
縦向き(4×5) | 480×600 | 960×1200 |
Google が画像にアクセスできるようにするため、画像は公開 CDN でホストする必要があります。
ファイル形式
PNG、JPG、静止 GIF、WebP
最大ファイルサイズ
5120 KB
その他の推奨事項
- 画像のセーフエリア: 重要なコンテンツは、画像の中央 80% の範囲内に配置してください。
- 透明な背景を使用して、ダークモードとライトモードの設定で画像が適切に表示されるようにします。
コンテンツ カテゴリ
コンテンツ カテゴリを使用すると、アプリは複数のカテゴリに属するコンテンツを公開できます。これにより、コンテンツが事前定義されたカテゴリ(以下に示すカテゴリ)にマッピングされます。
TYPE_EDUCATION
TYPE_SPORTS
TYPE_MOVIES_AND_TV_SHOWS
TYPE_BOOKS
TYPE_AUDIOBOOKS
TYPE_MUSIC
TYPE_DIGITAL_GAMES
TYPE_TRAVEL_AND_LOCAL
TYPE_HOME_AND_AUTO
TYPE_BUSINESS
TYPE_NEWS
TYPE_FOOD_AND_DRINK
TYPE_SHOPPING
TYPE_HEALTH_AND_FITENESS
TYPE_MEDICAL
TYPE_PARENTING
TYPE_DATING
Google が画像にアクセスできるようにするため、画像は公開 CDN でホストする必要があります。
コンテンツ カテゴリの使用に関するガイドライン
- ArticleEntity や GenericRecommendedEntity などの一部のエンティティでは、どのコンテンツ カテゴリも使用できます。EventEntity、EventReservationEntity、PersonEntity などの他のエンティティの場合、これらのカテゴリの一部のみが対象となります。リストを入力する前に、エンティティ タイプに使用できるカテゴリのリストを確認してください。
一部のコンテンツ カテゴリについては、汎用エンティティと ContentCategory の組み合わせではなく、特定のエンティティ タイプを使用します。
- TYPE_MOVIES_AND_TV_SHOWS - 汎用エンティティを使用する前に、Watch 統合ガイドでエンティティを確認してください。
- TYPE_BOOKS - 汎用エンティティを使用する前に、EbookEntity を確認してください。
- TYPE_AUDIOBOOKS - 汎用エンティティを使用する前に、AudiobookEntity を確認してください。
- TYPE_SHOPPING - 汎用エンティティを使用する前に、ShoppingEntity を確認してください。
- TYPE_FOOD_AND_DRINK - 汎用エンティティを使用する前に、食品の統合ガイドでエンティティを確認してください。
ContentCategory フィールドは省略可能です。コンテンツが前述のカテゴリに属していない場合は、空白のままにします。
複数のコンテンツ カテゴリを指定する場合は、コンテンツとの関連性の高い順に指定し、最も関連性の高いコンテンツ カテゴリをリストの最初に配置します。
ステップ 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. } });
publishRecommendationClusters
この API は、RecommendationCluster
オブジェクトのリストを公開するために使用されます。
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Top Picks For You") .build() ) .build() )
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Top Picks For You") .build()) .build());
サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。
- デベロッパー パートナーが提供した既存の
RecommendationCluster
データが削除されます。 - リクエストのデータが解析されて、更新されたおすすめコンテンツ クラスタに保存されます。
エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
publishFeaturedCluster
この API は、FeaturedCluster
オブジェクトのリストを公開するために使用されます。
Kotlin
client.publishFeaturedCluster( PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( FeaturedCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Java
client.publishFeaturedCluster( new PublishFeaturedClustersRequest.Builder() .addFeaturedCluster( new FeaturedCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build());
サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。
- デベロッパー パートナーが提供した既存の
FeaturedCluster
データが削除されます。 - リクエストのデータが解析されて、更新された注目コンテンツ クラスタに保存されます。
エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
publishContinuationCluster
この API は、ContinuationCluster
オブジェクトを公開するために使用されます。
Kotlin
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Java
client.publishContinuationCluster( new PublishContinuationClusterRequest.Builder() .setContinuationCluster( new ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build());
サービスがリクエストを受信すると、1 つのトランザクション内で次のアクションが行われます。
- デベロッパー パートナーが提供した既存の
ContinuationCluster
データが削除されます。 - リクエストのデータが解析されて、更新された継続クラスタに保存されます。
エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
publishUserAccountManagementRequest
この API は、ログインカードを公開するために使用されます。ログイン アクションにより、ユーザーをアプリのログインページに誘導し、アプリでコンテンツを公開(または、よりパーソナライズされたコンテンツを提供)できるようにします。
次のメタデータはログインカードの一部です。
属性 | 必須 / 任意 | 説明 |
---|---|---|
アクション 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() 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 は、おすすめコンテンツ クラスタのコンテンツを削除するために使用されます。
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
サービスがリクエストを受信すると、おすすめコンテンツ クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
deleteFeaturedCluster
この API は、注目コンテンツ クラスタのコンテンツを削除するために使用されます。
Kotlin
client.deleteFeaturedCluster()
Java
client.deleteFeaturedCluster();
サービスがリクエストを受信すると、注目コンテンツ クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
deleteContinuationCluster
この API は、継続クラスタのコンテンツを削除するために使用されます。
Kotlin
client.deleteContinuationCluster()
Java
client.deleteContinuationCluster();
サービスがリクエストを受信すると、継続クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
deleteUserManagementCluster
この API は、ユーザー アカウント管理クラスタのコンテンツを削除するために使用されます。
Kotlin
client.deleteUserManagementCluster()
Java
client.deleteUserManagementCluster();
サービスがリクエストを受信すると、ユーザー アカウント管理クラスタから既存のデータが削除されます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
deleteClusters
この API は、特定のクラスタタイプのコンテンツを削除するために使用されます。
Kotlin
client.deleteClusters( DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_CONTINUATION) .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) .build())
Java
client.deleteClusters( new DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_CONTINUATION) .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) .build());
サービスがリクエストを受信すると、指定したクラスタタイプに一致するすべてのクラスタから既存のデータが削除されます。クライアントは、1 つまたは複数のクラスタタイプを渡すこともできます。エラーが発生した場合は、リクエスト全体が拒否され、それまでの状態が維持されます。
エラー処理
公開 API のタスク結果をリッスンすることで、フォローアップの処理を実行し、正常なタスクを復元して再送信できるようにすることを強くおすすめします。
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster(..) .build()) .addOnCompleteListener { task -> if (task.isSuccessful) { // do something } else { val exception = task.exception if (exception is AppEngageException) { @AppEngageErrorCode val errorCode = exception.errorCode if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) { // do something } } } }
Java
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
として返され、その原因はエラーコードとして含まれます。
エラーコード | エラー名 | 注 |
---|---|---|
1 |
SERVICE_NOT_FOUND |
そのデバイスではこのサービスを利用できません。 |
2 |
SERVICE_NOT_AVAILABLE |
サービスをそのデバイスで利用することはできますが、呼び出し時には利用できません(明示的に無効になっている場合など)。 |
3 |
SERVICE_CALL_EXECUTION_FAILURE |
スレッドに関する問題が発生し、タスクを実行できませんでした。その場合は再試行できます。 |
4 |
SERVICE_CALL_PERMISSION_DENIED |
呼び出し元がサービスの呼び出しを行うことができません。 |
5 |
SERVICE_CALL_INVALID_ARGUMENT |
リクエストに無効なデータが含まれています(クラスタ数が許容数を超えているなど)。 |
6 |
SERVICE_CALL_INTERNAL |
サービス側でエラーが発生しています。 |
7 |
SERVICE_CALL_RESOURCE_EXHAUSTED |
サービスの呼び出し頻度が高すぎます。 |
ステップ 3: ブロードキャスト インテントを処理する
ジョブを介してコンテンツ公開 API の呼び出しを行うだけでなく、コンテンツ公開のリクエストを受信するために BroadcastReceiver
を設定する必要もあります。
ブロードキャスト インテントの主目的は、アプリの再有効化とデータ同期の強制です。ブロードキャスト インテントは、頻繁に送信されることを想定した設計にはなっていません。Engage のサービスが、コンテンツが古い可能性がある(1 週間前など)と判断した場合にのみトリガーされます。そうすることで、アプリが長時間実行されていない場合でも、より確実にユーザーに新しいコンテンツを提供できます。
BroadcastReceiver
は、次の 2 つの方法で設定する必要があります。
Context.registerReceiver()
を使用して、BroadcastReceiver
クラスのインスタンスを動的に登録します。これにより、メモリ内でまだアクティブになっているアプリからの通信が可能になります。
Kotlin
class AppEngageBroadcastReceiver : 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 } fun registerBroadcastReceivers(context: Context){ var context = context context = context.applicationContext // Register Recommendation Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION)) // Register Featured Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_FEATURED)) // Register Continuation Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION)) }
Java
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 に関するよくある質問をご覧ください。
お問い合わせ
統合プロセスについてご不明な点がありましたら、engage-developers@google.com までお問い合わせください。
次のステップ
この統合が完了した後のステップは次のとおりです。
- Google によるテストの準備が整った統合済みの APK を添付して、engage-developers@google.com にメールを送信します。
- Google 内部で検証と審査を行い、想定どおりに統合が機能するかどうかを確認します。変更が必要な場合は、Google から必要な詳細事項をご連絡します。
- テストが完了し、変更の必要もない場合は、更新された統合済みの APK を Google Play ストアに公開できるようになったことを Google からお知らせします。
- 更新された APK が Google Play ストアに公開されていることを Google が確認したら、おすすめコンテンツ、注目コンテンツ、連続性の各クラスタが公開され、ユーザーに表示されます。