Engage SDK Food：第三方技術整合操作說明

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

本指南適用對象為開發合作夥伴，提供透過 Engage SDK 填入新途徑區域和現有 Google 途徑，整合食品內容的操作說明。

整合詳情

術語

這項整合包含以下五個叢集類型：推薦、精選、美食購物車、美食物購物清單和重新訂購。

• 推薦叢集會顯示個別開發合作夥伴提供的個人化食品相關建議。推薦內容可以根據使用者的個人需求提供，或是一般項目 (例如新品特賣)。您可以使用這些推薦內容，顯示合適的食譜、商店、餐點、雜貨等項目。

  • 推薦叢集可由 ProductEntity、StoreEntity 或 RecipeEntity 清單組成，但不能混合不同實體類型的推薦內容。

  

  圖 1：`ProductEntity`、`StoreEntity` 和 `RecipeEntity`。 (*UI 僅供說明)

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

  

  圖：含有 `RecipeEntity` 的推薦叢集。 (*UI 僅供說明)

• 美食購物車叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的雜貨購物車預覽畫面，提示使用者完成購物車流程。系統只提供單一美食購物車叢集。

  • 美食購物車叢集必須顯示購物車中的商品總數，也可能加入使用者購物車中 X 項商品的圖片。

    

    圖：單一合作夥伴提供的美食購物車叢集。(*UI 僅供說明之用)

• 美食購物清單叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的雜貨購物清單預覽畫面，提示使用者返回對應的應用程式更新並完成清單。系統只提供單一美食購物清單叢集。

  

  圖：單一合作夥伴的美食購物清單叢集。(*UI 僅供說明之用)

• 重新訂購叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的舊訂單預覽畫面，提示使用者重新訂購。系統只提供單一重新訂購叢集。

  • 重新訂購叢集必須顯示使用者舊訂單中的商品總數，且必須加入下列其中一項：

    • 使用者舊訂單中 X 個商品的圖片。
    • 使用者舊訂單中 X 個項目的標籤。

  

  圖：單一合作夥伴的美食重新訂購叢集。(*UI 僅供說明之用)

事前作業

最低 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 個	最多 25 個 (ProductEntity、RecipeEntity 或 StoreEntity)
精選叢集	最多 1 個	最多 10 個 (ProductEntity、RecipeEntity 或 StoreEntity)
美食購物車叢集	最多 1 個	最多 1 個 ShoppingCartEntity
美食購物清單叢集	最多 1 個	最多 1 個 ShoppingListEntity
美食重新訂購叢集	最多 1 個	最多 1 個 ReorderEntity

步驟 1：提供實體資料

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

1. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

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

ProductEntity

ProductEntity 物件代表開發合作夥伴要發布的個別項目 (例如雜貨項目、餐廳的餐點或促銷活動)。

圖： ProductEntity 的屬性

屬性	必要性	說明	格式
代表圖片	必要	至少須提供一張圖片	如需相關指南，請參閱「圖片規格」一節。
動作 URI	必要	應用程式中的頁面深層連結，可顯示產品相關詳細資料。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	選用	產品名稱	任意文字 建議文字長度：最多 90 個半形字元，過長部分會以刪節號顯示
價格 - 目前價格	在特定情況下為必要	產品目前的價格。 如果提供了原價，則必須提供這項屬性。	任意文字
價格 - 附帶刪除線	選用	實體的原始價格，在 UI 中會加上刪除線表示這個價格。	任意文字
摘要	選用	如果有，會是用來主打產品的促銷、活動或更新。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
摘要附屬細則	選用	摘要的附屬細則文字。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
評分 (選用) - 注意：所有評分都會透過我們的標準星級評等系統顯示。
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	產品的評分次數。 注意：如果應用程式會控制向使用者顯示的計數方式，請提供這個欄位。使用簡潔的字串。 舉例來說，如果計數為 1,000,000，建議使用 1M 等縮寫字，以免在較小的顯示大小中截斷計數。	字串
評分 - 次數值	選用	產品的評分次數。 注意：如果您不自行處理顯示縮寫邏輯，請提供這個欄位。如果同時有 Count 和 Count Value，系統會向使用者顯示 Count。	長
DisplayTimeWindow (選用) - 設定內容在途徑上顯示的時間長度
開始時間戳記	選用	Epoch 時間戳記，內容應會在此時間過後顯示在途徑上。 如未設定，表示內容一律會顯示在途徑上。	以毫秒為單位的 Epoch 時間戳記
結束時間戳記	選用	Epoch 時間戳記，內容在此時間後將不會顯示在途徑上。 如未設定，表示內容一律會顯示在途徑上。	以毫秒為單位的 Epoch 紀元時間戳記

StoreEntity

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

圖： StoreEntity 的屬性

屬性	必要性	說明	格式
代表圖片	必要	至少須提供一張圖片	如需相關指南，請參閱「圖片規格」一節。
動作 URI	必要	應用程式中的頁面深層連結，可顯示商店相關詳細資料。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	選用	商店名稱。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
位置	選用	商店的位置。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
摘要	選用	如果有，會是用來主打商店的促銷、活動或更新。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
摘要附屬細則	選用	摘要的附屬細則文字。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
說明	選用	商店說明。	任意文字 建議文字長度：最多 90 個半形字元，過長部分會以刪節號顯示
類別	選用	商店類別，在餐飲場所的情況下，可以是「法式」、「新美式」、「拉麵」、「高級餐飲」等菜系。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
注意：所有評分都會透過我們的標準星級評等系統顯示。
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	商店的評分次數。 注意：如果應用程式想控管向使用者顯示的方式，請提供這個欄位。提供可向使用者顯示的簡短字串。舉例來說，如果計數為 1,000,000，建議使用 1M 等縮寫字，以免在較小的顯示大小中遭到截斷。	字串
評分 - 次數值	選用	商店的評分次數。 注意：如果您不想自行處理顯示縮寫邏輯，請提供這個欄位。如果「Count」和「Count Value」都存在，我們會使用「Count」向使用者顯示	長

RecipeEntity

RecipeEntity 物件代表開發合作夥伴要發布的食譜項目。

圖： RecipeEntity 的屬性

屬性	必要性	說明	格式
代表圖片	必要	至少須提供一張圖片	如需相關指南，請參閱「圖片規格」一節。
動作 URI	必要	應用程式中的頁面深層連結，可顯示食譜相關詳細資訊。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
標題	選用	食譜名稱	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
作者	選用	食譜作者	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
烹調/準備時間	選用	食譜烹調時間	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
摘要	選用	如果有，會是用來主打食譜的宣傳、活動或更新。	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
類別	選用	食譜類別	任意文字 建議文字長度：最多 45 個半形字元，過長部分會以刪節號顯示
說明	選用	食譜說明	任意文字 建議文字長度：最多 90 個半形字元，過長部分會以刪節號顯示
注意：所有評分都會透過我們的標準星級評等系統顯示。
評分 - 最高值	選用	分級量表的最高值。 如果同時提供目前的評分值，則必須提供這項屬性。	大於或等於 0.0 的數字
評分 - 目前的值	選用	分級量表的目前值。 如果同時提供最高評分值，則須提供這項屬性。	大於或等於 0.0 的數字
評分 - 次數	選用	食譜的評分次數。 注意：如果應用程式想控管向使用者顯示的方式，請提供這個欄位。提供可向使用者顯示的簡短字串。舉例來說，如果計數為 1,000,000，建議使用 1M 等縮寫字，以免在較小的顯示大小中遭到截斷。	字串
評分 - 次數值	選用	食譜的評分次數。 注意：如果您不想自行處理顯示縮寫邏輯，請提供這個欄位。如果「Count」和「Count Value」都存在，我們會使用「Count」向使用者顯示	長

FoodShoppingCart

圖：美食購物車叢集屬性。

屬性	必要性	說明	格式
動作 URI	必要	合作夥伴應用程式中的購物車深層連結。 注意：您可以使用深層連結追蹤歸因。請參閱這篇常見問題文章	URI
項目數量	必要	購物車中的商品數量 (非僅指產品數量)。 舉例來說，如果購物車中有 3 顆柳丁和 1 顆蘋果，則這個數字應為 4。	大於或等於 1 的整數
標題	選用	購物車的標題 (例如「你的購物車」)。 如果開發人員未提供標題，系統預設會顯示「你的購物車」。	任意文字 建議文字長度：最多 25 個半形字元，過長部分會以刪節號顯示
動作文字	選用	購物車上按鈕的行動號召文字 (例如「你的購物袋」)。 如果開發人員未提供動作文字，系統會採用預設的「查看購物車」。 這個屬性適用於 1.1.0 以上版本。	字串
購物車圖片	選用	購物車中各項產品的圖片。 您最多可依優先順序提供 10 張圖片，實際顯示的圖片張數視裝置板型規格而定。	如需相關指南，請參閱「圖片規格」一節。
項目標籤	選用	購物清單中的項目標籤清單。 實際顯示的標籤數量視裝置板型規格而定。	任意文字標籤清單 建議文字長度：最多 20 個半形字元，過長部分會以刪節號顯示
DisplayTimeWindow (選用) - 設定內容在途徑上顯示的時間長度
開始時間戳記	選用	Epoch 時間戳記，內容應會在此時間過後顯示在途徑上。 如未設定，表示內容一律會顯示在途徑上。	以毫秒為單位的 Epoch 時間戳記
結束時間戳記	選用	Epoch 時間戳記，內容在此時間後將不會顯示在途徑上。 如未設定，表示內容一律會顯示在途徑上。	以毫秒為單位的 Epoch 紀元時間戳記

FoodShoppingList

圖：美食購物清單叢集。

屬性	必要性	說明	格式
動作 URI	必要	合作夥伴應用程式中的購物清單深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
項目數量	必要	購物清單中的項目數量。	大於或等於 1 的整數
標題	選用	清單的標題 (例如「你的雜貨清單」)。 如果開發人員未提供標題，系統會採用預設的「購物清單」。	任意文字 建議文字長度：最多 25 個半形字元，過長部分會以刪節號顯示
項目標籤	必要	購物清單中的項目標籤清單。 至少須提供 1 個標籤，最多可依優先順序提供 10 個標籤，實際顯示的標籤數量視裝置板型規格而定。	任意文字標籤清單 建議文字長度：最多 20 個半形字元，過長部分會以刪節號顯示

FoodReorderCluster

圖：美食重新訂購叢集。

屬性	必要性	說明	格式
動作 URI	必要	合作夥伴應用程式中的重新訂購深層連結。 注意：您可以使用深層連結追蹤歸因。 請參閱這篇常見問題文章	URI
動作文字	選用	「重新訂購」按鈕的行動號召文字 (例如「再次訂購」)。 如果開發人員未提供動作文字，系統會採用預設的「重新訂購」。 這個屬性適用於 1.1.0 以上版本。	字串
項目數量	必要	舊訂單中的項目數量，非僅指產品數量。 舉例來說，如果舊訂單中有 3 個小杯咖啡和 1 條可頌，則這個數字應為 4。	大於或等於 1 的整數
標題	必要	重新訂購項目的名稱。	任意文字 建議文字長度：最多 40 個半形字元，過長部分會以刪節號顯示
項目標籤	選用 (如未提供，則應提供代表圖片)	舊訂單的項目標籤清單。 您最多可依優先順序提供 10 個標籤，實際顯示的標籤數量視裝置板型規格而定。	任意文字清單 每個標籤的建議文字長度：最多 20 個半形字元，過長部分會以刪節號顯示
代表圖片	選用 (如未提供，則應提供項目標籤)	舊訂單中的項目圖片。 您最多可依優先順序提供 10 張圖片，實際顯示的圖片張數視裝置板型規格而定。	如需相關指南，請參閱「圖片規格」一節。

圖片規格

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

顯示比例	最低像素	建議的像素
正方形 (1x1) 建議採用	300x300	1200x1200
橫向 (1.91x1)	600x314	1200x628
直向 (4x5)	480x600	960x1200

檔案格式

PNG、JPG、靜態 GIF、WebP

檔案大小上限

5120 KB

其他建議

• 圖片安全區域：將重要內容放在圖片中央 80% 的範圍內。
• 使用透明背景，讓圖片正確顯示在深色和淺色主題設定中。

步驟 2：提供叢集資料

建議您在背景執行內容發布工作 (例如使用 WorkManager)，並安排定期執行或根據事件排程 (例如使用者每次開啟應用程式，或剛將商品加入購物車時)。

AppEngageFoodClient 負責發布美食叢集。

以下 API 可用於在用戶端發布叢集：

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

這個 API 可用於檢查服務是否可供整合，以及內容是否能在裝置上顯示。

KotlinJava

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.
    }
}

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

RecommendationCluster 物件可提供下列屬性：

屬性	必要性	說明
ProductEntity、StoreEntity 或 RecipeEntity 清單	必要	實體清單，組成這個推薦叢集的推薦項目。單一叢集中的實體必須屬於相同類型。
標題	必要	推薦叢集的標題 (例如「超值感恩節菜單」)。 建議文字長度：最多 25 個半形字元，過長部分會以刪節號顯示
副標題	選用	推薦叢集的副標題。
動作 URI	選用	合作夥伴應用程式中的頁面深層連結，可供使用者查看推薦項目完整清單。 注意：您可以使用深層連結追蹤歸因。請參閱這篇常見問題文章

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

KotlinJava

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .build())
                .build());

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

• 移除所有現有推薦叢集資料。
• 剖析要求所提供的資料並儲存在新的推薦叢集中。

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

publishFeaturedCluster

這個 API 可用來發布 FeaturedCluster 物件。

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

KotlinJava

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

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

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

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

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

publishFoodShoppingCart

這個 API 可用來發布 FoodShoppingCart 物件。

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

KotlinJava

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishFoodShoppingList

這個 API 可用來發布 FoodShoppingList 物件。

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

KotlinJava

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishReorderCluster

這個 API 可用來發布 FoodReorderCluster 物件。

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

KotlinJava

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishUserAccountManagementRequest

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

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

屬性	必要性	說明
動作 URI	必要	導向動作的深層連結，也就是前往應用程式登入頁面
圖片	選用 - 如未提供，則必須提供標題	資訊卡上顯示的圖片 解析度 1264x712、顯示比例 16x9 的圖片
標題	選用 - 如未提供，則必須提供圖片	資訊卡上的標題
動作文字	選用	行動號召中顯示的文字，也就是「登入」
副標題	選用	資訊卡上的選用副標題

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

KotlinJava

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

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。

KotlinJava

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

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

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

KotlinJava

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

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

deleteFeaturedCluster

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

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

KotlinJava

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

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

deleteFoodShoppingCartCluster

這個 API 可用來刪除美食購物車叢集的內容。

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

KotlinJava

client.deleteFoodShoppingCartCluster()

client.deleteFoodShoppingCartCluster();

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

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

deleteFoodShoppingListCluster

這個 API 可用來刪除美食購物清單叢集的內容。

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

KotlinJava

client.deleteFoodShoppingListCluster()

client.deleteFoodShoppingListCluster();

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

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

deleteReorderCluster

這個 API 可用於刪除 FoodReorderCluster 的內容。

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

KotlinJava

client.deleteReorderCluster()

client.deleteReorderCluster();

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

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

deleteUserManagementCluster

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

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

KotlinJava

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

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

deleteClusters

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

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

KotlinJava

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

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

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

處理錯誤

強烈建議您監聽來自發布 API 的工作結果，據以採取後續動作來復原及重新提交能順利執行的工作。

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

發生錯誤時會傳回 AppEngageException，並提供原因的錯誤代碼。

錯誤代碼	錯誤名稱	附註
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 類別的例項。這樣就能接收仍在記憶體中的應用程式訊息。

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 shopping cart cluster publish when PUBLISH_FOOD_SHOPPING_CART
// broadcast is received

// Trigger shopping list cluster publish when PUBLISH_FOOD_SHOPPING_LIST
// broadcast is received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER 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 Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_LIST));

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

}

• 在 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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER" />
      </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.food.PUBLISH_FOOD_SHOPPING_CART 建議在收到此意圖時啟動 publishFoodShoppingCart 呼叫。
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST 建議在收到此意圖時啟動 publishFoodShoppingList 呼叫。
• com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER 建議在收到此意圖時啟動 publishReorderCluster 呼叫。

整合工作流程

如需整合完成後驗證作業的逐步指南，請參閱「Engage 開發人員整合工作流程」一文。

常見問題

請參閱「Engage SDK 常見問題」。

聯絡資訊

如果在整合過程中有任何問題，請來信至 [e-mail] 與我們聯絡。我們的團隊會盡快回覆。

後續步驟

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

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