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 集成指南,以了解 read 和 watch 示例应用。
实体是指代表集群中单个内容的对象。实体可以是电子书、电影或任何相关的内容类型。
对于 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. 构建推荐集群
完成实体构建后,我们可以将其组合成一个集群。
集群是指一组捆绑在一起的内容。它们可以直观地呈现为一个界面视图,其中包含来自单个开发者合作伙伴的一组内容项。
图.
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. 使用验证应用进行测试
下载并使用验证应用来验证您的集成
验证应用应将每个集群显示为单独的行。
- 输入发布数据的软件包的名称。
- 验证相应集群中的所有实体是否均已发布。
- 验证实体中的所有字段是否均已发布。对于行中的每个项,开发者都可以点击海报图片以验证 intent。
验证广播 intent 流程
使用验证应用来验证广播 intent,点击界面顶部的按钮即可触发用于发送广播的逻辑。
9. 恭喜
现在,您已了解如何将 Engage SDK 添加到您的 Android 应用。
如需了解详情,请参阅 Engage SDK 开发者指南和商务网站。
资源
根据发布的内容类型,SDK 包含不同类型的实体类。您可以在下面列出的各垂直领域的集成指南中查看可用实体的列表: