Engage SDK Codelab

1. 简介

上次更新日期:2025 年 5 月 14 日

什么是 Engage SDK?

Engage SDK 可将个性化的应用内容呈现在用户所在的多种设备端 Google 展示途径上,进而帮助提升您应用的用户互动度。借助 Engage SDK,您的应用可以向已安装应用的用户提供个性化的(1 对 1)推荐内容和接续内容,从而在用户打开应用之前就吸引他们。

内容展示途径

集合

Entertainment Space

Play 商店 (即将推出)

借助全新的 Play 商店微件,可将您的内容直接呈现在用户的设备主屏幕上。

在特定 Android 平板电脑上为娱乐内容创建新的接触点。

更多展示途径即将开放,今年夏天从 Play 商店开启。

构建内容

完成此 Codelab 后,您将拥有一个能够将内容发送到 Google 展示途径的 Android 视频应用。

所需条件

  • 最新版本的 Android SDK
  • 最新版本的 Android Studio
  • 一部搭载 Android 10 或更高版本的移动设备。
  • 一根用于将移动设备连接到开发计算机的 USB 数据线。

经验

  • 您需要具备 Java 或 Kotlin 经验。
  • 您需要掌握 Android 开发相关知识。

2. 运行示例应用

为了让您能尽快上手,请下载示例应用代码,以便顺利完成此 Codelab。

如果您已安装 git,请克隆代码库。

git clone https://github.com/googlesamples/engage-sdk-samples.git

或者,点击此链接下载源代码,然后解压下载的 ZIP 文件。

此项目使用 Gradle 构建系统。如需构建此项目,请使用 gradlew build 命令,或在 Android Studio 中使用“导入项目”。

下载代码后,您会看到两个示例项目。

  • 对于 Java 开发者 - 请使用 read 示例应用

该应用是一个基础图书库。用户可以从列表中选择一本图书,然后开始阅读该图书。该应用演示了如何发布推荐和接续相关数据。

  • 对于 Kotlin 开发者 - 请使用 watch 示例应用

该应用是一个基础视频库。用户可以从列表中选择一个视频,然后开始观看该视频。该应用演示了如何发布推荐和接续相关数据。

如需获取有关学习 Android 开发的更多资源,请访问 developer.android.com 上的开发者指南

3. 构建实体

在此 Codelab 中,我们将分别参考 Engage SDK Read 集成指南Engage SDK Watch 集成指南,以了解 readwatch 示例应用。

实体是指代表集群中单个内容的对象。实体可以是电子书、电影或任何相关的内容类型。

对于 read 内容,SDK 具有以下实体类型

  • EbookEntity
  • AudiobookEntity
  • BookSeriesEntity

对于 watch 内容,SDK 具有以下实体类型

  • MovieEntity
  • TvShowEntity
  • TvSeasonEntity
  • TvEpisodeEntity
  • LiveStreamingVideoEntity
  • VideoClipEntity

在 read 示例应用中,请查看 EbookToEntityConverter.java 文件,其中包含用于构建 EbookEntity 以进行发布的方法。

EbookEntity.Builder entityBuilder = new EbookEntity.Builder()
        .setName("NAME OF EBOOK")
        .addAuthor("AUTHOR NAME")
        .setActionLinkUri(Uri.parse("DEEPLINK URI OF THIS EBOOK"))
        ...
         .build()

在 watch 示例应用中,请查看 ItemToEntityConverter.kt 文件,其中包含用于构建 MovieEntity 以进行发布的方法。

val movieBuilder: MovieEntity.Builder =
      MovieEntity.Builder()
        .setName("NAME OF THE MOVIE")
        .addPosterImage(
          Image.Builder()
            .setImageUri(
              Uri.parse("android.resource://movie")
            )
            .setImageWidthInPixel(408)
            .setImageHeightInPixel(960)
            .setImageTheme(ImageTheme.IMAGE_THEME_LIGHT)
            .build()
        )
        .setPlayBackUri(Uri.parse(movie.playbackUri))
        .setReleaseDateEpochMillis(movie.releaseDate)
        .setAvailability(movie.availability)
        .setDurationMillis(movie.durationMillis)
        .addGenre(movie.genre)
          ..
           .build()

同样,在您的应用中,您也可以将自己的数据项转换为想要发布的相应 Engage 实体。

4. 构建推荐集群

完成实体构建后,我们可以将其组合成一个集群。

集群是指一组捆绑在一起的内容。它们可以直观地呈现为一个界面视图,其中包含来自单个开发者合作伙伴的一组内容项。

e8ec28fa54ac7eec.png图.

Entertainment Space 界面,其中显示了包含来自单个合作伙伴的电子书实体的推荐集群。

对于大多数类别(包括 read 内容和 watch 内容),SDK 具有以下集群类型

  • 推荐集群可以根据用户在应用中的行为进行个性化设置,并按主题(例如新发布内容、降价或用户喜欢的话题)进行整理。每个应用最多可为每位用户提供 5 个推荐集群。
  • 接续集群可帮助用户在单个界面分组中继续进行未完成的内容(例如未看完的电影或未读完的电子书),其中包含来自多个应用的内容。
  • 精选集群可使用更大、更高级的界面模板在多应用集群中突出展示您的强推内容。

我们将为 read 内容和 watch 内容分别构建一个推荐集群。

read 示例应用中,请查看 GetRecommendationClusters.java 文件,其中展示了如何构建推荐集群的示例。

RecommendationCluster.Builder clusterBuilder = new RecommendationCluster.Builder();
// Set the cluster title
clusterBuilder.setTitle("For You");
for (int id : ebookIds) {
  //Create an ebook entity.
  EbookEntity entity = EbookToEntityConverter.convert(id); 
  // Add the ebook entity to the cluster
  clusterBuilder.addEntity(entity);
}
// Build the cluster
return clusterBuilder.build();

watch 示例应用中,请查看 ClusterRequestFactory.kt 文件,其中展示了如何构建推荐集群的示例。

// Loads all the movie data 
val recommendationsList = movieDao.loadMovieIsCurrentlyWatching(false)
val recommendationCluster = RecommendationCluster.Builder()
for (item in recommendationsList) {
   //Create a movie entity.
    val movieEntity = ItemToEntityConverter.convertMovie(item)
    // Add the movie entity to the cluster
    recommendationCluster.addEntity(movieEntity)
}
// Build the cluster
return recommendationCluster.build

5. 发布推荐集群

现在,我们已经了解了如何构建实体,以及如何将这些实体组合成集群。下一步是了解如何发布集群。

AppEngagePublishClient 负责建立连接以发布集群。

第 1 步:初始化客户端。

// Java version
AppEngagePublishClient client = new AppEngagePublishClient(context);
// Kotlin version
val client = AppEngagePublishClient(context)

第 2 步:创建用于发布集群的请求

在 read 示例应用中,请查看 EngageServiceWorker.java 中的 setRecommendations 方法

// Initialize the builder
PublishRecommendationClustersRequest.Builder publishRequestBuilder = new PublishRecommendationClustersRequest.Builder();

// Add all Recommendation Clusters
for (RecommendationCluster cluster : clusters) {
   publishRequestBuilder.addRecommendationCluster(cluster);
}
// Build the request    
publishRequestBuilder.build();

在 watch 示例应用中,请查看 ClusterRequestFactory.kt 中的 constructRecommendationClustersRequest 方法

// Initialize the builder
val request = PublishRecommendationClustersRequest.Builder()
// Add all Recommendation Cluster
.addRecommendationCluster(recommendationCluster)
// Build the request    
.build()

第 3 步:在 AppEngagePublishClient 中调用 publishRecommendationClusters 方法

在 read 示例应用中,请查看 EngageServiceWorker.java 中的 setRecommendations 方法

client.publishRecommendationClusters(publishRequest);

在 watch 示例应用中,请查看 EngageServiceWorker.kt 中的 publishRecommendations 方法

client.publishRecommendationClusters(request)

使用 isServiceAvailable API

在调用 publish API 之前,必须先调用 isServiceAvailable 以确保允许发布。

在 read 示例应用中,请查看 EngageServiceWorker.java 中的 startWork 方法

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

在 watch 示例应用中,请查看 EngageServiceWorker.kt 中的 doWork 方法

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.
          client.publishRecommendationClusters(request)
        } else {
          // Service is not available, do not publish.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

6. 发布状态

我们建议您使用 updatePublishStatus API 来指明内容未发布的原因。这有助于 Google 避免在您的应用有意不发布内容时发出错误提醒,引导用户采取纠正措施以访问您的内容,并向您提供有关内容发布状况的数据分析。

如需了解状态代码,请访问开发者网站。例如,如果因为用户需要登录而未显示任何内容,请使用 NOT_PUBLISHED_REQUIRES_SIGN_IN。我们将在下一步中应用此代码。

在 read 示例应用中,请查看 EngageServiceWorker.kt 中的 publishAndSetResult 方法

int publishStatusCode;
              if (loggedInAccount.isPresent()) {
                // If an account is logged in and content is published
                publishStatusCode = AppEngagePublishStatusCode.PUBLISHED;
              } else {
                // If an account is not logged in and no content is published
                publishStatusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN;
              }
              setPublishStatus(client, publishStatusCode);
            })

在 watch 示例应用中,请查看 EngageServiceWorker.kt 中的 publishUserAccountManagement 方法

private suspend fun publishUserAccountManagement(): Result {
    val publishTask: Task<Void>
    val statusCode: Int
    if (db.accountDao().isAccountSignedIn()) {
      // If an account is logged in and content is published
statusCode = AppEngagePublishStatusCode.PUBLISHED
    } else {
     // If an account is not logged in and no content is published
      statusCode = AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN
    }
    return publishAndProvideResult(publishTask, statusCode)
  }

7. Work Manager 和广播 intent

Work Manager

我们建议在后台(使用 WorkManager)执行内容发布作业。您可以定期(例如每天)和/或根据用户事件(例如应用打开时或用户完成阅读会话后)来安排此任务。以下示例主要介绍了预定发布。

在 read 示例应用中SetEngageState.java 文件中的 queuePeriodicSetEngageStateWorker 展示了如何设置 WorkManager 的示例

// Create a work manager
WorkManager workManager = WorkManager.getInstance(appContext);

// Set up a periodic work request for 24 hrs.
PeriodicWorkRequest publishRequest =
        new PeriodicWorkRequest.Builder(
                EngageServiceWorker.class, /* repeatInterval= */ 24, TimeUnit.HOURS)
            .setInputData(clusterToPublishData)
            .build();
// Add the work request to queue
workManager.enqueueUniquePeriodicWork(
        publishWorkName, ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE, publishRequest);

在 watch 示例应用中Publisher.kt 中的 periodicallyCallEngageServiceWorker 展示了如何设置 WorkManager 的示例

// Set up a periodic work request for 24 hrs.
val workRequest = PeriodicWorkRequestBuilder<EngageServiceWorker>(
          repeatInterval = 24,
          repeatIntervalTimeUnit = TimeUnit.HOURS
        )
        .setInputData(workDataOf(PUBLISH_TYPE to publishType))
        .build()

// Create a work manager and add the work request to queue
WorkManager.getInstance(context)
.enqueueUniquePeriodicWork(
workerName,
ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
workRequest
)

广播 intent

除了通过作业发出发布内容 API 调用外,还需要设置 BroadcastReceiver 来接收内容发布请求。

广播 intent 主要用于重新激活应用和强制同步数据。不应过于频繁地发送广播 intent。仅在 Engage Service 确定内容可能已过时(例如,内容是一周前的)的情况下,广播 intent 才会触发。这样一来,开发者将更加确信,即使应用长时间未执行,用户也能够获得新鲜的内容体验。

必须通过以下两种方式设置 BroadcastReceiver:

  • 使用 Context.registerReceiver() 动态注册 BroadcastReceiver 类的实例。这样一来,仍位于内存中的应用即可进行通信。

打开 read 示例应用中的 MainActivity.java 文件,查看以下内容:

private void registerReceiver() {
    BroadcastReceiver publishReceiver = new EngageServiceBroadcastReceiver();
    IntentFilter filter = new IntentFilter();
    filter.addAction(Intents.ACTION_PUBLISH_RECOMMENDATION);
    filter.addAction(Intents.ACTION_PUBLISH_FEATURED);
    filter.addAction(Intents.ACTION_PUBLISH_CONTINUATION);
    int flags = ContextCompat.RECEIVER_EXPORTED;
    ContextCompat.registerReceiver(getApplicationContext(), publishReceiver, filter, flags);
  }
  • 在 AndroidManifest.xml 文件中使用 <receiver> 标记对实现进行静态声明。这样一来,应用便可以在未运行时接收广播 intent,并且也可以发布内容。

打开 read 示例应用中的 AndroidManifest.xml 文件,查看以下内容:

<receiver
        android:name=".publish.EngageServiceBroadcastReceiver"
        android:exported="true">
      <intent-filter>
        <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
        <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
        <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
             </intent-filter>
 </receiver>

该服务会发送以下 intent

  • com.google.android.engage.action.PUBLISH_RECOMMENDATION 建议在收到此 intent 时启动 publishRecommendationClusters 调用。
  • com.google.android.engage.action.PUBLISH_FEATURED 建议在收到此 intent 时启动 publishFeaturedCluster 调用。
  • com.google.android.engage.action.PUBLISH_CONTINUATION 建议在收到此 intent 时启动 publishContinuationCluster 调用。

8. 使用验证应用进行测试

下载并使用验证应用来验证您的集成

验证应用应将每个集群显示为单独的行。

  • 输入发布数据的软件包的名称。

d1ad850cd02991d.png

  • 验证相应集群中的所有实体是否均已发布。

3953d00488212411.png

  • 验证实体中的所有字段是否均已发布。对于行中的每个项,开发者都可以点击海报图片以验证 intent。

23cd19224397adf3.png

验证广播 intent 流程

使用验证应用来验证广播 intent,点击界面顶部的按钮即可触发用于发送广播的逻辑。

9cb0b5315057fbe1.png

9. 恭喜

现在,您已了解如何将 Engage SDK 添加到您的 Android 应用。

如需了解详情,请参阅 Engage SDK 开发者指南和商务网站。

资源

根据发布的内容类型,SDK 包含不同类型的实体类。您可以在下面列出的各垂直领域的集成指南中查看可用实体的列表: