Engage SDK Shopping:第三方技術整合操作說明

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

本指南適用對象為開發合作夥伴,針對透過 Engage SDK 填入此新途徑區域和 Entertainment Space 等現有 Google 途徑的情況,提供整合購物內容的操作說明。

整合詳情

術語

這項整合包含以下五個叢集類型:推薦精選購物車購物清單重新訂購購物訂單追蹤

  • 「推薦」叢集會顯示個別開發合作夥伴提供的個人化購物建議。推薦內容可以根據使用者的個人需求提供,或是一般項目 (例如熱門項目)。您可以使用這些推薦內容,顯示合適的產品、活動、特價、促銷、訂閱等項目。

    推薦內容採用以下結構:

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

    • ShoppingEntity:代表叢集中單一項目的物件。

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

  • 「購物車」叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的購物車預覽畫面,提醒使用者完成購物車流程。這個單一購物車叢集會顯示在靠近 UI 頂端的位置,並且優先放置在所有推薦叢集的上方。每個開發合作夥伴最多可在購物車叢集中播送 3 個 ShoppingCart 例項。

    購物車採用以下結構:

    • 購物車叢集:此 UI 檢視畫面包含多個開發合作夥伴提供的一組購物車預覽畫面。

    • ShoppingCart:此物件代表單一開發合作夥伴的購物車預覽畫面,會顯示在購物車叢集中。ShoppingCart 必須顯示購物車中的項目總數,也可以加入使用者購物車中部分項目的圖片。

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

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

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

      • 使用者舊訂單中 X 個商品的圖片。
      • 使用者舊訂單中 X 個項目的標籤。
  • 「購物訂單追蹤」叢集會在一個 UI 群組中顯示多個開發合作夥伴提供的待處理或最近完成的購物訂單預覽畫面,方便使用者追蹤訂單。

    這個單一購物訂單追蹤叢集會顯示在靠近 UI 頂端的位置,並且優先放置在所有推薦叢集的上方。每個開發合作夥伴可在購物訂單追蹤叢集中播送多個 ShoppingOrderTrackingEntity 項目。

    • ShoppingOrderTrackingCluster 採用以下結構:

      • 購物訂單追蹤叢集:此 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 個 最多 10 個 ShoppingEntity
購物車叢集 最多 1 個 最多 3 個 ShoppingCart

只有在應用程式中每個商家都有個別購物車的情況下,才會預期有多個購物車。

購物清單叢集 最多 1 個 最多 1 個 ShoppingListEntity
購物重新訂購叢集 最多 1 個 最多 1 個 ReorderEntity
購物訂單追蹤叢集 最多 3 個 最多 3 個 ShoppingOrderTrackingEntity

步驟 1:提供實體資料

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

  1. ShoppingEntity
  2. ShoppingCart
  3. ShoppingList
  4. Reorder
  5. ShoppingOrderTracking

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

ShoppingEntity

ShoppingEntity 物件代表開發合作夥伴要發布的產品、促銷、特惠、訂閱或活動。

ShoppingEntity
屬性 必要性 說明 格式
代表圖片 必要 至少須提供一張圖片 如需相關指南,請參閱「圖片規格」一節。
動作 URI 必要

應用程式中的頁面深層連結,可顯示實體相關詳細資料。

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

URI
標題 選用 實體的名稱。

任意文字

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

價格 - 目前價格 在特定情況下為必要

實體目前的價格。

如果提供了附帶刪除線的價格,則必須提供這項屬性。

任意文字
價格 - 附帶刪除線 選用 實體的原始價格,在 UI 中會加上刪除線表示這個價格。 任意文字
摘要 選用 如果有,會是用來主打該實體的宣傳、活動或更新。

任意文字

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

摘要附屬細則 選用 摘要的附屬細則文字。

任意文字

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

評分 (選用) - 注意:所有評分都會透過我們的標準星級評等系統顯示。
評分 - 最高值 選用

分級量表的最高值。

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

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

目前分級量表的值。

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

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

實體的評分次數。

注意:如果應用程式會控制向使用者顯示的計數方式,請提供這個欄位。使用簡潔的字串。舉例來說,如果計數為 1,000,000,建議使用 1M 等縮寫字,以免在較小的顯示大小下截斷計數。

字串
評分 - 次數值 選用

實體的評分次數。

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

DisplayTimeWindow (選用) - 設定內容在途徑上顯示的時間長度
開始時間戳記 選用

Epoch 時間戳記,內容應會在此時間過後顯示在途徑上。

如未設定,表示內容一律會顯示在途徑上。

以毫秒為單位的 Epoch 時間戳記
結束時間戳記 選用

Epoch 時間戳記,內容在此時間後將不會顯示在途徑上。

如未設定,表示內容一律會顯示在途徑上。

以毫秒為單位的 Epoch 時間戳記

ShoppingCart

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

合作夥伴應用程式中的購物車深層連結。

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

URI
項目數量 必要

購物車中的項目數量,非僅指產品數量。

舉例來說,如果購物車中有 3 件相同的襯衫和 1 頂帽子,則這個數字應為 4。

大於或等於 1 的整數
動作文字 選用

購物車上按鈕的行動號召文字 (例如「你的購物袋」)。

如果開發人員未提供動作文字,系統會採用預設的「查看購物車」

這個屬性適用於 1.1.0 以上版本。

字串
標題 選用

購物車的標題 (例如「你的購物袋」)。

如果開發人員未提供標題,系統預設會顯示「你的購物車」

如果開發合作夥伴為每個商家發布獨立的購物車,請在標題中加入商家名稱

任意文字

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

購物車圖片 選用

購物車中各項產品的圖片。

您最多可依優先順序提供 10 張圖片,實際顯示的圖片張數視裝置板型規格而定。

如需相關指南,請參閱「圖片規格」一節。
項目標籤 選用

購物清單中的項目標籤清單。

實際顯示的標籤數量視裝置板型規格而定。

任意文字標籤清單

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

上次使用者互動時間戳記 選用 自紀元起經過的毫秒數,可識別使用者上次與購物車互動的時間。

開發合作夥伴會將這項資訊做為輸入內容,為每個商家發布個別購物車,並可能用於排名。

以毫秒為單位的 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 - End Time 選用

以毫秒為單位的 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 物件。這適用於開發合作夥伴為每個商家發布個別購物車的情況。使用此 API 時,請在標題中加入商家名稱。

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,並提供原因的錯誤代碼。

錯誤代碼 錯誤名稱 附註
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 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 常見問題」。

聯絡資訊

如果在整合過程中有任何問題,請來信至 engage-developers@google.com 與我們聯絡。我們的團隊會盡快回覆。

後續步驟

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

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