Engage SDK 其他產業：第三方技術整合操作說明

Google 正在建構的裝置端途徑會依產業別將使用者的應用程式分門別類，並提供全新沉浸式體驗，可供使用者取用及瀏覽個人化應用程式內容。開發合作夥伴可以利用這個全螢幕體驗，在應用程式以外的專屬管道展示最精彩的多媒體內容。

本文件適用對象為開發合作夥伴，提供透過 Engage SDK 填入此新途徑區域，整合預訂、活動、住宿、景點、人物和其他可能不屬於上述任何類別的新內容的操作說明。

整合詳情

術語

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

• 「推薦」叢集會顯示個別開發合作夥伴提供的個人化建議。此 UI 檢視畫面包含相同開發合作夥伴提供的一組推薦內容。

  • ArticleEntity：ArticleEntity 代表與多個內容類別相關的文字推薦內容。與 GenericFeaturedEntity 相比，ArticleEntity 項目可讓開發人員提供各種文字和圖片內容，並附上更多中繼資料，向使用者說明資訊。例如：行銷內容、新聞摘要

    

    圖 1：UI 顯示推薦叢集內的單一 ArticleEntity。

  • EventEntity：EventEntity 代表未來發生的事件。事件開始時間是需要傳達給使用者的關鍵資訊。

    

    圖 2：顯示建議叢集中單一 EventEntity 的 UI。

  • LodgingEntity：LodgingEntity 代表住宿地點，例如飯店、公寓、度假屋 (短期) 和長期租賃。

    

    圖 3：在建議叢集中顯示單一 LodgingEntity 的使用者介面。

  • StoreEntity：StoreEntity 代表商店、餐廳、咖啡廳等，會在需要向使用者傳達餐飲場所或商店重要資訊的內容中加以強調。

    

    圖 4：UI 顯示推薦叢集內的單一 StoreEntity。

  • PointOfInterestEntity：PointOfInterestEntity 代表加油站、活動場地、主題樂園、博物館、觀光景點、健行步道等地點。如果位置資訊是需要傳達給使用者的關鍵資訊，就會以醒目顯示的方式呈現。不應用於住宿、商店或餐飲場所。

    

    圖 5：UI 顯示推薦叢集內的單一 PointOfInterestEntity。

  • PersonEntity：PersonEntity 代表個人。建議內容可能會在健康與健身、運動、約會等類別中，突顯某位使用者。

    

    圖 5：UI 顯示推薦叢集內的單一 PersonEntity。

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

  接續內容可採用以下結構：

  • ArticleEntity：ArticleEntity 代表與多個內容類別相關的文字推薦內容。這個實體可用於代表尚未看完的新聞文章，或是使用者想從離開頁面繼續存取的其他內容。例如：行銷內容、新聞摘要

    

    圖 6. UI 顯示接續叢集內的單一 ArticleEntity。

  • RestaurantReservationEntity：RestaurantReservationEntity 代表餐廳或咖啡廳的訂位，可協助使用者追蹤即將到來或正在進行的餐廳訂位。

    

    圖 7. UI 顯示接續叢集內的單一 RestaurantReservationEntity。

  • EventReservationEntity：EventReservationEntity 代表活動的保留項目，並可協助使用者追蹤近期或進行中的活動預留項目。事件包括但不限於：

    • 體育賽事，例如預訂足球賽門票
    • 遊戲活動，例如預訂電競賽事
    • 娛樂活動，例如電影院電影預訂、演唱會、戲劇、簽書會
    • 旅遊或景點預訂，例如導覽、博物館票券
    • 社交/研討會/會議預訂
    • 教育/訓練課程預約

    

    圖 8.UI 顯示接續叢集內的單一 EventReservationEntity。

  • LodgingReservationEntity：LodgingEntityReservation 代表旅遊住宿預訂，可協助使用者追蹤即將到來或正在進行的飯店或度假民宿預訂。

    

    圖 9.UI 顯示接續叢集內的單一 LodgingReservationEntity。

  • TransportationReservationEntity：TransportationReservationEntity 代表任何交通工具的預訂資訊，可協助使用者追蹤即將出發或正在進行的航班、渡輪、火車、公車、叫車服務或郵輪的預訂資訊。

    

    圖 10.UI 顯示接續叢集內的單一 TransportationReservationEntity。

  • VehicleRentalReservationEntity：VehicleRentalReservationEntity 代表租車預訂，可協助使用者追蹤即將到期或正在進行的租車預訂。

    

    圖 11. UI 顯示「接續」叢集內的單一 VehicleRentalReservationEntity。

• 「精選」叢集是 UI 檢視畫面，會在一個 UI 群組中展示多個開發合作夥伴提供的精選主打 GenericFeaturedEntity。這個單一精選叢集會顯示在靠近 UI 頂端的位置，並且優先放置在所有推薦叢集的上方。每個開發合作夥伴可在精選叢集中播送支援類型的單一實體，因此在精選叢集中，可能會有來自多個應用程式開發人員的多個不同類型實體。

  • GenericFeaturedEntity：GenericFeaturedEntity 與推薦項目的差異在於，Featured 項目應用於開發人員的單一熱門內容，且應代表對使用者而言最有趣且相關的單一最重要內容。

    

    圖 12：在精選叢集中顯示單一主頁橫幅的通用精選 Entity 資訊卡

事前作業

最低 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、EventEntity、LodgingEntity、StoreEntity、PointOfInterestEntity 或 PersonEntity)
接續叢集	最多 1 個	至少 1 個	最多 10 個 (ArticleEntity、EventReservationEntity、LodgingReservationEntity、TransportationReservationEntity 或 VehicleRentalReservationEntity)
精選叢集	最多 1 個	至少 1 個	最多 10 個 (GenericFeaturedEntity)

步驟 1：提供實體資料

SDK 定義了不同實體，用來代表各種項目類型。Others 類別支援下列實體：

1. GenericFeaturedEntity
2. ArticleEntity
3. EventEntity
4. LodgingEntity
5. StoreEntity
6. PointOfInterestEntity
7. PersonEntity
8. RestaurantReservationEntity
9. EventReservationEntity
10. LodgingReservationEntity
11. TransportationReservationEntity
12. VehicleRentalReservationEntity

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

GenericFeaturedEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
代表圖片	必要	當您提供多張圖片時，我們只會顯示 1 張圖片。 建議長寬比為 16:9 注意：如有提供標記，請確保圖片頂端和底部都留有 24 dp 的空間	如需相關指南，請參閱「圖片規格」一節。
標題	選用	實體的名稱。	任意文字 建議文字長度：50 個半形字元
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個副標題的建議文字大小：最多 50 個半形字元
徽章	選用	每個徽章都是自由文字 (最多 15 個字元) 或小圖片。 在圖片/影片上方顯示特殊的使用者體驗，例如在圖片上重疊徽章 「即時更新」 文章閱讀時間長度
徽章 - 文字	選用	徽章的名稱 注意：徽章必須提供文字或圖片，	任意文字 建議文字長度：最多 15 個半形字元
徽章 - 圖片	選用	小型圖片 特殊的使用者體驗處理方式，例如在圖片/影片縮圖上疊加徽章。 注意：徽章必須包含文字或圖片	如需相關指南，請參閱「圖片規格」一節。
內容類別	選用	說明實體中的內容類別。	列舉清單 如需相關指引，請參閱「內容類別」一節。

ArticleEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題	URI
標題	必要	實體的名稱。	任意文字 建議文字長度：最多 50 個半形字元
代表圖片	選用	如果您提供多張圖片，我們只會顯示 1 張圖片。 建議長寬比為 16:9 注意：強烈建議使用圖片。如果提供徽章，請確保圖片頂部和底部都有 24 個像素/點的安全區域	如需相關指南，請參閱「圖片規格」一節。
來源 - 書名	選用	作者、機構或檢舉人的名稱	任意文字 建議文字長度：最多 25 個半形字元
來源 - 圖片	選用	來源圖片，例如作者、機構、記者	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個副標題的建議文字大小：最多 50 個半形字元
徽章	選用	每個徽章都是自由文字 (最多 15 個字元) 或小圖片。 在圖片/影片上方顯示特殊的使用者體驗，例如在圖片上重疊徽章 「即時更新」 文章閱讀時間長度
徽章 - 文字	選用	徽章的名稱 注意：徽章必須提供文字或圖片，	任意文字 建議文字長度：最多 15 個半形字元
徽章 - 圖片	選用	小型圖片 特殊的使用者體驗處理方式，例如在圖片/影片縮圖上疊加徽章。 注意：徽章必須包含文字或圖片	如需相關指南，請參閱「圖片規格」一節。
內容發布時間	選用	這是內容在應用程式中發布/更新時的 Epoch 時間戳記 (以毫秒為單位)。	以毫秒為單位的 Epoch 紀元時間戳記
上次互動時間	必要 (有條件)	使用者上次與這個實體互動時的紀元紀時 (以毫秒為單位)。 注意：如果這個實體是接續叢集的一部分，則必須填入這個欄位。	以毫秒為單位的 Epoch 紀元時間戳記
進度百分比	必要 (有條件)	使用者迄今已消耗的完整內容百分比。 注意：如果這個實體屬於接續叢集，則為必要欄位。	介於 0 至 100 之間的 int 值 (含 0 和 100)。
內容類別	選用	說明實體中的內容類別。	列舉清單 如需相關指引，請參閱「內容類別」一節。

EventEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題	URI
標題	必要	實體的名稱。	字串 建議文字長度：最多 50 個半形字元
開始時間	必要	事件預計開始的 Epoch 時間戳記。 注意：這會以毫秒為單位顯示。	以毫秒為單位的 Epoch 紀元時間戳記
事件模式	必要	這個欄位用於指出活動是線上、實體或兩者皆是。	列舉：VIRTUAL、IN_PERSON 或 HYBRID
代表圖片	必要	當您提供多張圖片時，我們只會顯示 1 張圖片。 建議長寬比為 16:9 注意：強烈建議使用圖片。如果提供徽章，請確保圖片頂部和底部都有 24 個像素/點的安全區域	如需相關指南，請參閱「圖片規格」一節。
地點 - 國家/地區	必要 (有條件)	舉辦活動的國家/地區。 注意：如果是 IN_PERSON 或 HYBRID 事件，就必須提供這項資訊	任意文字 建議文字長度：最多 20 個半形字元
地點 - 城市	必要 (有條件)	事件發生的城市。 注意：對於 IN_PERSON 或 HYBRID 的事件，此為必填屬性	任意文字 建議文字長度：最多 20 個半形字元
位置 - 顯示地址	必要 (有條件)	活動地點或場所名稱，應向使用者顯示。 注意：如果是 IN_PERSON 或 HYBRID 事件，就必須提供這項資訊	任意文字 建議文字長度：最多 20 個半形字元
地點 - 街道地址	選用	活動舉辦地點的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 州/省	選用	活動舉辦地點的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 郵遞區號	選用	活動舉辦地點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 社區	選用	活動舉辦地點的鄰 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
結束時間	選用	事件預計結束的 Epoch 時間戳記。 注意：這會以毫秒為單位顯示。	以毫秒為單位的 Epoch 紀元時間戳記
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個副標題的建議文字大小：最多 50 個半形字元
徽章	選用	每個徽章可以是任意文字 (最多 15 個半形字元) 或小型圖片。
徽章 - 文字	選用	徽章的名稱 注意：徽章必須提供文字或圖片，	任意文字 建議文字長度：最多 15 個半形字元
徽章 - 圖片	選用	小型圖片 特殊的使用者體驗處理方式，例如在圖片/影片縮圖上疊加徽章。 注意：徽章必須提供文字或圖片，	如需相關指南，請參閱「圖片規格」一節。
Price - CurrentPrice	在特定情況下為必要	活動票券/通行證目前的價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	活動票券/通行證的原始價格。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長的文字以刪節號顯示)
內容類別	選用	說明實體中的內容類別。	符合資格的列舉清單 TYPE_MOVIES_AND_TV_SHOWS (範例：Cinema) TYPE_DIGITAL_GAMES (範例：電子競技) TYPE_MUSIC (示例：演唱會) TYPE_TRAVEL_AND_LOCAL (範例：旅遊、節慶活動) TYPE_HEALTH_AND_FITENESS (範例 - 瑜伽課) TYPE_EDUCATION (範例 - 課程) TYPE_SPORTS (範例：足球賽) TYPE_DATING (範例：Meetup) 如需相關指引，請參閱「內容類別」一節。

LodgingEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	必要	實體的名稱。	字串 建議文字長度：最多 50 個半形字元
代表圖片	必要	當您提供多張圖片時，我們只會顯示 1 張圖片。建議的顯示比例為 16:9 注意：如果提供徽章，請確保圖片頂部和底部都有 24 個像素的安全區域	如需相關指南，請參閱「圖片規格」一節。
地點 - 國家/地區	必要	住宿地點的國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 城市	必要	住宿地點所在的城市。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 顯示地址	必要	要向使用者顯示的住宿地址。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 街道地址	選用	住宿地點的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 州/省	選用	住宿地點所在的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 郵遞區號	選用	住宿地點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 社區	選用	住宿地點 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
徽章	選用	每個徽章可以是任意文字 (最多 15 個半形字元) 或小型圖片。
徽章 - 文字	選用	徽章的名稱 注意：徽章必須提供文字或圖片，	任意文字 建議文字長度：最多 15 個半形字元
徽章 - 圖片	選用	小型圖片 特殊的使用者體驗處理方式，例如在圖片/影片縮圖上疊加徽章。 注意：徽章必須包含文字或圖片	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個字幕的建議文字長度：最多 50 個半形字元
AvailabilityTimeWindow - Start Time	選用	住宿預計開放/可預訂的 Epoch 時間戳記 (以毫秒為單位)。	以毫秒為單位的 Epoch 紀元時間戳記
AvailabilityTimeWindow - End Time	選用	以毫秒為單位的 Epoch 時間戳記，表示系統預計開放/提供住宿的時間。	以毫秒為單位的 Epoch 紀元時間戳記
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	住宿地點的評分次數。 注意：如果應用程式會控制向使用者顯示的計數方式，請提供這個欄位。使用精簡字串。 舉例來說，如果計數是 1,000,000，請考慮使用 1M 等縮寫，以免在較小的顯示器尺寸中遭到截斷。	字串
評分 - 計數值	選用	住宿地點的評分次數。 注意：如果您不自行處理顯示縮寫的邏輯，請提供這個欄位。如果同時有 Count 和 Count Value，系統會向使用者顯示 Count。	長
Price - CurrentPrice	在特定情況下為必要	住宿的目前價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	住宿服務的原始價格，在 UI 中會加上刪除線表示這個價格。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長部分會以刪節號顯示)

StoreEntity

StoreEntity 物件代表開發合作夥伴要發布的個別商店，例如餐廳或雜貨店。

屬性	必要性	說明	格式
代表圖片	必要	至少須提供一張圖片	如需相關指南，請參閱「圖片規格」一節。
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題	URI
標題	選用	商店名稱。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
位置	選用	商店的位置。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
摘要	選用	如果有，會是用來主打商店的促銷、活動或更新。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
摘要附屬細則	選用	摘要的附屬細則文字。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
說明	選用	商店說明。	任意文字 建議文字長度：最多 90 個半形字元，過長部分會以刪節號顯示
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	住宿地點的評分次數。 注意：如果應用程式想控制向使用者顯示的方式，請提供這個欄位。提供可向使用者顯示的簡短字串。舉例來說，如果計數是 1,000,000，請考慮使用 1M 等縮寫，以免在螢幕較小的裝置上順利顯示。	字串
評分 - 計數值	選用	住宿飯店的評分次數。 注意：如果您不想自行處理顯示縮寫邏輯，請提供這個欄位。如果「Count」和「Count Value」都存在，我們會使用「Count」向使用者顯示	長

PointOfInterestEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	必要	實體的名稱。	字串 建議文字長度：最多 50 個半形字元
代表圖片	必要	當您提供多張圖片時，我們只會顯示 1 張圖片。 建議長寬比為 16:9 注意：強烈建議使用圖片。如果提供徽章，請確保圖片頂部和底部都有 24 個像素/點的安全區域	如需相關指南，請參閱「圖片規格」一節。
地點 - 國家/地區	必要	搜尋點所在的國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 城市	必要	搜尋點發生的城市。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 顯示地址	必要	要向使用者顯示的搜尋點地址。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 街道地址	選用	搜尋點的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 州/省	選用	搜尋點所在的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 郵遞區號	選用	搜尋點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 社區	選用	搜尋點的鄰里 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
AvailabilityTimeWindow - Start Time	選用	預期 POI 開放/可用的 Epoch 時間戳記 (以毫秒為單位)。	以毫秒為單位的 Epoch 紀元時間戳記
AvailabilityTimeWindow - End Time	選用	紀元時間戳記 (以毫秒為單位)，表示 POI 預期開放/可供使用前所需的時間。	以毫秒為單位的 Epoch 紀元時間戳記
徽章	選用	每個徽章可以是任意文字 (最多 15 個半形字元) 或小型圖片。
徽章 - 文字	選用	徽章的名稱 注意：徽章必須提供文字或圖片，	任意文字 建議文字長度：最多 15 個半形字元
徽章 - 圖片	選用	小型圖片 特殊的使用者體驗處理方式，例如在圖片/影片縮圖上疊加徽章。 注意：徽章必須提供文字或圖片，	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個字幕的建議文字長度：最多 50 個半形字元
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	搜尋點的評分次數。 注意：如果應用程式會控制向使用者顯示的計數方式，請提供這個欄位。使用簡潔的字串。舉例來說，如果計數是 1,000,000，請考慮使用 1M 等縮寫，以免在較小的顯示器尺寸中遭到截斷。	字串
評分 - 計數值	選用	搜尋點的評分次數。 注意：如果您不自行處理顯示縮寫的邏輯，請提供這個欄位。如果「Count」和「Count Value」都存在，系統會向使用者顯示「Count」	長
Price - CurrentPrice	在特定情況下為必要	搜尋點的票券/入場券目前價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	景點的票券/入場券原價。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長部分會以刪節號顯示)
內容類別	選用	說明實體中的內容類別。	符合資格的列舉清單 TYPE_TRAVEL_AND_LOCAL TYPE_MOVIES_AND_TV_SHOWS (示例：戲院) TYPE_MEDICAL (範例：醫院) TYPE_EDUCATION (範例：學校) TYPE_SPORTS (範例：體育場) 如需相關指引，請參閱「內容類別」一節。

PersonEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
設定檔 - 名稱	必要	個人資料名稱，或 ID/帳號代碼，例如「John Doe」、「@TeamPixel」等	字串 建議文字長度：最多 50 個半形字元
設定檔 - 顯示圖片	必要	使用者的個人資料相片或顯示圖片。 注意：必須是正方形 1:1 圖片。	如需相關指南，請參閱「圖片規格」一節。
個人資料 - 其他文字	選用	任意文字，例如個人資料名稱。	任意文字 建議文字長度：最多 15 個半形字元
個人資料 - 其他圖片	選用	小型圖片，例如驗證徽章。	如需相關指南，請參閱「圖片規格」一節。
標題圖片	選用	如果您提供多張圖片，我們只會顯示 1 張圖片。 建議長寬比為 16:9 注意：強烈建議使用圖片。如果提供徽章，請確保圖片頂部和底部都有 24 個像素/點的安全區域	如需相關指南，請參閱「圖片規格」一節。
熱門程度 - 次數	選用	指出追蹤者人數或熱門程度值，例如「370 萬」。 注意：如果您同時提供「計數」和「計數」值，系統會使用「數量」	字串 建議文字長度：次數 + 標籤合計最多 20 個半形字元
熱門程度 - 計數值	選用	追蹤者人數或熱門度值。 注意：如果應用程式不想處理大數字應如何針對不同顯示大小進行最佳化，請提供計數值。如果同時提供 Count 和 Count Value，系統會使用 Count。	長
熱門程度 - 標籤	選用	指出熱門標籤的意思，例如「按讚」。	字串 建議文字長度：次數 + 標籤合計最多 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 如需相關指引，請參閱「內容類別」一節。

RestaurantReservationEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題	URI
標題	必要	實體的名稱。	字串 建議文字長度：最多 50 個半形字元
預訂開始時間	必要	預留項目預計啟動時間的 Epoch 時間戳記，以毫秒為單位。	以毫秒為單位的 Epoch 紀元時間戳記
地點 - 國家/地區	必要	餐廳舉辦的國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 城市	必要	提供餐廳的城市。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 顯示地址	必要	向使用者顯示的 prestaurant 地址。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 街道地址	選用	餐廳的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 州/省	選用	餐廳所在的州或省 (如有)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 郵遞區號	選用	餐廳的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 社區	選用	餐廳的社區 (如有)。	任意文字 建議文字長度：最多 20 個半形字元
代表圖片	選用	當您提供多張圖片時，我們只會顯示 1 張圖片。建議顯示比例為 16:9	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個字幕的建議文字長度：最多 50 個半形字元
資料表大小	選用	預訂群組中的人數	整數 > 0

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。	任意文字
Price - CurrentPrice	在特定情況下為必要	活動票券/通行證目前的價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	活動票券/通行證的原始價格。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長部分會以刪節號顯示)
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	事件的評分次數。 注意：如果應用程式想控制向使用者顯示的方式，請提供這個欄位。提供可向使用者顯示的簡短字串。舉例來說，如果計數為 1,000,000，建議使用 1M 等縮寫字，以免在較小的顯示大小中遭到截斷。	字串
評分 - 計數值	選用	事件的評分次數。 注意：如果您不想自行處理顯示縮寫邏輯，請提供這個欄位。如果「Count」和「Count Value」都存在，我們會使用「Count」向使用者顯示	長
內容類別	選用	說明實體中的內容類別。	符合資格的列舉清單 TYPE_MOVIES_AND_TV_SHOWS (範例：Cinema) TYPE_DIGITAL_GAMES (範例：電子競技) TYPE_MUSIC (示例：演唱會) TYPE_TRAVEL_AND_LOCAL (範例：旅遊、節慶活動) TYPE_HEALTH_AND_FITENESS (範例 - 瑜伽課) TYPE_EDUCATION (範例 - 課程) TYPE_SPORTS (範例：足球賽) TYPE_DATING (範例 - 聚會) 如需相關指引，請參閱「內容類別」一節。

LodgingReservationEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	必要	實體的名稱。	任意文字。例如「你的 12 月 12 日入住訂單」 建議文字長度：最多 50 個半形字元
入住時間	必要	以毫秒為單位的 Epoch 時間戳記，代表預訂的入住時間。	以毫秒為單位的 Epoch 紀元時間戳記
退房時間	必要	以毫秒為單位的 Epoch 時間戳記，代表預訂的退房時間。	以毫秒為單位的 Epoch 紀元時間戳記
地點 - 國家/地區	必要	住宿地點所在的國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 城市	必要	住宿地點所在的城市。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 顯示地址	必要	要向使用者顯示的住宿地址。	任意文字 建議文字長度：最多 20 個半形字元
地點 - 街道地址	選用	住宿地點的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 州/省	選用	住宿地點所在的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 郵遞區號	選用	住宿地點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
位置 - 社區	選用	住宿地點 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
代表圖片	選用	當您提供多張圖片時，我們只會顯示 1 張圖片。建議的顯示比例為 16:9 注意：如果提供徽章，請確保圖片頂部和底部都有 24 個像素的安全區域	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個字幕的建議文字長度：最多 50 個半形字元
預留項目 ID	選用	住宿預訂的預訂 ID。	任意文字
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	住宿地點的評分次數。 注意：如果應用程式想控制向使用者顯示的方式，請提供這個欄位。提供可向使用者顯示的簡短字串。舉例來說，如果計數是 1,000,000，請考慮使用 1M 等縮寫，以免在螢幕較小的裝置上順利顯示。	字串
評分 - 計數值	選用	住宿飯店的評分次數。 注意：如果您不想自行處理顯示縮寫邏輯，請提供這個欄位。如果「Count」和「Count Value」都存在，我們會使用「Count」向使用者顯示	長
Price - CurrentPrice	在特定情況下為必要	住宿的目前價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	住宿服務的原始價格，在 UI 中會加上刪除線表示這個價格。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長部分會以刪節號顯示)

TransportationReservationEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題	URI
標題	必要	實體的名稱。	任意文字。例如「SFO 到 SAN」 建議文字長度：最多 50 個半形字元
運輸類型	必要	預訂的交通工具類型。	值：FLIGHT、TRAIN、BUS 或 FERRY
出發時間	必要	以毫秒為單位的 Epoch 時間戳記，代表出發時間。	以毫秒為單位的 Epoch 紀元時間戳記
抵達時間	必要	代表抵達時間的 Epoch 時間戳記，以毫秒為單位。	以毫秒為單位的 Epoch 紀元時間戳記
出發地點 - 國家/地區	選用	出發國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
出發地點 - 城市	選用	出發城市。	任意文字 建議文字長度：最多 20 個半形字元
出發地點 - 顯示地址	選用	向使用者顯示的出發地點。	任意文字 建議文字長度：最多 20 個半形字元
出發地點 - 街道地址	選用	出發地點的街道地址 (如有)。	任意文字 建議文字長度：最多 20 個半形字元
出發地點 - 州/省	選用	出發地點的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
出發地點 - 郵遞區號	選用	出發地點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
出發地點 - 鄰近範圍	選用	出發地點的鄰里 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
抵達地點 - 國家/地區	選用	抵達國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
抵達地點 - 城市	選用	抵達的城市。	任意文字 建議文字長度：最多 20 個半形字元
到達地點 - 顯示地址	選用	向使用者顯示的抵達位置。	任意文字 建議文字長度：最多 20 個半形字元
抵達地點 - 街道地址	選用	抵達地點的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
抵達地點 - 州	選用	抵達地點的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
到達地點 - 郵遞區號	選用	抵達地郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
抵達地點 - 鄰	選用	抵達地點的鄰裡 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
服務供應商 - 名稱	選用	服務供應商的名稱。 注意：服務供應商必須提供文字或圖片。	任意文字。例如航空公司名稱
服務供應商 - 圖片	選用	服務供應商的標誌/圖片。 注意：服務供應商必須提供文字或圖片。	如需相關指南，請參閱「圖片規格」一節。
代表圖片	選用	當您提供多張圖片時，我們只會顯示 1 張圖片。建議的顯示比例為 16:9	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個字幕的建議文字長度：最多 50 個半形字元
預留項目 ID	選用	交通工具預訂的 ID。	任意文字
Price - CurrentPrice	在特定情況下為必要	目前的預訂價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	預留項目的原始價格，在 UI 中會加上刪除線表示這個價格。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長的文字以刪節號顯示)
交通運輸號碼	必填	航班號碼、公車號碼、火車號碼或渡輪/郵輪號碼。	任意文字
登機時間	必填	代表預訂航班登機時間的紀元時間戳記 (如適用)	以毫秒為單位的 Epoch 紀元時間戳記

VehicleRentalReservationEntity

屬性	必要性	說明	格式
動作 URI	必要	服務供應商應用程式中實體的深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	必要	實體的名稱。	任意文字。例如：「臺北市信義區」 建議文字長度：最多 50 個半形字元
取車時間	必要	代表預約取車時間的 Epoch 時間戳記。	以毫秒為單位的 Epoch 紀元時間戳記
回程時間	選用	代表預訂結束時間的 Epoch 時間戳記。	以毫秒為單位的 Epoch 紀元時間戳記
取車地址 - 國家/地區	選用	取貨地點的國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
取車地址 - 城市	選用	上車地點的城市。	任意文字 建議文字長度：最多 20 個半形字元
取車地址 - 顯示地址	選用	向使用者顯示的接送地點。	任意文字 建議文字長度：最多 20 個半形字元
取貨地址 - 街道地址	選用	取貨地點的街道地址 (如有)。	任意文字 建議文字長度：最多 20 個半形字元
取貨地址 - 州	選用	取貨地點的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
取車地址 - 郵遞區號	選用	取貨地點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
取車地址 - 鄰近地區	選用	取貨地點的社區 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 國家/地區	選用	退貨地點的國家/地區。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 城市	選用	退貨地點的城市。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 顯示地址	選用	向使用者顯示的退回位置。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 街道地址	選用	退貨地點的街道地址 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 州/省	選用	退貨地點的州或省 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 郵遞區號	選用	退貨地點的郵遞區號 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
退貨地址 - 鄰近地區	選用	退貨地點的鄰里 (如適用)。	任意文字 建議文字長度：最多 20 個半形字元
服務供應商 - 名稱	選用	服務供應商的名稱。 注意：服務供應商必須提供文字或圖片。	任意文字。例如「Avis Car Rental」
服務供應商 - 圖片	選用	服務供應商的標誌/圖片。 注意：服務供應商必須提供文字或圖片。	如需相關指南，請參閱「圖片規格」一節。
代表圖片	選用	當您提供多張圖片時，我們只會顯示 1 張圖片。建議顯示比例為 16:9	如需相關指南，請參閱「圖片規格」一節。
說明	選用	用來說明實體的單一段落文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 建議文字長度：180 個半形字元
字幕清單	選用	最多 3 個字幕，每個字幕為單行文字。 注意：系統會向使用者顯示說明或字幕清單，但不會同時顯示兩者。	任意文字 每個副標題的建議文字大小：最多 50 個半形字元
確認 ID	選用	租車預訂的確認 ID。	任意文字
Price - CurrentPrice	在特定情況下為必要	目前的預訂價格。 如果提供了附帶刪除線的價格，則必須提供這項屬性。	任意文字
價格 - 刪除線價格	選用	預留項目的原始價格，在 UI 中會加上刪除線表示這個價格。	任意文字
價格摘要	選用	主打促銷、活動、會員折扣的價格摘要 (如有)。	任意文字 建議文字長度：最多 45 個半形字元 (過長的文字以刪節號顯示)

圖片規格

圖片素材資源的規格規定如下：

顯示比例	最低像素	建議的像素
正方形 (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. ArticleEntity 和 GenericFeaturedEntity 等實體可使用任何內容類別。對於其他實體 (例如 EventEntity、EventReservationEntity、PointOfInterestEntity)，只有部分類別符合資格。填入清單之前，請先查看適用於實體類型的類別清單。

2. 針對某些內容類別，使用通用實體和 ContentCategory 的組合，而不是特定實體類型：

   • TYPE_MOVIES_AND_TV_SHOWS：請先參閱Watch 整合指南中的實體，再使用通用實體。
   • TYPE_BOOKS：使用泛型實體前，請先查看 EbookEntity。
   • TYPE_AUDIOBOOKS：請先查看 AudiobookEntity，再使用一般實體。
   • 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.
    }
});

注意：強烈建議您持續執行定期工作，檢查服務是否會在稍後恢復。Android 版本升級、應用程式升級、安裝和解除安裝程序都可能會影響服務的供應情形。只要確保以特定時間間隔的定期工作進行檢查，就能在服務可供使用時立即發布資料。

publishRecommendationClusters

這個 API 可用於發布 RecommendationCluster 物件清單。

重要事項：發布 API 屬於更新/插入 API，會取代現有內容。後續請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 基本上就會執行此操作。

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 物件清單。

重要事項：發布 API 屬於更新/插入 API，會取代現有內容。後續請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 基本上就會執行此操作。

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 物件。

重要事項：發布 API 屬於更新/插入 API，會取代現有內容。後續請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 基本上就會執行此操作。

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

重要事項：發布 API 屬於更新/插入 API，會取代現有內容。後續請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 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());

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

• 移除開發合作夥伴提供的現有 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 可用來刪除推薦叢集的內容。

重要事項：只有在沒有可發布的內容時，才應呼叫刪除 API。之後請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 本身就會執行此操作。使用刪除 API 前，請先來信至 engage-developers@ 與我們聯絡。

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

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

注意：這個 API 適用於 1.1.0 以上版本。

deleteFeaturedCluster

這個 API 可用來刪除精選叢集的內容。

重要事項：只有在沒有可發布的內容時，才應呼叫刪除 API。之後請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 本身就會執行此操作。使用刪除 API 前，請先來信至 engage-developers@ 與我們聯絡。

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

注意：這個 API 適用於 1.1.0 以上版本。

deleteContinuationCluster

這個 API 可用來刪除接續叢集的內容。

重要事項：只有在沒有可發布的內容時，才應呼叫刪除 API。之後請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 本身就會執行此操作。使用刪除 API 前，請先來信至 engage-developers@ 與我們聯絡。

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

注意：這個 API 適用於 1.1.0 以上版本。

deleteUserManagementCluster

這個 API 可用來刪除 UserAccountManagement 叢集的內容。

重要事項：只有在沒有可發布的內容時，才應呼叫刪除 API。之後請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 本身就會執行此操作。使用刪除 API 前，請先來信至 engage-developers@ 與我們聯絡。

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

注意：這個 API 適用於 1.1.0 以上版本。

deleteClusters

這個 API 可用於刪除指定叢集類型的內容。

重要事項：只有在沒有可發布的內容時，才應呼叫刪除 API。之後請勿呼叫刪除 API 和發布 API 來取代內容，因為發布 API 本身就會執行此操作。使用刪除 API 前，請先來信至 engage-developers@ 與我們聯絡。

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

// 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 常見問題」。

聯絡資訊

如果在整合過程中有任何問題，請來信至 [e-mail] 與我們聯絡。

後續步驟

完成這項整合後，後續步驟如下：

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