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