发布常见问题解答
谁负责管理内容发布作业？
应用开发者管理内容发布作业，并向 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 常见问题解答
常规问题
什么是 Engage？
Engage 让“从上次中断的位置继续”体验更上一层楼！这是一项重大升级，让观看者能够在更多设备上无缝继续观看内容。想象一下，您在 Google TV 上开始观看一部电影，然后在通勤途中在手机上轻松继续观看，这就是 Engage 的强大功能。
这个新系统旨在通过在整个 Google 生态系统中提供顺畅无阻的体验，提高观看者的互动度和留存率。
Video Discovery API 与 Engage 相同吗？
是的，它们是相同的。Engage SDK 是一个库，其中包含对“继续观看”行的支持。Engage 支持的实体类型不限于视频，因此该集成不再称为“视频发现”。
使用 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、Google Play 合集、平板电脑以及 Android 上的其他 Google 媒体应用和途径，从而最大限度地提高跨设备的用户互动度。
我可以发布到 Continuation 集群的实体数量上限是多少？
每个开发者合作伙伴在接续集群中最多只能有 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 添加内容时同时包含这两者，但在删除内容时仅使用accountId，系统可能无法正确识别和移除预期内容。
Engage 是否需要 profileId？
accountId为必填项。 这有助于跨设备识别用户。profileId对于提供良好的用户体验至关重要。虽然从技术上讲，profileId是可选的，但如果您的服务支持多个个人资料（如许多在线媒体服务），则强烈建议您使用该属性。为什么这很重要？ 因为如果没有profileId，继续观看行可能会显示同一账号中其他个人资料的内容。这可能会让用户感到困惑和沮丧。- 简而言之：提供
profileId可确保向“继续观看”行提供的内容准确反映每个人的观看记录。除非您的应用不支持账号中的个人资料概念，否则您应提供该功能。
Google 如何在自己的系统中使用 profileId？
如果服务提供不同的个人资料来观看内容，则 accountId 和 profileId 将用于将设备上观看的内容与设备上登录的 Google 账号相关联。Google 会根据 accountId 和 profileId 的组合记录 ContinueWatching 数据。登录了同一 Google 账号的任何 Google 设备都会在其“继续观看”行中从同一关联的 accountId 和 profileId 获取最新更新的数据。
实现 Engage 是否需要进行账号关联？
无需进行账号关联。我们正在降低其优先级，所有相关用例都将由新的 Device Entitlements API 涵盖。
“跨设备同步”相关问题
用户同意“跨设备同步”意味着什么？
在用户同意“跨设备同步”后，他们正在观看的内容将保存到 Google TV 服务器，以便他们在任何已登录账号的设备上无缝续播。如果用户未同意，其观看记录将仅保存在当前设备上。
我们可以将“跨设备同步”设置为 false 吗？
setUserConsentToSyncAcrossDevices 标志用于控制用户的 ContinuationCluster 数据是否在设备（电视、手机、平板电脑等）之间同步。如果此标志设置为 false，则“继续观看”内容仅在同一设备上显示。
为了充分利用我们的跨设备功能，我们强烈建议您的应用征得用户同意，并将 SyncAcrossDevices 设置为 true。
在非 Android 设备上，如何征得用户同意分享观看记录
devices? 非 Android 设备会向第三方服务器分享哪些数据点？
在用户级别（个人资料或账号级别）征求用户同意。获得用户同意后，系统可以随时发送基于互动的“继续观看”载荷，以便 Google 能够在用户在任何设备上进行部分互动或后续互动的实体中反映用户的无处不在的恢复状态（无需在每台设备或每个平台上重新征求用户同意）。合作伙伴将发送与个人资料 ID（已存入 Android）关联的用户最新“继续观看”状态（根据规范）。
REST API 问题
是否有关于 REST API 的文档？
REST API 的预计发布时间为 2025 年 3 月，这一点已在 Engage 开发者文档中说明。
旧版“接下来观看”问题
Engage 是否会取代“接下来观看”API？
Engage 将在所有支持“接下来观看”API 的 Android TV 设备上向后兼容。如需在 Google TV 和其他支持 Engage 的途径上进行集成，开发者应使用 Engage SDK。
测试和集成问题
LastPlayBackPositionTimeMillis 和时长之间有什么区别？
LastPlayBackPositionTimeMillis 应反映用户停止观看时的播放时长（以毫秒为单位，例如 10 分 5 秒对应 605000 毫秒）。该值不得大于实体的总时长。
而 LastEngagementTime 是用户上次与内容互动的时间戳。
我们应该执行哪些测试用例？
以下是我们的 QA 团队针对 Google TV 执行的测试用例。您也可以在其他平台上执行类似的测试用例。
- 观看一个时长超过 20 分钟的视频，观看时长约为 5 分钟。退出应用。视频卡片应显示在“继续观看”行中。注意： 在 CW 中，我们仅显示每个第三方应用的 5 张卡片
- 选择“继续观看”行中新出现的卡片后，应从视频中的正确位置继续播放视频。注意：任何新内容或旧内容都应从上次中断的位置继续播放
- 在 GTV 设备上更改账号应该会更改“继续观看”行中的卡片。应该只会显示当前账号中的视频。按最近顺序排序。第三方应用个人资料 CW 将混合显示。注意：GoogleAccount2 的 CW 将显示 GoogleAccount2 曾观看过的第三方内容
- 使用“返回”按钮退出应用 > 验证卡片是否显示在“继续观看”行中
- 在“继续观看”行中隐藏视频，该视频不应再次显示。测试隐藏的内容是否在 24 小时后以及应用在 24 小时后打开时仍保持隐藏状态。确认隐藏一项内容不会隐藏多项内容。
- “继续观看”行中显示的内容，包含完整元数据：卡片图片、应用名称、标题、电视内容的剧季和剧集编号
- 进度条中会显示“检查进度”
- 用户观看了内容，直到片尾字幕出现 - 内容不会显示在“继续观看”行中
- 确认“继续观看”行中没有显示未观看的内容
- 确认 CW 内容是根据观看活动发生的时间（而非应用上次打开的时间或最后一天）按时间顺序排列的
- 确认 CW 卡片上的剧集和季详细信息与观看的剧集内容一致
- 确认已看完的内容（播放到演职员表或之后的内容）不会显示在“继续观看”行中
- 在观看剧集/电影/节目期间关闭设备。“在观看剧集/电影/节目中途关闭设备。验证在开启设备时以及在其他电视上，CW 是否在正确的位置显示正确的卡片和进度条
- 完整观看第 1 集后关闭设备，验证
- 第 1 集消失，并且不会重新出现在“继续观看”行中 [在第二台设备上以及在开启测试设备时]
- 第 2 集（如果有）应显示在“继续观看”行中 [在第二台设备上以及在开启测试设备时]
- 第一种场景：TV1：Google 账号：妈妈，第三方账号/个人资料：账号 1/个人资料 1。观看内容，并验证 CW 数据是否显示第三方账号 1/个人资料 1 观看的内容
TV2：Google 账号：妈妈。验证第一个场景中的 CW 数据。现在，以其他账号登录第三方应用。第三方账号/个人资料：account_2/profile_2。观看内容，并验证 CW 数据是否显示第三方账号 2/个人资料 2 观看的内容
GoogleAccount: mom. 新设备情况/未安装第三方应用。在新设备（对设备进行 FDR）上，验证 CW 是否显示 Google 账号上次使用的第三方应用中的数据。注意：如果 GAIA 尚未与其他设备上的第三方个人资料相关联，则 CW 行不应显示第三方内容
- GoogleAccount: mom. 新设备用例/已安装第三方应用但未登录。 在新设备（对设备进行 FDR）上，验证 CW 是否显示 Google 账号上次使用的第三方应用中的数据。
-
- 注意：如果 Google 账号尚未与第三方个人资料相关联，则“继续观看”行不应显示第三方内容
我们发现 Google TV iOS 应用中没有显示续播内容。这是怎么回事？
您需要发送 iOS 深层链接，以便内容显示在 iOS 设备上的“继续观看”行中。
我应该多久更新一次“继续观看”行的内容信息？我是否应该频繁更新，例如每 15 秒更新一次？
不建议频繁更新。原因如下：
- 性能影响：持续发送更新会给我们的服务器带来不必要的压力，可能会导致所有用户的系统运行速度变慢。
- 不必要的数据：当用户正在观看视频时，其播放位置会不断变化。每隔几秒发送一次更新会产生大量冗余数据，这些数据对恢复播放没有帮助。
何时更新“继续观看”行的内容信息：
重点关注用户观看进度的有意义变化。以下是关键场景：
- 播放暂停或停止：当用户暂停或停止观看时，发送更新以存储其当前位置。
- 应用已关闭或在后台运行：如果用户在观看视频时退出应用或切换到其他应用，请发送更新以保存其进度。
- 当用户从应用内的“继续观看”行中移除内容时
如何高效更新：
请勿使用定时更新，而是利用视频播放器或应用生命周期内的事件来触发更新。例如：
onPause、onStop：视频播放暂停或停止时。onAppClose、onAppBackgrounded：当应用关闭或移至后台时。
遵循这些准则，您将确保高效利用资源，同时仍可在“继续观看”行中为用户提供顺畅的体验。