Engage SDK Health and Fitness:第三方技術整合操作說明

在使用者所在位置觸及他們,提升應用程式參與度。整合 Engage SDK,即可在多個裝置端途徑直接向使用者提供個人化推薦內容和續播內容,例如收藏Entertainment Space 和 Play 商店。整合後,平均每個 APK 會增加不到 50 KB (壓縮後),且大多數應用程式的開發人員只需約一週時間即可完成。詳情請造訪商家網站

本指南適用於開發合作夥伴,提供將健康與健身內容傳送至 Engage 內容途徑的操作說明。

整合詳情

術語

這項整合包含以下三個叢集類型:推薦精選接續

  • 「推薦」叢集會顯示個別開發合作夥伴提供的個人化健康與健身建議。推薦內容可以根據使用者的個人需求提供,或是一般項目 (例如熱門健身與健康內容)。你可以使用這些主題標籤,找出與健康和健身相關的文章或使用者。

    • 推薦叢集可由 ArticleEntityPersonEntityEventEntity 組成,但不能混合不同實體類型的推薦內容。

    推薦內容採用以下結構:

    • 推薦叢集:此 UI 檢視畫面包含相同開發合作夥伴提供的一組推薦內容。

    • 實體:代表叢集中單一項目的物件。這項整合功能提供一些實體,可透過推薦叢集顯示:

      • ArticleEntity:ArticleEntity 代表與健康與健身相關的文字內容建議。可用於文章、網誌文章、行銷內容、新聞摘要等。

        圖 1:UI 顯示推薦叢集內的單一 ArticleEntity。
      • PersonEntity:PersonEntity 代表一個人。建議可以著重於教練或任何與健康和健身相關的人士等。

        圖 2:UI 顯示「推薦」叢集內的單一 PersonEntity。
      • EventEntity:EventEntity 代表未來發生的活動。活動開始時間是必須傳達給使用者的重要資訊。這個實體可用於顯示與健康和健身相關的活動,例如捐血營、訓練課程、健身房或瑜珈課程等。

        圖 3:UI 顯示推薦叢集內的單一 EventEntity。
  • 接續叢集會在單一 UI 群組中,顯示多個開發合作夥伴所提供使用者最近互動的內容。每個開發合作夥伴最多可在接續叢集中播送 10 個實體。

    後續內容可採用以下結構:

    • ArticleEntity:ArticleEntity 代表與健康與健身相關的文字內容建議。這個實體可用來表示未完成的新聞文章或其他內容,使用者可從上次中斷的地方繼續閱讀。例如:新聞片段、有關健康或健身相關主題的網誌文章片段。

      圖 6. UI 顯示「接續」叢集內的單一 ArticleEntity。
    • EventReservationEntity:EventReservationEntity 代表活動預訂,可協助使用者追蹤即將到來或正在進行的健身和健康活動預訂。例如:訓練課程

      圖 8.UI 顯示「接續」叢集內的單一 EventReservationEntity。
  • 「精選」叢集會在一個 UI 群組中展示多個開發合作夥伴提供的精選實體。這個單一精選叢集會顯示在靠近 UI 頂端的位置,並且優先放置在所有推薦叢集的上方。每個開發合作夥伴最多可在精選叢集中播送 10 個實體。

    • GenericFeaturedEntity:GenericFeaturedEntity 與建議項目不同,精選項目應僅用於開發人員提供的單一頂尖內容,且應代表對使用者而言最重要、最有趣且最相關的內容。

      圖 12:UI 顯示精選叢集中的單一主打 GenericFeaturedEntity 資訊卡

事前作業

最低 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'
}

摘要

這項設計是以繫結服務的實作為基礎。

用戶端可發布的資料受到不同叢集類型的限制,如下所示:

叢集類型 叢集限制 單一叢集中的實體數量下限 單一叢集中的實體數量上限
推薦叢集 最多 7 個 至少 1 個 最多 50 個 (ArticleEntityPersonEntityEventEntity)
接續叢集 最多 1 個 至少 1 個 最多 20 個 (ArticleEntityEventReservationEntity)
精選叢集 最多 1 個 至少 1 個 最多 20 個 (GenericFeaturedEntity)

步驟 1:提供實體資料

SDK 定義了不同實體,用來代表各種項目類型。「健康與健身」類別支援下列實體:

  1. GenericFeaturedEntity
  2. ArticleEntity
  3. PersonEntity
  4. EventEntity
  5. EventReservationEntity

下方圖表列出各類型的可用屬性和必要性。

GenericFeaturedEntity

屬性 必要性 說明 格式
動作 URI 必要

服務供應商應用程式中實體的深層連結。

注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章

URI
代表圖片 必要

如果提供多張圖片,系統只會顯示 1 張。 建議顯示比例為 16:9

注意:如果提供徽章,請確保圖片頂端和底部都有 24 dp 的安全空間

如需相關指南,請參閱「圖片規格」一節。
標題 選用 實體名稱。

任意文字

建議文字長度:50 個半形字元

說明 選用

描述實體的單一段落文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

建議文字長度:最多 180 個半形字元

字幕清單 選用

最多 3 個副標題,每個副標題為一行文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

每個副標題的建議文字長度:最多 50 個半形字元

徽章 選用

每個徽章可以是任意文字 (最多 15 個字元),也可以是小型圖片。

在圖片/影片上進行特殊 UX 處理,例如在圖片上疊加徽章

  • 「即時更新」
  • 文章閱讀時間長度
徽章 - 文字 選用

徽章名稱

注意:徽章必須包含文字或圖片

任意文字

建議文字長度:最多 15 個半形字元

徽章 - 圖片 選用

小型圖片

特殊使用者體驗處理方式,例如在圖片/影片縮圖上疊加徽章。

注意:徽章必須包含文字或圖片

如需相關指南,請參閱「圖片規格」一節。
內容類別 選用 描述實體中內容的類別。

列舉清單

如需相關指引,請參閱「內容類別」一節。

ArticleEntity

屬性 必要性 說明 格式
動作 URI 必要

服務供應商應用程式中實體的深層連結。

注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章

URI
標題 必要 實體名稱。

任意文字

建議文字長度:最多 50 個半形字元

代表圖片 選用

如果提供多張圖片,系統只會顯示 1 張。 建議顯示比例為 16:9

注意:強烈建議提供圖片。如果提供徽章,請確保圖片頂端和底部都有 24 dp 的安全空間

如需相關指南,請參閱「圖片規格」一節。
來源 - 標題 選用 作者、機構或記者的名稱

任意文字

建議文字長度:最多 25 個半形字元

來源 - 圖片 選用 來源圖片,例如作者、機構、記者 如需相關指南,請參閱「圖片規格」一節。
說明 選用

描述實體的單一段落文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

建議文字長度:最多 180 個半形字元

字幕清單 選用

最多 3 個副標題,每個副標題為一行文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

每個副標題的建議文字長度:最多 50 個半形字元

徽章 選用

每個徽章可以是任意文字 (最多 15 個字元),也可以是小型圖片。

在圖片/影片上進行特殊 UX 處理,例如在圖片上疊加徽章

  • 「即時更新」
  • 文章閱讀時間長度
徽章 - 文字 選用

徽章名稱

注意:徽章必須包含文字或圖片

任意文字

建議文字長度:最多 15 個半形字元

徽章 - 圖片 選用

小型圖片

特殊使用者體驗處理方式,例如在圖片/影片縮圖上疊加徽章。

注意:徽章必須包含文字或圖片

如需相關指南,請參閱「圖片規格」一節。
內容發布時間 選用 這是內容在應用程式中發布 / 更新時的 Epoch 時間戳記 (以毫秒為單位)。 以毫秒為單位的 Epoch 紀元時間戳記
上次互動時間 某些情況下必填

使用者上次與這個實體互動時的毫秒級時間戳記。

注意:如果這個實體屬於延續叢集,則必須填寫這個欄位。

以毫秒為單位的 Epoch 紀元時間戳記
進度百分比 某些情況下必填

使用者至今觀看完整內容的百分比。

注意:如果這個實體屬於延續叢集,則必須填寫這個欄位。

介於 0 到 100 之間 (含 0 和 100) 的 int 值。
內容類別 選用 描述實體中內容的類別。

列舉清單

如需相關指引,請參閱「內容類別」一節。

PersonEntity

屬性 必要性 說明 格式
動作 URI 必要

服務供應商應用程式中實體的深層連結。

注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章

URI
設定檔 - 名稱 必要 個人資料名稱,或 ID/帳號代碼,例如「John Doe」、「@TeamPixel」等。

字串

建議文字長度:最多 50 個半形字元

個人資料 - 顯示圖片 必要

使用者的個人資料相片或顯示圖片。

注意:必須是 1:1 的正方形圖片。

如需相關指南,請參閱「圖片規格」一節。
個人資料 - 其他文字 選用 任意文字,例如商家檔案控點。

任意文字

建議文字長度:最多 15 個半形字元

個人資料 - 其他圖片 選用 小型圖片,例如驗證徽章。 如需相關指南,請參閱「圖片規格」一節。
標題圖片 選用

如果提供多張圖片,系統只會顯示 1 張。 建議顯示比例為 16:9

注意:強烈建議提供圖片。如果提供徽章,請確保圖片頂端和底部都有 24 dp 的安全空間

如需相關指南,請參閱「圖片規格」一節。
熱門程度 - 數量 選用

表示追蹤者人數或熱門程度值,例如「370 萬」。

注意:如果同時提供「計數」和「計數值」,系統會使用「計數」。

字串

建議文字長度:次數 + 標籤合計最多 20 個半形字元

熱門程度 - 數量值 選用

追蹤者人數或熱門程度值。

注意:如果應用程式不想處理邏輯,瞭解如何針對不同顯示大小最佳化大量項目,請提供 Count Value。如果同時提供「計數」和「計數值」,系統會使用「計數」。

熱門程度 - 標籤 選用 指出熱門程度標籤,例如「按讚」。

字串

建議文字長度:次數 + 標籤合計最多 20 個半形字元

熱門程度 - 視覺化 選用

指出互動目的,例如:顯示按讚圖示、表情符號的圖片。

可以提供多張圖片,但不一定在所有板型規格上都能顯示。

注意:必須是 1:1 正方形圖片

如需相關指南,請參閱「圖片規格」一節。
評分 - 最高值 必填

分級量表的最高值。

如果同時提供目前的評分值,則必須提供這項屬性。

大於或等於 0.0 的數字
評分 - 目前的值 必填

評分量表的目前值。

如果同時提供最高評分值,則須提供這項屬性。

大於或等於 0.0 的數字
評分 - 次數 選用

實體的評分次數。

注意:如果應用程式會控管向使用者顯示的計數,請提供這個欄位。使用簡潔的字串。 舉例來說,如果計數為 1,000,000,請考慮使用縮寫 (例如 1M),以免計數在較小的螢幕上遭到截斷。

字串
評分 - 次數值 選用

實體的評分次數。

注意:如果您未自行處理顯示縮寫邏輯,請提供這個欄位。如果同時提供「數量」和「數量值」,系統會向使用者顯示「數量」。

地點 - 國家/地區 選用 該人員所在的國家/地區或服務地點。

任意文字

建議文字長度:最多約 20 個半形字元

地點 - 城市 選用 該人員所在的城市或服務地點。

任意文字

建議文字長度:最多約 20 個半形字元

位置 - 顯示地址 選用 系統會向使用者顯示該人員所在或服務的地址。

任意文字

建議文字長度:最多約 20 個半形字元

地點 - 街道地址 選用 該人員所在或服務的街道地址 (如適用)。

任意文字

建議文字長度:最多約 20 個半形字元

地點 - 州/省 選用 該人員所在的州 (如適用)。

任意文字

建議文字長度:最多約 20 個半形字元

地點 - 郵遞區號 選用 該人員所在或服務地點的郵遞區號 (如適用)。

任意文字

建議文字長度:最多約 20 個半形字元

地點 - 鄰近地區 選用 人員所在或服務的鄰里 (如適用)。

任意文字

建議文字長度:最多約 20 個半形字元

徽章 選用

每個徽章可以是任意文字 (最多 15 個字元),也可以是小型圖片。

徽章 - 文字 選用

徽章名稱

注意:徽章必須包含文字或圖片

任意文字

建議文字長度:最多 15 個半形字元

徽章 - 圖片 選用

小型圖片

特殊使用者體驗處理方式,例如在圖片/影片縮圖上疊加徽章。

注意:徽章必須包含文字或圖片

如需相關指南,請參閱「圖片規格」一節。
說明 選用

描述實體的單一段落文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

建議文字長度:最多 180 個半形字元

字幕清單 選用

最多 3 個副標題,每個副標題為一行文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

每個副標題的建議文字長度:最多 50 個半形字元

內容類別 選用 描述實體中內容的類別。

符合資格的列舉清單

  • TYPE_HEALTH_AND_FITENESS (例如:瑜珈/健身教練)
  • TYPE_HOME_AND_AUTO (例如:水電工)
  • TYPE_SPORTS (例如:球員)
  • TYPE_DATING

如需相關指引,請參閱「內容類別」一節。

EventEntity

屬性 必要性 說明 格式
動作 URI 必要

服務供應商應用程式中實體的深層連結。

注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章

URI
標題 必要 實體名稱。

字串

建議文字長度:最多 50 個半形字元

開始時間 必要

活動預計開始的 Epoch 時間戳記。

注意:這項指標會以毫秒為單位表示。

以毫秒為單位的 Epoch 紀元時間戳記
活動模式 必要

這個欄位用於指出活動是線上、現場或混合式。

列舉: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 個半形字元

結束時間 選用

預計活動結束時間的 Epoch 時間戳記。

注意:這項指標會以毫秒為單位表示。

以毫秒為單位的 Epoch 紀元時間戳記
說明 選用

描述實體的單一段落文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

建議文字長度:最多 180 個半形字元

字幕清單 選用

最多 3 個副標題,每個副標題為一行文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

每個副標題的建議文字長度:最多 50 個半形字元

徽章 選用

每個徽章可以是任意文字 (最多 15 個字元),也可以是小型圖片。

徽章 - 文字 選用

徽章名稱

注意:徽章必須包含文字或圖片

任意文字

建議文字長度:最多 15 個半形字元

徽章 - 圖片 選用

小型圖片

特殊使用者體驗處理方式,例如在圖片/影片縮圖上疊加徽章。

注意:徽章必須包含文字或圖片

如需相關指南,請參閱「圖片規格」一節。
價格 - CurrentPrice 在特定情況下為必要

活動票券/通行證的目前價格。

如果提供了原價,則必須提供這項屬性。

任意文字
價格 - StrikethroughPrice 選用 活動票券/通行證的原始價格。 任意文字
價格摘要 選用 價格宣傳,用來主打促銷、活動、會員折扣 (如有)。

任意文字

建議文字長度:最多 45 個半形字元,過長部分會以刪節號顯示

內容類別 選用 描述實體中內容的類別。

符合資格的列舉清單

  • TYPE_MOVIES_AND_TV_SHOWS (例如:電影院)
  • TYPE_DIGITAL_GAMES (例如:電競)
  • TYPE_MUSIC (例如:音樂會)
  • TYPE_TRAVEL_AND_LOCAL (例如:旅遊、節慶)
  • TYPE_HEALTH_AND_FITENESS (例如:瑜珈課)
  • TYPE_EDUCATION (範例 - 類別)
  • TYPE_SPORTS (例如:足球賽)
  • TYPE_DATING (例如:meetup)

如需相關指引,請參閱「內容類別」一節。

EventReservationEntity

屬性 必要性 說明 格式
動作 URI 必要

服務供應商應用程式中實體的深層連結。

注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章

URI
標題 必要 實體名稱。

字串

建議文字長度:最多 50 個半形字元

開始時間 必要

活動預計開始的 Epoch 時間戳記。

注意:這項指標會以毫秒為單位表示。

以毫秒為單位的 Epoch 紀元時間戳記
活動模式 必要

這個欄位用於指出活動是線上、現場或混合式。

列舉: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 的安全空間

如需相關指南,請參閱「圖片規格」一節。
結束時間 選用

預計活動結束時間的 Epoch 時間戳記。

注意:這項指標會以毫秒為單位表示。

以毫秒為單位的 Epoch 紀元時間戳記
服務供應商 - 名稱 選用

服務供應商名稱。

注意:服務供應商必須提供文字或圖片。

任意文字。例如活動主辦人/巡迴演唱會的名稱
服務供應商 - 圖片 選用

服務供應商的標誌/圖片。

注意:服務供應商必須提供文字或圖片。

如需相關指南,請參閱「圖片規格」一節。
說明 選用

描述實體的單一段落文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

建議文字長度:最多 180 個半形字元

字幕清單 選用

最多 3 個副標題,每個副標題為一行文字。

注意:系統會向使用者顯示說明或副標題清單,但不會同時顯示兩者。

任意文字

每個副標題的建議文字長度:最多 50 個半形字元

徽章 選用

每個徽章可以是任意文字 (最多 15 個字元),也可以是小型圖片。

徽章 - 文字 選用

徽章名稱

注意:徽章必須包含文字或圖片

任意文字

建議文字長度:最多 15 個半形字元

徽章 - 圖片 選用

小型圖片

特殊使用者體驗處理方式,例如在圖片/影片縮圖上疊加徽章。

注意:徽章必須包含文字或圖片

如需相關指南,請參閱「圖片規格」一節。
預訂 ID 選用 預訂活動的預訂 ID。 任意文字
價格 - CurrentPrice 在特定情況下為必要

活動票券/通行證的目前價格。

如果提供了原價,則必須提供這項屬性。

任意文字
價格 - StrikethroughPrice 選用 活動票券/通行證的原始價格。 任意文字
價格摘要 選用 價格宣傳,用來主打促銷、活動、會員折扣 (如有)。

任意文字

建議文字長度:最多 45 個半形字元,過長部分會以刪節號顯示

評分 - 最高值 選用

分級量表的最高值。

如果同時提供目前的評分值,則必須提供這項屬性。

大於或等於 0.0 的數字
評分 - 目前的值 選用

評分量表的目前值。

如果同時提供最高評分值,則須提供這項屬性。

大於或等於 0.0 的數字
評分 - 次數 選用

活動的評分次數。

注意:如果應用程式要控管這項資訊的顯示方式,請提供這個欄位。請提供可向使用者顯示的簡短字串。舉例來說,如果計數為 1,000,000,請考慮使用 1M 等縮寫,以免在較小的螢幕上遭到截斷。

字串
評分 - 次數值 選用

活動的評分次數。

注意:如果您不想自行處理顯示縮寫邏輯,請提供這個欄位。如果同時提供「數量」和「數量值」,系統會使用「數量」向使用者顯示

內容類別 選用 描述實體中內容的類別。

符合資格的列舉清單

  • TYPE_MOVIES_AND_TV_SHOWS (例如:電影院)
  • TYPE_DIGITAL_GAMES (例如:電競)
  • TYPE_MUSIC (例如:音樂會)
  • TYPE_TRAVEL_AND_LOCAL (例如:旅遊、節慶)
  • TYPE_HEALTH_AND_FITENESS (例如:瑜珈課)
  • TYPE_EDUCATION (範例 - 類別)
  • TYPE_SPORTS (例如:足球賽)
  • TYPE_DATING (例如:meetup)

如需相關指引,請參閱「內容類別」一節。

圖片規格

圖片素材資源的規格規定如下表所示:

顯示比例 最低像素 建議的像素

正方形 (1x1)

建議採用

300x300 1200x1200
橫向 (1.91x1) 600x314 1200x628
直向 (4x5) 480x600 960x1200

圖片必須在公開 CDN 上代管,以便 Google 存取。

檔案格式

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

圖片必須在公開 CDN 上代管,以便 Google 存取。

內容類別使用指南

  1. 部分實體 (例如 ArticleEntityGenericFeaturedEntity) 適用於任何內容類別。如果是其他實體 (例如 EventEntityEventReservationEntityPersonEntity),只有這些類別的子集符合資格。填入清單前,請先查看符合實體類型資格的類別清單。
  2. 對於某些內容類別,請使用特定實體類型,而非一般實體和 ContentCategory 的組合:

    • TYPE_MOVIES_AND_TV_SHOWS - 使用一般實體前,請先參閱智慧手錶整合指南中的實體。
    • TYPE_BOOKS - Check out the EbookEntity before using the generic entities.
    • TYPE_AUDIOBOOKS - Check out AudiobookEntity before using the generic entities.
    • TYPE_SHOPPING - 結帳前請先查看 ShoppingEntity,再使用一般實體。
    • TYPE_FOOD_AND_DRINK - 使用一般實體前,請先參閱食品整合指南中的實體。
  3. ContentCategory 欄位為選填欄位,如果內容不屬於上述任何類別,請將此欄位留空。

  4. 如果提供多個內容類別,請依與內容的相關性排序,最相關的內容類別應列在清單最前面。

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

服務收到要求後,系統會在單一交易中執行以下動作:

  • 移除開發合作夥伴提供的現有 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());

服務收到要求後,系統會在單一交易中執行以下動作:

  • 移除開發合作夥伴提供的現有 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());

服務收到要求後,系統會在單一交易中執行以下動作:

  • 移除開發合作夥伴提供的現有 ContinuationCluster 資料。
  • 剖析要求所提供的資料並儲存在更新後的接續叢集中。

如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。

publishUserAccountManagementRequest

這個 API 是用來發布「登入」資訊卡。登入動作會將使用者導向應用程式的登入頁面,方便應用程式發布內容 (或提供更個人化的內容)

登入資訊卡包含下列中繼資料:

屬性 必要性 說明
動作 URI 必要 導向動作的深層連結,也就是前往應用程式登入頁面
圖片 選用 - 如未提供,則必須提供標題

資訊卡上顯示的圖片

解析度 1264x712、顯示比例 16x9 的圖片

標題 選用 - 如未提供,則必須提供圖片 資訊卡上的標題
動作文字 選用 行動號召中顯示的文字,也就是「登入」
副標題 選用 資訊卡上的選用副標題

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

服務收到要求後,系統會在單一交易中執行以下動作:

  • 移除開發合作夥伴提供的現有 UserAccountManagementCluster 資料。
  • 剖析要求所提供的資料並儲存在更新後的 UserAccountManagementCluster 叢集中。

如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。

updatePublishStatus

如因內部業務原因,導致無法發布任何叢集,我們強烈建議使用 updatePublishStatus API 更新發布狀態。這麼做很重要,因為:

  • 在所有情況下,提供狀態都至關重要,即使內容已發布 (STATUS == PUBLISHED) 也一樣。如此一來,才能為資訊主頁填入資料,並以明確的狀態表示整合項目的健康度和其他指標。
  • 如未發布內容,但整合狀態未遭中斷 (STATUS == NOT_PUBLISHED),Google 便可避免在應用程式健康資訊主頁中觸發快訊。這可從提供者的角度確認內容是因預期的情況而未發布。
  • 這有助開發人員深入瞭解資料何時已發布或未發布。
  • 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

如果內容因使用者未登入而未發布,建議您發布登入資訊卡。如因任何原因導致提供者無法發布登入資訊卡,建議您呼叫 updatePublishStatus API,並使用狀態碼 NOT_PUBLISHED_REQUIRES_SIGN_IN

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 可用來刪除 UserAccountManagement 叢集的內容。

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

服務收到要求後,會從 UserAccountManagement 叢集中移除現有資料。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。

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

服務收到要求後,會從符合指定叢集類型的所有叢集中移除現有資料。用戶端可以選擇傳遞一或多個叢集類型。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。

處理錯誤

強烈建議您監聽來自發布 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 Service 判定內容可能過時 (例如已滿一週)。這樣一來,即使應用程式已有長時間未執行,使用者也能獲得最新的內容體驗。

BroadcastReceiver 必須透過下列兩種方式進行設定:

  • 使用 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),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}
  • AndroidManifest.xml 檔案中使用 <receiver> 標記,以靜態方式宣告實作項目。這樣應用程式就能在未執行的狀態下接收廣播意圖,也能發布內容。

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      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 與我們聯絡。

後續步驟

完成這項整合後,後續步驟如下:

  • 傳送電子郵件至 engage-developers@google.com,並附上整合完成可供 Google 測試的 APK。
  • Google 會在內部執行驗證及審查,確認整合項目能夠正常運作。如果需要進行變更,Google 會與您聯絡並提供所有必要詳細資料。
  • 測試完成後,如果不需要進行任何變更,Google 會與您聯絡,通知您可以開始將完成整合的更新版 APK 發布至 Play 商店。
  • Google 確認您已將更新版 APK 發布至 Play 商店後,就會發布您的推薦精選接續叢集供使用者瀏覽。