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

Google 正在建構的裝置端途徑會依產業別將使用者的應用程式分門別類，並提供全新沉浸式體驗，可供使用者取用及瀏覽個人化應用程式內容。開發合作夥伴可以利用這個全螢幕體驗，在應用程式以外的專屬管道展示最精彩的多媒體內容。本指南適用對象為開發合作夥伴，提供透過 Engage SDK 填入這個新途徑區域的操作說明，整合健康與健身內容。

整合詳情

術語

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

• 「推薦」叢集會顯示個別開發合作夥伴提供的個人化健康與健身建議。這些推薦可以根據使用者的個人需求提供，或是一般化 (例如流行的健身和健康建議)。您可以使用這些推薦內容，顯示有關健康和健身內容的文章或人物。

  • 推薦叢集可由 ArticleEntity、PersonEntity 或 EventEntity 組成，但不能混合不同實體類型的組合。

  推薦內容採用以下結構：

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

  • 實體：代表叢集中單一項目的物件。這項整合提供部分可透過推薦叢集顯示的實體：

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

      

    • PersonEntity：PersonEntity 代表個人。這些建議可以主打教練或是任何與健康和健身有關的個人。

      

    • EventEntity：EventEntity 代表未來發生的事件。事件開始時間是需要傳達給使用者的重要資訊。此實體可用於顯示與健康和健身相關的活動，例如血流捐、訓練課程、健身房或瑜伽課程等。

      

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

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

  • ArticleEntity：ArticleEntity 是針對健康與健身相關文字內容的建議。這個實體可用於代表未看完的新聞報導，或是使用者想從離開頁面繼續瀏覽的其他內容。例如：與健康或健身相關主題的新聞摘要和網誌文章片段。

    

  • EventReservationEntity：EventReservationEntity 代表活動的預訂，並協助使用者追蹤近期或正在進行的健身和健康事件預留項目。例如：訓練課程

    

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

  • 一般精選實體：泛型精選實體應與推薦項目不同，應用於開發人員提供的單一熱門內容，且應代表使用者會感興趣的最重要內容。

    

事前作業

最低 API 級別：19

將 com.google.android.play:engage 程式庫新增至應用程式：

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.4.1'
}

摘要

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

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

步驟 1：提供實體資料

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

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

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

GenericFeaturedEntity

ArticleEntity

PersonEntity

EventEntity

EventReservationEntity

圖片規格

下表列出圖片素材資源的規格規定：

圖片必須在公開 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 和 GenericGenericEntity) 符合使用任何內容類別的資格。至於 EventEntity、EventReservationEntity 和 PersonEntity 等其他實體，則只有這些類別的子集符合資格。請先查看適用於特定實體類型的類別清單，再填入清單。

2. 針對某些內容類別，而非一般實體和 ContentCategory 的組合，請使用特定實體類型：

   • TYPE_BOOKS_AND_TV_SHOWS - 請先參閱「手錶整合指南」中的實體，再使用一般實體。
   • 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 可用於檢查服務是否可供整合，以及內容是否能在裝置上顯示。

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

publishRecommendationClusters

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

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

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

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

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

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

publishContinuationCluster

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

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

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

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

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

publishUserAccountManagementRequest

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

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

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。

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteContinuationCluster

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

client.deleteContinuationCluster()

client.deleteContinuationCluster();

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

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

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

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

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

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

處理錯誤

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

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

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

步驟 3：處理廣播意圖

除了透過工作發出發布內容 API 呼叫，您還需要設定 BroadcastReceiver 來接收內容發布要求。

廣播意圖的目標主要用於應用程式重新啟動及強制同步處理資料。廣播意圖的傳送頻率通常不高。觸發廣播意圖的唯一時機，就是 Engage Service 判定內容可能過時 (例如已滿一週)。這樣一來，即使應用程式已有長時間未執行，使用者也能獲得最新的內容體驗。

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

• 使用 Context.registerReceiver() 以動態方式註冊 BroadcastReceiver 類別的例項。這樣就能接收仍在記憶體中的應用程式訊息。

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

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

聯絡資訊

如果在整合過程中有任何問題，請來信至 engage-developers@google.com 與我們聯絡。

後續步驟

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

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