Google は、ユーザーのアプリをカテゴリ別に整理し、没入感のある新しいエクスペリエンスによってアプリ コンテンツの使用や発見をパーソナライズできるオンデバイス サーフェスを構築しています。この全画面エクスペリエンスにより、デベロッパー パートナーは、アプリ外の専用チャネルで優れたリッチ コンテンツを紹介できます。このガイドには、Engage SDK を使用して新しいサーフェス領域にコンテンツを表示するデベロッパー パートナーが、デートコンテンツを統合するための手順が記載されています。
統合の詳細
用語
この統合には、おすすめコンテンツ、注目コンテンツ、連続性の 3 種類のクラスタがあります。
おすすめコンテンツ クラスタには、特定のデベロッパー パートナーが提供するパーソナライズされたおすすめのデート情報が表示されます。これらのおすすめは、ユーザーに合わせてカスタマイズできます。
- おすすめコンテンツ クラスタは、
ArticleEntity
、PersonEntity
、EventEntity
で構成できますが、異なるエンティティ タイプを組み合わせることはできません。
おすすめコンテンツの構成は次のとおりです。
おすすめコンテンツ クラスタ: 同一のデベロッパー パートナーが提供するおすすめコンテンツのグループが表示される UI ビュー。
エンティティ: クラスタ内の単一のアイテムを表すオブジェクト。この統合では、おすすめコンテンツ クラスタを使用して表示されるエンティティがいくつか提供されます。
ArticleEntity: ArticleEntity は、出会い系に関連するテキストベースのコンテンツのレコメンデーションを表します。ArticleEntity アイテムを使用すると、デベロッパーはより多くのメタデータを含むさまざまなテキスト コンテンツと画像コンテンツを提供し、ユーザーに情報を明確にできます。
PersonEntity: PersonEntity は、個人を表します。デートの潜在的な人物に焦点を合わせることなどがおすすめです。
EventEntity: EventEntity は、今後発生するイベントを表します。イベントの開始時間は、ユーザーに伝達する必要がある重要な情報です。
- おすすめコンテンツ クラスタは、
継続クラスタでは、複数のデベロッパー パートナーが提供するユーザーが最近エンゲージしたコンテンツが 1 つの UI グループに表示されます。各デベロッパー パートナーは、連続性クラスタ内で最大 10 個のエンティティをブロードキャストできます。
連続性コンテンツの構造は次のとおりです。
ArticleEntity: ArticleEntity は、出会い系に関連するテキストベースのコンテンツのレコメンデーションを表します。このエンティティは、ユーザーが閲覧途中のニュース記事など、続きのコンテンツを表すために使用できます。
EventReservationEntity: EventReservationEntity はイベントの予約を表します。これは、ユーザーが今後または開催中のデートやイベントの予約を追跡するのに役立ちます。
注目コンテンツ クラスタは、多くのデベロッパー パートナーが提供する注目の
GenericFeaturedEntity
のセレクションを 1 つの UI グループに表示する UI ビューです。1 つの注目コンテンツ クラスタが UI の上部付近に、どのおすすめコンテンツ クラスタよりも優先されて表示されます。各デベロッパー パートナーは、サポートされているタイプのエンティティを注目コンテンツ クラスタ内に 1 つずつブロードキャストできます。注目コンテンツ クラスタには、複数のアプリ デベロッパーが提供する多数のエンティティ(場合によっては異なるタイプ)をブロードキャストできます。GenericFeatureEntity: GenericFEATUREEntity は、おすすめアイテムとは異なり、デベロッパーからの上位 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.1'
}
概要
この設計は、バインドされたサービスの実装に基づいています。
クライアントが公開できるデータには、各種クラスタに関する次の上限が適用されます。
クラスタタイプ | クラスタ数の上限 | クラスタ内のエンティティ数の下限 | クラスタ内のエンティティ数の上限 |
---|---|---|---|
おすすめコンテンツ クラスタ | 最大 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 dp の安全スペースを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
タイトル | 任意 | エンティティのタイトル。 | 自由形式のテキスト 推奨テキストサイズは 50 文字 |
説明 | 任意 | エンティティを説明する 1 段落のテキスト。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 推奨テキストサイズは 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各字幕には 1 行のテキスト)。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 | 各バッジには、自由形式のテキスト(最大 15 文字)または小さい画像を使用できます。 画像や動画の上に特別な UX を配置する(画像にバッジをオーバーレイするなど)
|
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズは 15 文字以内 |
バッジ - 画像 | 任意 | 小さい画像 特別な UX 処理(画像や動画のサムネイルにバッジをオーバーレイするなど)。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 列挙型のリスト 詳しくは、コンテンツ カテゴリのセクションをご覧ください。 |
ArticleEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 こちらのよくある質問をご覧ください |
URI |
タイトル | 必須 | エンティティのタイトル。 | 自由形式のテキスト 推奨テキストサイズ: 最大 50 文字 |
ポスター画像 | 任意 | 複数の画像が指定されている場合、画像は 1 つだけ表示されます。 推奨されるアスペクト比は 16:9 です 注: 画像を指定することを強くおすすめします。バッジを使用する場合は、画像の上部と下部の両方に 24 dp のセーフスペースを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
ソース - タイトル | 任意 | 作成者、組織、または報告者の名前 | 自由形式のテキスト 推奨テキストサイズは 25 文字未満 |
ソース - 画像 | 任意 | 作成者、組織、報告者などの情報源の画像 | 詳しくは、画像の仕様をご覧ください。 |
説明 | 任意 | エンティティを説明する 1 段落のテキスト。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 推奨テキストサイズは 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各字幕には 1 行のテキスト)。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 | 各バッジには、自由形式のテキスト(最大 15 文字)または小さい画像を使用できます。 画像や動画の上に特別な UX を配置する(画像にバッジをオーバーレイするなど)
|
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズは 15 文字以内 |
バッジ - 画像 | 任意 | 小さい画像 特別な UX 処理(画像や動画のサムネイルにバッジをオーバーレイするなど)。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
コンテンツの公開日時 | 任意 | これは、アプリ内でコンテンツが公開または更新されたときのエポック タイムスタンプ(ミリ秒単位)です。 | エポック タイムスタンプ(ミリ秒) |
前回のエンゲージメント時間 | 条件付き必須 | ユーザーが前回このエンティティを操作したときのエポック タイムスタンプ(ミリ秒単位)。 注: このエンティティが継続クラスタの一部である場合、このフィールドは必須です。 |
エポック タイムスタンプ(ミリ秒) |
進捗率 | 条件付き必須 | 現時点でユーザーがコンテンツ全体に対して消費した割合。 注: このエンティティが継続クラスタの一部である場合、このフィールドは必須です。 |
0 ~ 100 の int 値。 |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 列挙型のリスト 詳しくは、コンテンツ カテゴリのセクションをご覧ください。 |
PersonEntity
属性 | 必須 / 任意 | 説明 | 形式 |
---|---|---|---|
アクション URI | 必須 |
プロバイダ アプリ内のエンティティへのディープリンク。 注: アトリビューションにはディープリンクを使用できます。 こちらのよくある質問をご覧ください |
URI |
プロフィール - 名前 | 必須 | プロフィール名または ID またはハンドル(「John Doe」、「@TeamPixel」など)。 | 文字列 推奨テキストサイズ: 最大 50 文字 |
プロフィール - アバター | 必須 |
ユーザーのプロフィール写真またはアバター画像。 注: 1:1 の正方形の画像を使用してください。 |
詳しくは、画像の仕様をご覧ください。 |
プロフィール - 追加テキスト | 任意 | プロフィール ハンドルなどの自由形式のテキスト。 | 自由形式のテキスト 推奨テキストサイズは 15 文字以内 |
プロフィール - 追加の画像 | 任意 | 認証バッジなどの小さい画像。 | 詳しくは、画像の仕様をご覧ください。 |
ヘッダー画像 | 任意 | 複数の画像が指定されている場合、画像は 1 つだけ表示されます。 推奨されるアスペクト比は 16:9 です 注: 画像を指定することを強くおすすめします。バッジを使用する場合は、画像の上部と下部の両方に 24 dp のセーフスペースを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
人気度 - 数 | 任意 |
ヘッダー画像を表します。プロフィール画像とは異なるものにする必要があります。 これは、作品を気に入っている人物を際立たせる追加の画像がある場合に使用できます。 注: 16:9 の画像を使用してください。バッジを提供する場合は、画像の上下に 24 dp のセーフスペースを確保してください。 |
文字列 推奨テキストサイズ: カウントとラベルを合わせて最大 20 文字 |
人気度 - カウント値 | 任意 | フォロワー数または人気度の値。 注: さまざまなディスプレイ サイズに合わせて多数の数値を最適化するロジックをアプリで処理しない場合は、カウント値を指定します。「カウント」と「カウント値」の両方を指定すると、カウントが使用されます。 |
詳細 |
人気度 - ラベル | 任意 | 人気度ラベルを示します(「高評価」など)。 | 文字列 推奨テキストサイズ: カウントとラベルを合わせて最大 20 文字 |
人気度 - ビジュアル | 任意 |
インタラクションの目的を表します。例: 高評価アイコンや絵文字の画像。 複数の画像を指定できますが、そのすべてがすべてのフォーム ファクタに表示されるとは限りません。 注: 1:1 の正方形の画像を使用してください |
詳しくは、画像の仕様をご覧ください。 |
評価 - 最高値 | 必須 | 段階別評価の最高値。 現在の評価値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 現在の値 | 必須 | 段階別評価の現在の値。 評価の最高値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 件数 | 任意 | エンティティの評価のカウント。 注: ユーザーへの表示方法をアプリで制御する場合は、このフィールドを指定します。ユーザーに表示される簡潔な文字列を指定してください。たとえば、カウントが 1,000,000 の場合は、1M などの略語を使用して、小さいディスプレイ サイズで切り捨てられないようにすることを検討してください。 |
文字列 |
評価 - カウント値 | 任意 | エンティティの評価のカウント。 注: 表示省略ロジックを独自に処理しない場合は、このフィールドを指定します。「カウント」と「カウント値」の両方が存在する場合は、カウントを使用してユーザーに表示します。 |
詳細 |
場所 - 国 | 任意 | ユーザーが拠点を置く、またはサービスを提供している国。 | 自由形式のテキスト 推奨テキストサイズは最大 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 dp のセーフスペースを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
場所 - 国 | 条件付き必須 | イベントが行われる国。 注: これは、IN_PERSON または HYBRID のイベントの場合は必須です。 |
自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
場所 - 市区町村 | 条件付き必須 | イベントが行われる都市。 注: これは、IN_PERSON または HYBRID のイベントの場合は必須です。 |
自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
場所 - 表示住所 | 条件付き必須 | ユーザーに表示する、イベント開催地の住所または会場名。 注: これは、IN_PERSON または HYBRID のイベントの場合は必須です。 |
自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
場所 - 住所 | 任意 | イベントがホストされている場所の番地(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
場所 - 都道府県 | 任意 | イベントがホストされている都道府県(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
場所 - 郵便番号 | 任意 | イベントがホストされている場所の郵便番号(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
地域 - 周辺地域 | 任意 | イベントが開催される近隣地域(該当する場合)。 | 自由形式のテキスト 推奨テキストサイズは最大 20 文字 |
終了時間 | 任意 |
イベントの終了が予想されるエポック タイムスタンプ。 注: これはミリ秒単位で表されます。 |
エポック タイムスタンプ(ミリ秒) |
説明 | 任意 | エンティティを説明する 1 段落のテキスト。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 推奨テキストサイズは 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各字幕には 1 行のテキスト)。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 |
各バッジには、自由形式のテキスト(最大 15 文字)または小さい画像を使用できます。 |
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズは 15 文字以内 |
バッジ - 画像 | 任意 | 小さい画像 特別な UX 処理(画像や動画のサムネイルにバッジをオーバーレイするなど)。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
価格 - 現在の価格 | 条件付きで必須 |
イベントのチケット/パスの現在の料金。 取り消し線を引いた価格を指定する場合は必須です。 |
自由形式のテキスト |
価格 - 取り消し線 | 任意 | イベントのチケット/パスの元の価格。 | 自由形式のテキスト |
価格のコールアウト | 任意 | プロモーション、イベント、メンバー割引をアピールするための価格コールアウト(利用可能な場合)。 | 自由形式のテキスト 推奨テキストサイズは 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 dp のセーフスペースを確保してください。 |
詳しくは、画像の仕様をご覧ください。 |
終了時間 | 任意 |
イベントの終了が予想されるエポック タイムスタンプ。 注: これはミリ秒単位で表されます。 |
エポック タイムスタンプ(ミリ秒) |
サービス プロバイダ - 名前 | 任意 |
サービス プロバイダの名前。 注: サービス プロバイダにはテキストまたは画像のいずれかが必要です。 |
自由形式のテキスト。例: イベントの主催者/ツアーの名前 |
サービス プロバイダ - 画像 | 任意 |
サービス プロバイダのロゴまたは画像。 注: サービス プロバイダにはテキストまたは画像のいずれかが必要です。 |
詳しくは、画像の仕様をご覧ください。 |
説明 | 任意 | エンティティを説明する 1 段落のテキスト。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 推奨テキストサイズは 180 文字 |
字幕リスト | 任意 | 最大 3 つの字幕(各字幕には 1 行のテキスト)。 注: ユーザーには、説明または字幕リストが両方ではなく、いずれか一方が表示されます。 |
自由形式のテキスト 各サブタイトルの推奨テキストサイズ: 最大 50 文字 |
バッジ | 任意 |
各バッジには、自由形式のテキスト(最大 15 文字)または小さい画像を使用できます。 |
|
バッジ - テキスト | 任意 | バッジのタイトル 注: バッジにはテキストまたは画像が必要です。 |
自由形式のテキスト 推奨テキストサイズは 15 文字以内 |
バッジ - 画像 | 任意 | 小さい画像 特別な UX 処理(画像や動画のサムネイルにバッジをオーバーレイするなど)。 注: バッジにはテキストまたは画像が必要です。 |
詳しくは、画像の仕様をご覧ください。 |
予約 ID | 任意 | イベント予約の予約 ID。 | 自由形式のテキスト |
価格 - 現在の価格 | 条件付きで必須 |
イベントのチケット/パスの現在の料金。 取り消し線を引いた価格を指定する場合は必須です。 |
自由形式のテキスト |
価格 - 取り消し線 | 任意 | イベントのチケット/パスの元の価格。 | 自由形式のテキスト |
価格のコールアウト | 任意 | プロモーション、イベント、メンバー割引をアピールするための価格コールアウト(利用可能な場合)。 | 自由形式のテキスト 推奨テキストサイズは 45 文字未満(テキストが長すぎると省略記号が表示されます) |
評価 - 最高値 | 任意 | 段階別評価の最高値。 現在の評価値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 現在の値 | 任意 | 段階別評価の現在の値。 評価の最高値も指定する場合は必須です。 |
0.0 以上の数値。 |
評価 - 件数 | 任意 | イベントの評価のカウント。 注: ユーザーへの表示方法をアプリで制御する場合は、このフィールドを指定します。ユーザーに表示される簡潔な文字列を指定してください。たとえば、カウントが 1,000,000 の場合は、1M などの略語を使用して、小さいディスプレイ サイズで切り捨てられないようにすることを検討してください。 |
文字列 |
評価 - カウント値 | 任意 | イベントの評価のカウント。 注: 表示省略ロジックを独自に処理しない場合は、このフィールドを指定します。「カウント」と「カウント値」の両方が存在する場合は、カウントを使用してユーザーに表示します。 |
詳細 |
コンテンツ カテゴリ | 任意 | エンティティ内のコンテンツのカテゴリを記述します。 | 有効な列挙型のリスト
詳しくは、コンテンツ カテゴリのセクションをご覧ください。 |
画像の仕様
次の表に、画像アセットに必要な仕様を示します。
アスペクト比 | 最小ピクセル数 | 推奨ピクセル数 |
---|---|---|
スクエア(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 や Generic FeaturesEntity などのエンティティでは、すべてのコンテンツ カテゴリを使用できます。EventEntity、EventReservationEntity、PersonEntity などのエンティティでは、これらのカテゴリのサブセットのみが対象になります。リストにデータを入力する前に、エンティティ タイプに使用できるカテゴリのリストを確認してください。
一部のコンテンツ カテゴリには、汎用エンティティと ContentCategory の組み合わせではなく、特定のエンティティ タイプを使用します。
- TYPE_MOVIES_AND_TV_SHOWS - 汎用エンティティを使用する前に、スマートウォッチの統合ガイドでエンティティを確認します。
- 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
ユーザーがログインしていないためにコンテンツが公開されていない場合は、ログインカードを公開することをおすすめします。なんらかの理由でプロバイダがログインカードを公開できない場合は、ステータス コード 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
として返され、その原因はエラーコードとして含まれます。
エラーコード | 注 |
---|---|
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
クラスのインスタンスを動的に登録します。これにより、メモリ内でまだアクティブになっているアプリからの通信が可能になります。
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 が確認したら、おすすめコンテンツ、注目コンテンツ、連続性の各クラスタが公開され、ユーザーに表示されます。