Google 正在建構的裝置端途徑會依產業別將使用者的應用程式分門別類,並提供全新沉浸式體驗,可供使用者取用及瀏覽個人化應用程式內容。開發合作夥伴可以利用這個全螢幕體驗,在應用程式以外的專屬管道展示最精彩的多媒體內容。
本指南適用對象為開發合作夥伴,針對透過 Engage SDK 填入此新途徑區域和 Entertainment Space 等現有 Google 途徑的情況,提供整合購物內容的操作說明。
整合詳情
術語
這項整合包含以下五個叢集類型:推薦、 精選、購物車、購物清單、重新訂購和 購物訂單追蹤:
「推薦」叢集會顯示個別開發合作夥伴提供的個人化購物建議。推薦內容可以根據使用者的個人需求提供,或是一般項目 (例如熱門項目)。您可以使用這些推薦內容,顯示合適的產品、活動、特價、促銷、訂閱等項目。
推薦內容採用以下結構:
推薦叢集:此 UI 檢視畫面包含相同開發合作夥伴提供的一組推薦內容。
ShoppingEntity:代表叢集中單一項目的物件。
「精選」叢集會在一個 UI 群組中展示多個開發合作夥伴提供的精選主打
ShoppingEntity
。這個單一精選叢集會顯示在靠近 UI 頂端的位置,並且優先放置在所有推薦叢集的上方。每個開發合作夥伴都可在精選叢集中發布單一 ShoppingEntity。「購物車」叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的購物車預覽畫面,提醒使用者完成購物車流程。這個單一購物車叢集會顯示在靠近 UI 頂端的位置,並且優先放置在所有推薦叢集的上方。每個開發合作夥伴最多可以播送 購物車叢集中有 3 個「
ShoppingCart
」執行個體。購物車採用以下結構:
購物車叢集:此 UI 檢視畫面包含多個開發合作夥伴提供的一組購物車預覽畫面。
ShoppingCart:此物件代表單一開發合作夥伴的購物車預覽畫面,會顯示在購物車叢集中。
ShoppingCart
必須顯示購物車中的項目總數,也可以加入使用者購物車中部分項目的圖片。
購物清單叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的購物清單預覽畫面,提示使用者返回對應的應用程式更新並完成清單。系統只提供單一購物清單叢集。
重新訂購叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的舊訂單預覽畫面,提示使用者重新訂購。系統只提供單一重新訂購叢集。
重新訂購叢集必須顯示使用者舊訂單中的商品總數,且必須加入下列其中一項:
- 使用者舊訂單中 X 個商品的圖片。
- 使用者舊訂單中 X 個項目的標籤。
「購物訂單追蹤」叢集會顯示「待處理」的預覽畫面 或最近多家開發合作夥伴透過單一使用者介面完成的購物訂單 以便追蹤訂單。
頁面上只會列出一個 ShoppingOrderTracking 叢集 在 UI 頂端附近,並且優先放置在所有最佳化建議上方 叢集內每個開發合作夥伴都可廣播多個 購物訂單追蹤叢集內的 ShoppingOrderTrackingEntity 項目。
ShoppingOrderTrackingCluster 採用以下結構:
- ShoppingOrderTracking 叢集:包含一組群組的 UI 檢視畫面 多個開發合作夥伴提供的訂單追蹤預覽畫面
- ShoppingOrderTrackingEntity:代表購物訂單的物件 單一開發合作夥伴的追蹤預覽畫面,以顯示 購物訂單追蹤叢集。ShoppingOrderTrackingEntity 必須顯示 訂單狀態和訂單時間。強烈建議你 填入 ShoppingOrderTrackingEntity 的預計送達時間,例如 有提供時即會向使用者顯示。
事前作業
最低 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'
}
詳情請參閱「Android 11 套件瀏覽權限」一文。
摘要
這項設計是以繫結服務的實作為基礎。
用戶端可發布的資料受到不同叢集類型的限制,如下所示:
叢集類型 | 叢集限制 | 單一叢集中的實體數量上限 |
---|---|---|
推薦叢集 | 最多 5 個 | 最多 25 個 ShoppingEntity |
精選叢集 | 最多 1 個 | 最多 1 個 ShoppingEntity |
購物車叢集 | 最多 1 個 | 最多 3 個 ShoppingCart
只有每個商家針對個別購物車的應用程式需要提供多個購物車。 |
購物清單叢集 | 最多 1 個 | 最多 1 個 ShoppingListEntity |
購物重新訂購叢集 | 最多 1 個 | 最多 1 個 ReorderEntity |
購物訂單追蹤叢集 | 最多 3 個 | 最多 3 個 ShoppingOrderTrackingEntity |
步驟 1:提供實體資料
SDK 定義了不同實體,用來代表各種項目類型。Shopping 類別支援下列實體:
ShoppingEntity
ShoppingCart
ShoppingList
Reorder
ShoppingOrderTracking
下方圖表列出各類型的可用屬性和必要性。
ShoppingEntity
ShoppingEntity
物件代表產品、促銷、特惠、訂閱、
設定事件或事件名稱
ShoppingEntity
屬性 | 必要性 | 說明 | 格式 |
---|---|---|---|
代表圖片 | 必要 | 至少須提供一張圖片 | 如需相關指南,請參閱「圖片規格」一節。 |
動作 URI | 必要 |
應用程式中的頁面深層連結,可顯示實體相關詳細資料。 注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題 |
URI |
標題 | 選用 | 實體的名稱。 | 任意文字 建議文字長度:最多 90 個半形字元,過長部分會以刪節號顯示 |
價格 - 目前價格 | 在特定情況下為必要 |
實體目前的價格。 如果提供了附帶刪除線的價格,則必須提供這項屬性。 |
任意文字 |
價格 - 附帶刪除線 | 選用 | 實體的原始價格,在 UI 中會加上刪除線表示這個價格。 | 任意文字 |
摘要 | 選用 | 如果有,會是用來主打該實體的宣傳、活動或更新。 | 任意文字 建議文字長度:最多 45 個半形字元,過長部分會以刪節號顯示 |
摘要附屬細則 | 選用 | 摘要的附屬細則文字。 | 任意文字 建議文字長度:最多 45 個半形字元,過長部分會以刪節號顯示 |
評分 (選用) - 注意:所有評分都會透過我們的標準星級評等系統顯示。 | |||
評分 - 最高值 | 選用 | 分級量表的最高值。 如果同時提供目前的評分值,則必須提供這項屬性。 |
大於或等於 0.0 的數字 |
評分 - 目前的值 | 選用 | 目前分級量表的值。 如果同時提供最高評分值,則須提供這項屬性。 |
大於或等於 0.0 的數字 |
評分 - 計算 | 選用 |
實體的評分次數。 注意:如果您的應用程式含有應用程式,請提供這個欄位 控制向使用者顯示的次數。使用精簡的字串。 舉例來說,如果計數是 1,000,000,請考慮使用縮寫 以免在螢幕較小的情況下遭到截斷 |
字串 |
評分 - 計數值 | 選用 | 實體的評分次數。 注意:如果您不處理訂單,請提供這個欄位 顯示縮寫邏輯如果同時包含次數和計數值 系統會向使用者顯示計數。 |
長 |
DisplayTimeWindow (選用) - 設定內容在途徑上顯示的時間長度 | |||
開始時間戳記 | 選用 |
Epoch 時間戳記,內容應會在此時間過後顯示在途徑上。 如未設定,表示內容一律會顯示在途徑上。 |
以毫秒為單位的 Epoch 時間戳記 |
結束時間戳記 | 選用 |
Epoch 時間戳記,內容在此時間後將不再顯示 表面。 如未設定,表示內容一律會顯示在途徑上。 |
以毫秒為單位的 Epoch 時間戳記 |
ShoppingCart
屬性 | 必要性 | 說明 | 格式 |
---|---|---|---|
動作 URI | 必要 |
合作夥伴應用程式中的購物車深層連結。 注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題 |
URI |
項目數量 | 必要 |
購物車中的項目數量,非僅指產品數量。 舉例來說,如果購物車中有 3 件相同的襯衫和 1 頂帽子, 這個數字應為 4 |
大於或等於 1 的整數 |
動作文字 | 選用 |
購物車上按鈕的行動號召文字 (例如「你的購物袋」)。 如果開發人員未提供動作文字, 「查看購物車」為預設選項。 這個屬性適用於 1.1.0 以上版本。 |
字串 |
標題 | 選用 | 購物車的標題 (例如「你的購物袋」)。 如果開發人員未提供標題,系統預設會顯示「你的購物車」。 如果開發合作夥伴為每個商家發布個別購物車, 請在標題中加入商家名稱。 |
任意文字 建議文字長度:最多 25 個半形字元,過長部分會以刪節號顯示 |
購物車圖片 | 選用 | 購物車中各項產品的圖片。 您最多可依優先順序提供 10 張圖片,實際顯示的圖片張數視裝置板型規格而定。 |
如需相關指南,請參閱「圖片規格」一節。 |
項目標籤 | 選用 | 購物清單中的項目標籤清單。 實際顯示的標籤數量視裝置板型規格而定。 |
任意文字標籤清單 建議文字長度:最多 20 個半形字元,過長部分會以刪節號顯示 |
上次使用者互動時間戳記 | 選用 | 從 Epoch 紀元時間起算的毫秒數,可識別上一個時間。
就會引發這個事件。
這項資訊會做為 開發合作夥伴會為每個商家發布不同的購物車,且或許會使用 以便進行排名 |
以毫秒為單位的 Epoch 紀元時間戳記 |
DisplayTimeWindow (選用) - 設定內容在途徑上顯示的時間長度 | |||
開始時間戳記 | 選用 |
Epoch 時間戳記,內容應會在此時間過後顯示在途徑上。 如未設定,表示內容一律會顯示在途徑上。 |
以毫秒為單位的 Epoch 時間戳記 |
結束時間戳記 | 選用 |
Epoch 時間戳記,內容在此時間後將不再顯示 表面。 如未設定,表示內容一律會顯示在途徑上。 |
以毫秒為單位的 Epoch 時間戳記 |
ShoppingList
屬性 | 必要性 | 說明 | 格式 |
---|---|---|---|
動作 URI | 必要 |
合作夥伴應用程式中的購物清單深層連結。 注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題 |
URI |
項目數量 | 必要 | 購物清單中的項目數量。 | 大於或等於 1 的整數 |
標題 | 選用 |
清單的標題 (例如「你的雜貨清單」)。 如果開發人員未提供標題, 「購物清單」為預設選項。 |
任意文字 建議文字長度:最多 25 個半形字元,過長部分會以刪節號顯示 |
項目標籤 | 必要 | 購物清單中的項目標籤清單。 至少須提供 1 個標籤,最多可依優先順序提供 10 個標籤,實際顯示的標籤數量視裝置板型規格而定。 |
任意文字標籤清單 建議文字長度:最多 20 個半形字元,過長部分會以刪節號顯示 |
ShoppingReorderCluster
屬性 | 必要性 | 說明 | 格式 |
---|---|---|---|
動作 URI | 必要 |
合作夥伴應用程式中的重新訂購深層連結。 注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題 |
URI |
動作文字 | 選用 |
「重新訂購」按鈕的行動號召文字 (例如 再次訂購)。 如果開發人員未提供動作文字, 預設值為「重新訂購」。 這個屬性適用於 1.1.0 以上版本。 |
字串 |
項目數量 | 必要 |
舊帳戶中的項目數量,非僅指產品數量 順序。 舉例來說,假設網站上有 3 個小咖啡和 1 條可頌 舊訂單,這個數字應為 4。 |
大於或等於 1 的整數 |
標題 | 必要 | 重新訂購項目的名稱。 | 任意文字 建議文字長度:最多 40 個半形字元,過長部分會以刪節號顯示 |
項目標籤 | 選用 (如未提供,則應提供代表圖片) |
舊訂單的項目標籤清單。 您最多可依優先順序提供 10 個標籤,實際顯示的標籤數量視裝置板型規格而定。 |
任意文字清單 每個標籤的建議文字大小:最多 20 個半形字元 (過長的文字可能會以刪節號顯示) |
代表圖片 | 選用 (如未提供,則應提供項目標籤) |
舊訂單中的項目圖片。 您最多可依優先順序提供 10 張圖片,實際顯示的圖片張數視裝置板型規格而定。 |
如需相關指南,請參閱「圖片規格」一節。 |
ShoppingOrderTrackingCluster
屬性 | 必要性 | 說明 | 格式 |
---|---|---|---|
標題 | 必要 |
描述所追蹤包裹/商品或追蹤項目的簡短標題 號碼。 |
任意文字 建議文字長度:50 個半形字元 (文字過長, 顯示刪節號) |
訂單類型 | 必要 |
描述所追蹤包裹/商品或追蹤項目的簡短標題 號碼。 |
例如:IN_STORE_PICKUP、SAME_DAY_DELIVERY、MULTI_DAY_DELIVERY |
狀態 | 必要 |
訂單目前的狀態。 例如:「遲交」、「運送中」、「延遲」。 「已出貨」、「已送達」、「缺貨中」、「訂單就緒」 |
任意文字 建議文字長度:25 個半形字元 (文字過長, 顯示刪節號) |
訂單時間 | 必要 |
下單時的 Epoch 時間戳記,以毫秒為單位。 如果商品預計送達時間,就會顯示訂單時間 不存在 |
以毫秒為單位的 Epoch 紀元時間戳記 |
動作 URI | 必要 |
合作夥伴應用程式中的訂單追蹤深層連結。 |
URI |
OrderDeliveryTimeWindow (選填) - 設定時間 回溯期 (從下單時起算) 發生在預計/實際交付時間的產品 | |||
OrderDeliveryTimeWindow - 開始時間 | 選用 |
以毫秒為單位的 Epoch 時間戳記, 已送達或可供取貨 |
以毫秒為單位的 Epoch 紀元時間戳記 |
OrderDeliveryTimeWindow - 結束時間 | 選用 |
建立訂單的 Epoch 時間戳記,以毫秒為單位或早於訂單的發生時間 已送達或可供取貨 |
以毫秒為單位的 Epoch 紀元時間戳記 |
代表圖片 | 選用 | 包含在訂單中一項商品/產品的圖片。 建議顯示比例為 1:1 |
如需相關指南,請參閱「圖片規格」一節。 |
項目數量 | 選用 | 訂單中的項目數量。 | 大於或等於 1 的整數 |
說明 | 選用 | 用一段文字描述訂單中的項目。 注意:說明和字幕清單將會顯示 只會向使用者顯示 |
任意文字 建議文字長度:180 個半形字元 |
字幕清單 | 選用 | 最多 3 則字幕,每行文字各一行。 注意:說明和字幕清單將會顯示 只會向使用者顯示 |
任意文字 每個字幕的建議文字大小:上限 50 個半形字元 |
訂單價值 - 目前價格 | 選用 | 訂單目前的值。 | 任意文字 |
訂單號碼 | 選用 | 可用來識別訂單的訂單號碼/ID。 |
任意文字 建議文字長度:最多 25 個半形字元 |
追蹤號碼 | 選用 | 訂單/包裹運送的追蹤號碼,以便在訂單時使用 需要提交內容 |
任意文字 建議文字長度:最多 25 個半形字元 |
圖片規格
圖片素材資源的規格規定如下:
顯示比例 | 最低像素 | 建議的像素 |
---|---|---|
正方形 (1x1) 建議用於非精選叢集 |
300x300 | 1200x1200 |
橫向 (1.91x1) 建議用於精選叢集 |
600x314 | 1200x628 |
直向 (4x5) | 480x600 | 960x1200 |
檔案格式
PNG、JPG、靜態 GIF、WebP
檔案大小上限
5120 KB
其他建議
- 圖片安全區域:將重要內容放在圖片中央 80% 的範圍內。
- 使用透明背景,讓圖片正確顯示在深色和淺色主題設定中。
步驟 2:提供叢集資料
建議您在背景執行內容發布工作 (例如使用 WorkManager),並安排定期執行或根據事件排程 (例如使用者每次開啟應用程式,或剛將商品加入購物車時)。
AppEngageShoppingClient
負責發布購物叢集。
以下 API 可公開用於在用戶端中發布叢集:
isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishShoppingCart
publishShoppingCarts
publishShoppingList
publishShoppingReorderCluster
publishShoppingOrderTrackingCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteShoppingCartCluster
deleteShoppingListCluster
deleteShoppingReorderCluster
deleteShoppingOrderTrackingCluster
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
物件清單。
RecommendationCluster
物件可提供下列屬性:
屬性 | 必要性 | 說明 |
---|---|---|
ShoppingEntity 清單 | 必要 | ShoppingEntity 物件清單,組成這個推薦叢集的推薦項目。 |
標題 | 必要 | 推薦叢集的標題。 建議文字長度:最多 25 個半形字元,過長部分會以刪節號顯示 |
副標題 | 選用 | 推薦叢集的子標題。 |
動作 URI | 選用 |
合作夥伴應用程式中的頁面深層連結,可供使用者查看推薦項目完整清單。 注意:您可以使用深層連結追蹤歸因。 請參閱這篇常見問題 |
Kotlin
client.publishRecommendationClusters( PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Black Friday Deals") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Black Friday Deals") .build()) .build());
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除所有現有推薦叢集資料。
- 剖析要求所提供的資料並儲存在新的推薦叢集中。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
publishFeaturedCluster
這個 API 可用來發布 FeaturedCluster
物件。
Kotlin
client.publishFeaturedCluster( PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( FeaturedCluster.Builder() ... .build()) .build())
Java
client.publishFeaturedCluster( new PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( new FeaturedCluster.Builder() ... .build()) .build());
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
FeaturedCluster
資料。 - 剖析要求所提供的資料並儲存在更新後的精選叢集中。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
publishShoppingCart
這個 API 可用來發布 ShoppingCartCluster
物件。
Kotlin
client.publishShoppingCart( PublishShoppingCartRequest.Builder() .setShoppingCart( ShoppingCart.Builder() ... .build()) .build())
Java
client.publishShoppingCart( new PublishShoppingCartRequest.Builder() .setShoppingCart( new ShoppingCart.Builder() ... .build()) .build())
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
ShoppingCart
資料。 - 剖析要求所提供的資料並儲存在更新後的購物車叢集中。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
publishShoppingCarts
這個 API 可用來發布多個 ShoppingCart
物件。這是
適用於開發合作夥伴;根據個別商家發布個別購物車。包含
商家名稱。
Kotlin
client.publishShoppingCarts( PublishShoppingCartClustersRequest.Builder() .addShoppingCart( ShoppingCart.Builder() ... .build()) .build())
Java
client.publishShoppingCarts( new PublishShoppingCartClustersRequest.Builder() .addShoppingCart( new ShoppingCart.Builder() ... .build()) .build())
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
ShoppingCart
資料。 - 剖析要求所提供的資料並儲存在更新後的購物車叢集中。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
publishShoppingList
這個 API 可用來發布 FoodShoppingList
物件。
Kotlin
client.publishFoodShoppingList( PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( FoodShoppingListEntity.Builder() ... .build()) .build())
Java
client.publishFoodShoppingList( new PublishFoodShoppingListRequest.Builder() .setFoodShoppingList( new FoodShoppingListEntity.Builder() ... .build()) .build());
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
FoodShoppingList
資料。 - 剖析要求所提供的資料並儲存在更新後的購物清單叢集中。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
publishShoppingReorderCluster
這個 API 可用來發布 ShoppingReorderCluster
物件。
Kotlin
client.publishShoppingReorderCluster( PublishShoppingReorderClusterRequest.Builder() .setReorderCluster( ShoppingReorderCluster.Builder() ... .build()) .build())
Java
client.publishShoppingReorderCluster( new PublishShoppingReorderClusterRequest.Builder() .setReorderCluster( new ShoppingReorderCluster.Builder() ... .build()) .build());
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
ShoppingReorderCluster
資料。 - 剖析要求所提供的資料並儲存在更新後的重新訂購叢集中。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
publishShoppingOrderTrackingCluster
這個 API 可用來發布 ShoppingOrderTrackingCluster
物件。
Kotlin
client.publishShoppingOrderTrackingCluster( PublishShoppingOrderTrackingClusterRequest.Builder() .setShoppingOrderTrackingCluster( ShoppingOrderTrackingCluster.Builder() ... .build()) .build())
Java
client.publishShoppingOrderTrackingCluster( new PublishShoppingOrderTrackingClusterRequest.Builder() .setShoppingOrderTrackingCluster( new ShoppingOrderTrackingCluster.Builder() ... .build()) .build());
服務收到要求後,系統會在單一交易中執行以下動作:
- 移除開發合作夥伴提供的現有
ShoppingOrderTrackingCluster
資料。 - 剖析要求所提供的資料並儲存在更新後的購物訂單中 追蹤叢集。
如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
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();
服務收到要求後,會從精選叢集中移除現有資料。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
deleteShoppingCartCluster
這個 API 可用來刪除購物車叢集的內容。
Kotlin
client.deleteShoppingCartCluster()
Java
client.deleteShoppingCartCluster();
服務收到要求後,會從購物車叢集中移除現有資料。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
deleteShoppingListCluster
這個 API 可用來刪除購物清單叢集的內容。
Kotlin
client.deleteShoppingListCluster()
Java
client.deleteShoppingListCluster();
服務收到要求後,會從購物清單叢集中移除現有資料。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
deleteShoppingReorderCluster
這個 API 可用來刪除購物重新訂購叢集的內容。
Kotlin
client.deleteShoppingReorderCluster()
Java
client.deleteShoppingReorderCluster();
服務收到要求後,會從購物重新訂購叢集中移除現有資料。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
deleteShoppingOrderTrackingCluster
這個 API 可用來刪除購物訂單追蹤叢集的內容。
Kotlin
client.deleteShoppingOrderTrackingCluster()
Java
client.deleteShoppingOrderTrackingCluster();
服務收到要求後,會從 購物訂單追蹤叢集。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
deleteUserManagementCluster
這個 API 可用來刪除 UserAccountManagement 叢集的內容。
Kotlin
client.deleteUserManagementCluster()
Java
client.deleteUserManagementCluster();
服務收到要求後,會從 UserAccountManagement 叢集中移除現有資料。如果發生錯誤,整個要求都會遭到拒絕,現有狀態則維持不變。
deleteClusters
這個 API 可用於刪除指定叢集類型的內容。
Kotlin
client.deleteClusters( DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) ... .build())
Java
client.deleteClusters( new DeleteClustersRequest.Builder() .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
,並提供原因的錯誤代碼。
錯誤代碼 | 附註 |
---|---|
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 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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast // is received // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast // is received // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is // received // Trigger shopping order tracking cluster publish when // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER 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 Shopping Cart Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART)) // Register Shopping List Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST)) // Register Reorder Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER)) // Register Shopping Order Tracking Cluster Publish Intent context.registerReceiver(AppEngageBroadcastReceiver(), IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER)) }
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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is // received // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is // received // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is // received // Trigger reorder cluster publish when PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART)); // Register Shopping List Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST)); // Register Reorder Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER)); // Register Shopping Order Tracking Cluster Publish Intent context.registerReceiver(new AppEngageBroadcastReceiver(), new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.PUBLISH_SHOPPING_CART" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
</intent-filter>
<intent-filter>
<action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_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.shopping.PUBLISH_SHOPPING_CART
建議在收到此意圖時啟動publishShoppingCart
呼叫。com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST
建議在收到此意圖時啟動publishShoppingList
呼叫。com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER
建議在收到此意圖時啟動publishReorderCluster
呼叫。com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER
建議您在以下時間啟動publishShoppingOrderTrackingCluster
呼叫: 才會收到意圖
整合工作流程
如需整合完成後驗證作業的逐步指南,請參閱「Engage 開發人員整合工作流程」一文。
常見問題
請參閱「Engage SDK 常見問題」。
聯絡資訊
聯絡 [email protected] 都會遇到任何問題我們的團隊會盡快回覆。
後續步驟
完成這項整合後,後續步驟如下:
- 傳送電子郵件至 [email protected],並附上整合完成可供 Google 測試的 APK。
- Google 會在內部執行驗證及審查,確認整合項目能夠正常運作。如果需要進行變更,Google 會與您聯絡並提供所有必要詳細資料。
- 測試完成後,如果不需要進行任何變更,Google 會與您聯絡,通知您可以開始將完成整合的更新版 APK 發布至 Play 商店。
- Google 確認您已將更新版 APK 發布至 Play 商店、您的推薦、精選、購物車 購物清單、重新訂購叢集和購物訂單追蹤叢集 叢集則會發布,並對使用者顯示