发布常见问题解答
谁负责管理内容发布作业？
应用开发者管理内容发布作业，并向 Engage Service 发送请求。这样一来，开发者合作伙伴就可以更好地控制向用户发布内容的时间和方式。这样可以避免为发布内容而过于频繁地唤醒合作伙伴应用。
开发者是否需要发布所有集群类型？
虽然从技术层面来讲，开发者可以只发布一个集群，但我们强烈建议开发者包含更多集群。否则，开发者将错失提升内容互动度的良机。我们强烈建议为每个行业发布所有集群类型。
在应用运行期间，开发者合作伙伴应该以怎样的频率使用 Work Manager 发布数据？
这将由开发者合作伙伴决定。Google 建议，对于一般推荐内容，每天发布一次或两次；对于购物车、重新订购和其他续订内容，则使用事件驱动型方法（例如，在用户将商品添加到购物车或用户中途停止观看电影时，以回调方式启动 worker）。 对于社交应用，务必在每次使用应用后发布更新的推荐聚类。社交应用用户对最新推荐内容更感兴趣，最好是只看到一次帖子。
开发者应在何时调用删除 API？
仅当没有要发布的内容时，才应调用删除 API。请勿随后调用删除和发布 API 来替换内容；发布 API 会自动移除之前的内容。
广播 intent 常见问题解答
为什么 Android 应用开发者需要注册广播 intent？
为了向用户提供新内容，您应该使用广播 intent 来触发数据同步，以应对用户可能不经常使用应用的情况。
无法测试广播 intent
验证应用不支持测试具有权限的广播 intent。您必须在测试时移除权限，然后在第 6 步中将 SDK 切换到正式版之前重新添加这些权限。
不允许后台执行
注册广播 intent 时，您可能会遇到以下错误：
Background execution not allowed: receiving Intent
{ act=com.google.android.engage.action.PUBLISH_RECOMMENDATION .. }
您需要动态注册广播接收器。
class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION 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,
com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
/*scheduler=*/null));
...
}
工作流常见问题解答
与 SDK 集成时，您可能会遇到以下错误：
应用、集群、实体级验证错误
应用级、集群级和实体级摘要会显示验证错误的数量。这些错误对应于缺少必需字段或提供的值无效。错误消息会以红色显示在每个相关字段下方。在分享 APK 之前，请修正所有验证错误并检查正确性。
测试深层链接
深层链接与软件包名称关联。使用 adb 工具测试深层链接是一种不错的方法。
adb shell am start -W -a android.intent.action.VIEW -d <DEEPLINK URI> <PACKAGE NAME>
如何计算集成的影响？
深层链接是跟踪归因的绝佳方式。用于将用户引导至您的应用的深层链接网址可包含额外的跟踪参数。例如：http://xx/deeplink?source_tag=engage。
开发者可以添加自己的跟踪参数并提供归因数据以计算影响。
Engage for TV 2.0 常见问题解答
常规问题
什么是 Engage？
Engage 将“从上次中断处继续播放”体验提升到了新的高度！这是一项重大升级，可让观看者在更多设备上顺畅地继续观看内容。想象一下，您可以在 Google TV 上开始观看电影，然后在通勤途中轻松地在手机上继续观看，这就是 Engage 的强大之处。
新系统旨在通过在整个 Google 生态系统中提供顺畅无阻的体验，提高观看者的互动度和留存率。
Video Discovery API 与 Engage 是否相同？
是的，它们是相同的。Engage SDK 是一个库，其中包含对“继续观看”行的支持。与视频相比，Engage 支持更多内容实体类型，因此该集成不再命名为“视频发现”。
使用 Engage 有哪些好处？
答：“继续观看”功能可让观看者比以往更轻松地从上次中断的地方继续观看您的内容，无论他们使用什么设备。其工作原理如下：
- 在 Google 产品间实现无缝体验：在 Google TV 上开始观看，然后可在 Android 手机、iPhone 或 Android 平板电脑上无缝继续观看。即使在尚未安装该应用的设备上，此功能也能正常运行！
- 提高互动度和留存率：即使是在新设备上，Engage 也能帮助您重新吸引用户使用您的应用。通过让用户继续观看自己喜爱的节目，您可以提高他们继续观看的几率。
- 覆盖面更广：除了 Google TV，Engage 还适用于其他 Android 媒体体验，例如 Play 收藏和其他 Google 媒体应用。
- 向后兼容：如果您已在使用旧版“接着看”功能，则没问题！Engage 具有向后兼容性，因此您现有的集成仍可正常运行。
重要提示：所有新的“继续观看”集成都必须使用 Engage。旧的“跨设备接下来播放”系统正在逐步淘汰。
哪些平台支持 Engage？
- Google TV
- Android TV（仅限设备端，但支持 Engage SDK）
- Google TV Android 移动应用
- Google TV iOS 移动应用
- Play 收藏集
- Google 娱乐专区
- iOS 设备（通过 REST API 集成）。
Engage SDK 是否适用于“继续观看”功能？
是的，Engage SDK 支持“继续观看”行中的内容。必须与 Engage 集成。
所有人都可以使用 Engage 吗？
我们将分阶段推出 Engage。
- 抢先体验：我们最初将通过抢先体验计划 (EAP) 向部分合作伙伴授予访问权限。
- 扩大访问范围：我们正在努力尽快让所有开发者都能使用 Engage。
为确保顺利成功发布，我们已采取多项安全措施来管理发布。这包括在 Engage 端设置许可名单，以及在 Engage SDK 中进行单独检查。无论您是 EAP 合作伙伴，还是希望尽快加入，请与我们联系，以便我们在您开始集成 Engage SDK 之前设置访问权限。
是否有建议的图片大小？
我们更新了创建实体部分中的图片要求。
有了这个新的 API 文档，Google 服务器从客户端提取的“继续观看”数据是否会反映在所有设备上？
新 API 针对“继续观看”行中的内容提供了多项重大改进，包括：
在 Google TV 上获得顺畅的体验：用户可以在一台 Google TV 上开始观看，然后在登录了同一账号的任何其他 Google TV 上继续观看。 此功能还适用于旧版 Android TV。
移动应用集成：Engage 中的内容会显示在适用于 Android 和 iOS 的 Google TV 移动应用中，让用户可以在电视和移动设备之间无缝切换。
提高用户留存率：即使在未安装应用或用户未登录的设备上，“继续观看”行中的内容也能促使用户重新与您的应用互动，从而提高留存率。
扩展到其他平台：Engage 可扩展到其他 Google 媒体平台，例如 Android、Play Collections、平板电脑以及 Android 上的其他 Google 媒体应用和平台，从而最大限度地提高用户在各种设备上的互动度。
我可以向延续集群发布多少个实体的限制是什么？
每个开发者合作伙伴最多可以在接续集群中广播 5 个实体。此限制是为了在 Google TV 的“继续观看”行中公平分配内容，因为该行是多个媒体提供商共用的空间。
如果我尝试发布超过 5 个实体，会发生什么情况？
如果实体数量超过 5 个，Engage SDK 将拒绝您的发布请求。您需要减少请求中的实体数量才能成功发布。您应仅包含用户上次观看的实体，因此在大多数情况下，此类实体只有几个。如果此类实体超过 5 个，您可以选择最近的实体进行发布。
为什么实体数量有限制？
Google TV 上的“继续观看”行会显示来自各种媒体服务提供商的内容。限制每个提供商的实体数量，以便用户从所有喜爱的来源中看到各种各样的内容，从而打造公平均衡的用户体验。
验证应用问题
在提交应用之前，是否必须使用验证应用测试我的应用？
是的，在提交 APK 之前，务必使用验证应用测试您的应用。
虽然我们理解您可能对自己的实现充满信心，但 Engage 集成包含许多复杂的组件。验证应用可充当安全网，及早发现潜在问题，从长远来看可为您节省宝贵的时间和精力。
您可以将其视为一次快速检查，有助于确保顺利发布并提供出色的用户体验。
通过提前发现并解决任何问题，您可以避免因遭到拒批而需要重新提交的麻烦。
如需提交 APK，您需要附上一张屏幕截图，显示您的应用已通过验证流程。
在集成过程中，有哪些常见错误需要注意？
验证应用旨在发现 Engage 集成中存在的潜在问题。以下是开发者经常遇到的一些常见错误：
对于所有类型的内容（电影、电视节目、直播、视频片段）：
- 链接缺失：请务必为您的内容提供有效的平台专用 URI（链接）。这些链接会告知系统在每个平台上哪里可以找到您的内容。
- 缺少标题：请务必为所有内容添加标题。这有助于用户识别自己观看过的内容。
- 图片宽高比：验证与您的内容相关联的所有图片的宽高比是否接近 16:9。这可确保您的图片在不同屏幕上正确显示。
对于电视剧集：
- 完整的分集信息：请务必添加节目名称、分集编号和剧季编号。这有助于整理剧集，并让用户在系列中导航。
- 准确的播放位置：仔细检查上次播放位置是否小于或等于剧集的总时长。这样可确保用户从正确的位置继续播放。
对于电影：
- 准确的播放位置：与电视剧集类似，验证上次播放位置是否准确。
对于直播视频：
- 广播公司信息：包含直播的广播公司名称。
对于视频片段：
- 创作者信息：指定视频剪辑的创作者。
请注意：验证应用会标记这些问题，以便您在提交应用之前修复它们。这样可以节省您的时间，并确保用户获得更顺畅的体验。
账号和个人资料问题
我的应用使用匿名用户登录。对于 Engage，是否仍需要 AccountProfile？
AccountProfile 专为使用个人用户账号的应用而设计。不过，我们理解，有些应用（例如您的应用）可能依赖于匿名登录。在这种情况下，Engage 的运作方式如下：
AccountProfile在技术上是必需的，但即使您的应用没有用户账号系统，您仍然可以集成 Engage。- 仅限在设备上使用：Engage 的跨设备功能依赖于识别不同设备上的用户。由于匿名登录无法提供此信息，因此该功能将仅限在用户的当前设备上使用。
- 如何配置：如需设置此功能，您需要停用跨设备同步功能。这样可确保继续条目仅显示在开始播放内容的特定设备上。
总结：虽然您可以将 Engage 与匿名登录集成，但用户只能在同一设备上继续观看内容。
即使我的应用同时支持 accountId 和 profileId，我是否也可以仅使用 accountId 而不使用 profileId 来使用 AccountProfile？
AccountProfile 需要同时具备 accountId 和 profileId 才能正常运行。
原因如下：
- 一致的身份识别：
accountId用于识别用户，而profileId用于区分相应用户账号中的不同个人资料（如果适用）。同时提供这两个值可确保 Engage 准确跟踪和显示每个个人资料的内容。 - 防止出错：在不同的 API 调用中不一致地使用
accountId和profileId可能会导致意外行为和错误。例如，如果您在向 Engage 添加内容时同时添加了这两个 ID，但在删除内容时仅使用了accountId，系统可能无法正确识别并移除所需的内容。
Engage 是否需要 profileId？
accountId为必填项。 此标识符用于跨设备识别用户。profileId对于提供良好的用户体验至关重要。虽然从技术上讲，profileId是可选的，但如果您的服务支持多个个人资料（就像许多流媒体服务一样），强烈建议您使用profileId。为什么它如此重要？因为如果没有profileId，“继续观看”行可能会显示同一账号中其他个人资料的内容。这可能会让您的用户感到困惑和沮丧。- 简而言之：提供
profileId可确保提供给“继续观看”行的内容准确反映每个人的观看记录。除非您的应用不支持账号中的个人资料概念，否则您应提供此参数。
Google 如何使用其收到的 profileId？
如果该服务提供不同的个人资料来观看内容，则 accountId 和 profileId 将用于将设备上观看的内容与设备上登录的 Google 账号相关联。Google 会根据 accountId 和 profileId 的组合记录“继续观看”数据。任何登录了同一 Google 账号的 Google 设备都会在其“继续观看”行中显示来自同一关联的 accountId 和 profileId 的最新更新数据。
是否需要进行账号关联才能实现 Engage？
无需进行账号关联。此功能的重要性正在降低，所有相关应用场景都将由新的 Entitlements API 涵盖。
跨设备同步问题
用户同意后，“在设备之间同步”是什么意思？
在征得用户“跨设备同步”同意后，用户观看的内容将保存到 Google TV 服务器，以便用户在任何已登录的设备上无缝继续观看。如果未征得用户同意，用户的观看记录将保留在当前设备上。
我们可以将“跨设备同步”设置为 false 吗？
setUserConsentToSyncAcrossDevices 标志用于控制是否在用户的设备（电视、手机、平板电脑等）之间同步 ContinuationCluster 数据。如果此标志设置为 false，则“继续观看”内容仅在同一设备上显示。
为了充分利用我们的跨设备功能，我们强烈建议您的应用征得用户同意，并将 SyncAcrossDevices 设置为 true。
在非 Android 设备上，如何征求用户同意分享观看记录
设备？非 Android 设备会向第三方服务器分享哪些数据点？
系统会在用户级别（个人资料级别或账号级别）征求用户同意。获得同意后，可以随时发送基于互动情况的“继续观看”载荷，以便 Google 在用户部分或接下来会互动的所有实体中反映用户在任何设备上的无处不在的恢复状态（无需在每台设备或平台上重新征求同意）。合作伙伴将发送与个人资料 ID（已存放在 Android 上）关联的用户最新“继续观看”状态（按照规范）。
REST API 问题
是否有关于 REST API 的文档？
REST API 的预计发布时间为 2025 年 3 月，这已在 Engage 开发者文档中记录。
旧版“接下来观看”问题
Engage 是否会取代 Watch Next API？
在支持“接下来观看”API 的所有 Android TV 设备上，Engage 将实现向后兼容。如需在 Google TV 和其他支持 Engage 的平台上集成，开发者应使用 Engage SDK。
测试和集成问题
LastPlayBackPositionTimeMillis 和时长之间有什么区别？
LastPlayBackPositionTimeMillis 应反映用户停止观看时的播放时长（以毫秒为单位），例如 10 分 5 秒为 605000 毫秒。它绝不应大于实体的总时长。
而 LastEngagementTime 是用户上次与内容互动的时间戳。
我们应该执行哪些测试用例？
以下是我们的质量检查团队针对 Google TV 执行的测试用例。您还可以在其他平台上执行类似的测试用例。
- 观看时长超过 20 分钟的视频约 5 分钟。退出应用。视频卡片应显示在“继续观看”行中。注意：在“继续观看”行中，我们仅针对每个第三方应用显示 5 张卡片
- 选择“继续观看”行中新显示的卡片应会从视频中的正确位置继续播放视频。注意：任何新内容或旧内容都应从上次停止播放的位置恢复播放
- 在 GTV 设备上更改账号时，继续观看行中的卡片应随之更改。应仅显示当前账号中的视频，并按最近观看时间排序。第三方应用个人资料的继续观看内容将混合显示。注意：GoogleAccount2 的继续观看内容将显示 GoogleAccount2 曾观看过的第三方内容
- 使用“返回”按钮退出应用 > 验证卡片是否显示在“继续观看”行中
- 隐藏“继续观看”行中的视频，该视频不应再次显示。测试隐藏的内容在 24 小时后甚至在应用在 24 小时后打开后是否仍处于隐藏状态。确认隐藏一个项目不会隐藏多个项目。
- “继续观看”行中包含完整元数据的内容可用性：卡片图片、应用名称、标题、电视内容的剧季剧集编号
- 进度条中会显示“检查进度”
- 用户观看内容直至片尾字幕结束 - 内容未显示在“继续观看”行中
- 确认“继续观看”行中未显示未观看过的项目
- 确认 CW 项按手表活动发生的时间（而非应用上次打开的时间或最后一天）按时间顺序排列
- 确认 CW 卡片上的剧集和剧季信息与观看的剧集内容一致
- 确认已完成（达到或超过积分要求）的商品不会显示在“继续观看”行中
- 在观看剧集/电影/节目过程中，中途关闭设备。“在观看剧集/电影/节目过程中，中途关闭设备。验证在开启设备和其他电视时，CW 是否在正确的位置显示正确的卡片和进度条”
- 在完整观看第 1 剧集后关闭设备，验证
- 第 1 集在“继续观看”行中消失 [在第二部设备上和在开启测试设备时]
- 第 2 集（如有）应显示在“继续观看”行中 [在第二部设备上和在开启测试设备时]
- 第一种情形：电视 1：Google 账号：妈妈，第三方账号 / 个人资料：账号 1/profile_1。观看内容并验证 CW 数据是否显示了第三方账号 1/个人资料 1 观看的内容
TV2：GoogleAccount：妈妈。验证第一个场景中的 CW 数据。现在，以其他账号登录第三方应用。第三方账号/个人资料：account_2/profile_2。观看内容并验证 CW 数据是否显示第三方账号/个人资料 (account_2/profile_2) 观看的内容
GoogleAccount：妈妈。未安装新的设备保护壳 /第三方应用。在新设备（FDR 设备）上，验证 CW 是否显示 Google 账号上次使用的第三方应用的数据。注意：如果 GAIA 尚未与另一设备上的第三方个人资料相关联，则 CW 行不应显示第三方内容
- GoogleAccount：妈妈。新设备用例 /已安装第三方应用但未登录。 在新设备上（对设备进行 FDR），验证 CW 是否显示 Google 账号上次使用的第三方应用的数据。
-
- 注意：如果 GoogleAccount 尚未与第三方个人资料相关联，“继续观看”行不应显示第三方内容
我们发现，Google TV iOS 应用中未显示续播内容。这是怎么回事？
您需要发送内容的 iOS 深层链接，以便内容显示在 iOS 设备上的“继续观看”行中。
我应该多久更新一次“继续观看”行的内容信息？我是否应该频繁更新，例如每 15 秒更新一次？
不建议频繁更新。原因如下：
- 性能影响：持续发送更新会给我们的服务器带来不必要的压力，可能会导致所有人的系统运行速度变慢。
- 不必要的数据：用户在积极观看时，其播放位置会不断变化。每隔几秒发送一次更新会产生大量冗余数据，这些数据对恢复播放没有帮助。
何时更新“继续观看”行的内容信息：
重点在于捕获用户观看进度的有意义的变化。以下是关键场景：
- 播放暂停或停止：当用户暂停或停止观看时，发送更新以存储其当前位置。
- 应用已关闭或已转到后台：如果用户在观看视频时退出应用或切换到另一应用，请发送更新以保存其进度。
- 当用户从应用内的“继续观看”行中移除内容时
如何高效更新：
请勿使用定时更新，而应利用视频播放器或应用生命周期内的事件来触发更新。例如：
onPause、onStop：视频播放暂停或停止时。onAppClose、onAppBackgrounded：当应用关闭或移至后台时。
遵循这些准则可确保高效利用资源，同时仍能为用户提供“继续观看”行中的顺畅体验。