Engage SDK 常见问题解答

发布常见问题解答

谁负责管理内容发布作业？

应用开发者管理内容发布作业，并向 Engage Service 发送请求。这样一来，开发者合作伙伴就可以更好地控制向用户发布内容的时间和方式。这样可以避免为发布内容而过于频繁地唤醒合作伙伴应用。

开发者是否需要发布所有集群类型？

虽然从技术层面来讲，开发者可以只发布一个集群，但我们强烈建议开发者包含更多集群。否则，开发者将错失提升内容互动度的良机。我们强烈建议为每个行业发布所有集群类型。

在应用运行期间，开发者合作伙伴应该以怎样的频率使用 Work Manager 发布数据？

这将由开发者合作伙伴决定。对于常规推荐内容，Google 建议每天发布 1 到 2 次；对于购物车、重新订购和其他接续内容，建议使用事件驱动型方法（例如，在用户将商品添加到购物车或在用户将电影停止播放时，启动 worker 作为回调）。对于社交应用，请务必在每次使用应用后发布更新后的推荐集群。社交应用用户更感兴趣的是最新的推荐内容，并且最好只看到一次帖子。

开发者应在何时调用删除 API？

仅当没有要发布的内容时，才应调用删除 API。请勿随后调用删除和发布 API 来替换内容；发布 API 会自动移除之前的内容。

广播 intent 常见问题解答

为什么 Android 应用开发者需要注册广播 intent？

为了向用户提供新内容，您应该使用广播 intent 来触发数据同步，以应对用户可能不经常使用应用的情况。

不允许后台执行

注册广播 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));
...

}

工作流常见问题解答

与 SDK 集成时，您可能会遇到以下错误：

深层链接与软件包名称关联。使用 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？

  1. Google TV
  2. Android TV（仅限设备端，但支持 Engage SDK）
  3. Google TV Android 移动应用
  4. Google TV iOS 移动应用
  5. Play Cubes
  6. Google Entertainment Space
  7. 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 合作伙伴，还是希望尽快加入 EAP，请与我们联系，以便我们在您开始集成 Engage SDK 之前设置访问权限。

更新了创建实体部分中的图片要求。

有了这个新的 API 文档，Google 服务器是否会从客户端拉取“继续观看”数据，并且这些数据是否会反映在所有设备中？

新 API 为继续观看功能带来了诸多优势，包括：

  • 在多部 Google TV 上畅享流畅体验：用户可以在一部 Google TV 上开始观看，然后在使用同一账号登录的任何其他 Google TV 上继续观看。此功能也适用于旧版 Android TV。

  • 移动应用集成：Android 版和 iOS 版 Google TV 移动应用均提供“继续观看”功能，让用户能够在电视和移动设备之间无缝切换。

  • 提高用户留存率：即使在未安装应用或用户未登录的设备上，继续观看功能也会提示用户重新与您的应用互动，从而提高留存率。

  • 扩展到其他平台：此集成将“继续观看”功能扩展到 Android、Play Cube、平板电脑以及 Android 上的其他 Google 媒体应用和途径等其他 Google 媒体平台，从而最大限度地提高跨设备的用户互动度。

我可以向接续集群发布的实体数量有上限吗？

每个开发者合作伙伴在接续集群中最多只能有 5 个实体。此限制可确保在 Google TV 上的“继续观看”行（多个媒体提供商共享的空间）中公平分配内容。

如果我尝试发布超过 5 个实体，会怎么样？

如果您的发布请求超出 5 个实体限制，EngageSDK 将拒绝该请求。您需要减少请求中实体的数量，才能成功发布。您应仅添加用户未看完的媒体资源，因此在大多数情况下，此类媒体资源只有少数。如果有超过 5 个此类实体，您可以选择发布较新的实体。

为什么实体数量有上限？

Google TV 上的“继续观看”行会显示来自不同媒体提供商的内容。限制每个提供商的实体数量可确保用户看到来自其所有喜爱来源的丰富多样的内容，从而提供公平、均衡的用户体验。

验证应用问题

在提交应用之前，是否必须使用验证应用测试我的应用？

是的，在提交 APK 之前，请务必使用验证应用测试您的应用。

我们理解，您可能对自己的实现充满信心，但“继续观看”2.0 集成包含许多复杂的组件。验证应用可充当安全网，尽早发现潜在问题，从长远来看可为您节省宝贵的时间和精力。

您可以将其视为一次快速检查，有助于确保顺利发布并提供出色的用户体验。

通过提前发现并解决所有问题，您可以避免因被拒而感到沮丧，并避免反复提交。

如需提交 APK，您需要附上显示应用已通过验证流程的屏幕截图。

#### 集成过程中需要注意哪些常见错误？

验证应用旨在发现“继续观看”2.0 集成可能存在的问题。以下是开发者经常遇到的一些常见错误：

对于所有内容类型（电影、电视剧分集、直播、视频剪辑）：

  • 缺少链接：请确保为您的内容提供适用于特定平台的有效 URI（链接）。这些链接会告知系统在每个平台上应在哪里找到您的内容。
  • 缺少标题：请务必为您的所有内容添加标题。这有助于用户识别自己观看的内容。
  • 图片宽高比：确保与您的内容相关联的所有图片的宽高比接近 16:9。这样可以确保您的图片在不同屏幕上正常显示。

对于电视剧集：

  • 完整的分集信息：请务必提供节目名称、剧集编号和剧季编号。这有助于整理剧集，并允许用户在系列中导航。
  • 准确的播放位置：仔细检查上次播放位置是否小于或等于分集的总时长。这样可以确保用户从正确的位置继续播放。

对于电影：

  • 准确的播放位置：与电视剧集类似，请确保上次播放位置准确无误。

对于直播视频：

  • 直播者信息：对于直播，请添加直播者的姓名。

对于视频剪辑：

  • 创作者信息：指定视频剪辑的创作者。

请注意：验证应用会标记这些问题，以便您在提交应用之前进行修正。这样可以节省您的时间，并确保用户获得更顺畅的体验。

账号和个人资料问题

我的应用使用匿名用户登录。是否仍需要 AccountProfile 才能使用“继续观看”2.0？

AccountProfile 适用于使用个人用户账号的应用。不过，我们了解到，某些应用（例如您的应用）可能依赖于匿名登录。在这种情况下，“继续观看”2.0 的运作方式如下：

  • 从技术层面来说，AccountProfile 是必需的，但即使您的应用没有用户账号系统，您仍然可以集成“继续观看”2.0。
  • 仅限设备端使用：继续观看 2.0 的跨设备功能依赖于在不同设备上识别用户。由于匿名登录无法提供此信息，因此此功能将仅限于用户当前使用的设备。
  • 配置方法：如需进行此设置，您需要停用跨设备同步。 这样可以确保“继续观看”条目仅显示在开始播放内容的特定设备上。

总结：虽然您可以将“继续观看”2.0 与匿名登录集成，但用户只能在同一设备上继续观看内容。

即使我的应用同时支持 accountId 和 profileId，我也可以仅使用 accountId 来使用 AccountProfile 吗？

AccountProfile 需要同时提供 accountId 和 profileId 才能正常运行。原因如下：

  • 一致的标识：accountId 用于标识用户，而 profileId 用于区分该用户账号中的不同个人资料（如果适用）。提供这两项信息可确保“继续观看”功能准确跟踪和显示每个个人资料的内容。
  • 避免错误：在不同的 API 调用中使用不一致的 accountId 和 profileId 可能会导致意外行为和错误。例如，如果您在将内容添加到“继续观看”时同时包含这两项，但在删除内容时仅使用 accountId，系统可能无法正确识别和移除预期内容。

是否需要 profileId 才能使用“继续观看”2.0？

  • accountId 是必需字段。这会在不同设备上识别用户。
  • profileId 对于提供良好的用户体验至关重要。虽然 profileId 在技术上是可选的，但如果您的服务支持多个个人资料（如许多在线媒体服务），强烈建议您使用 profileId。为什么这如此重要？因为如果没有 profileId，继续观看功能可能会显示同一账号中其他个人资料的内容。这可能会给用户带来困惑和沮丧的体验。
  • 简而言之：提供 profileId 可确保“继续观看”功能准确反映每个用户的观看记录。除非您的应用不支持账号中的个人资料概念，否则您应提供个人资料。

Google 会如何使用其端的 profileId？

如果该服务提供不同的个人资料来观看内容，系统会使用 accountId 和 profileId 将设备上观看的内容与设备上已登录的 Google 账号相关联。Google 会根据 accountId-profileId 组合记录继续观看数据。登录了同一 Google 账号的任何 Google 设备都会在“继续观看”行中获取同一关联的 accountId-profileId 的最新更新数据。

是否必须关联账号才能实现“继续观看”2.0？

无需关联账号。我们将降低其优先级，所有相关用例都将由新的 Device Entitlements API 涵盖。

跨设备同步问题

在用户同意“跨设备同步”后，系统会将他们正在观看的内容保存到 Google TV 服务器，以便他们在任何已登录账号的设备上无缝接着上次观看的位置继续观看。如果未征得用户同意，其观看记录将保留在当前设备本地。

我们可以将“在设备之间保持同步”设置为 false 吗？

UserConsentToSyncAcrossDevices 标志用于控制用户的 ContinuationCluster 数据是否会在其设备（电视、手机、平板电脑等）之间同步。如果此标志设为 false，则“继续观看”功能只会在同一设备上发生。

为了充分利用我们的跨设备功能，我们强烈建议您的应用征得用户同意并将 SyncAcrossDevices 设为 true。

设备？非 Android 设备会将哪些数据点分享给第三方服务器？

意见征求是在用户级别（个人资料级别或账号级别）收集的。征得用户同意后，您就可以将基于互动的继续观看载荷发送到任何位置，以便 Google 在用户在任何设备上与任何实体进行部分互动或下一次互动时，反映用户的通用性接续状态（而无需在每部设备或平台上重新征求用户同意）。合作伙伴将发送与个人资料 ID（已存储在 Android 上）关联的用户最新的继续观看状态（如规范所述）。

REST API 问题

REST API 是否有文档？

REST API 的预计发布时间为 2025 年 3 月，详情请参阅“继续观看 2.0”开发者文档。

旧版“接下来观看”问题

Video Discovery API 是否会取代 Watch Next API？

Video Discovery API 将在支持 Watch Next API 的所有 Android TV 设备上向后兼容。所有开发者都应使用 Video Discovery API（继续观看 2.0）发布到“继续观看”行。

测试和集成问题

LastPlayBackPositionTimeMillis 和 duration 有何区别？

LastPlayBackPositionTimeMillis 应反映用户停止观看时（例如，605000 毫秒（10 分钟 5 秒）。该值不得大于实体的总时长。

而 LastEngagementTime 是用户上次与内容互动时的时间戳。

我们应执行哪些测试用例？

以下是我们的质量检查团队针对 Google TV 执行的测试用例。您还可以在其他平台上执行类似的测试用例。

  1. 观看时长超过 20 分钟的视频大约 5 分钟。退出应用。视频卡片应显示在“继续观看”行中。注意：在 CW 中，我们只会显示每个第三方应用的 5 张卡片
  2. 选择“继续观看”行中新显示的卡片后，系统应从视频中的正确位置继续播放视频。注意：任何新内容或旧内容都应从上次暂停的位置继续播放
  3. 在 GTV 设备上更改账号后，继续观看行中的卡片应该也会随之更改。系统只会显示当前账号中的视频。按最近用过的顺序排序。第三方应用配置文件 CW 将混合使用。注意：GoogleAccount2 的 CW 将显示 GoogleAccount2 观看过的第三方内容
  4. 使用返回按钮退出应用 > 确保卡片显示在“继续观看”行中
  5. 隐藏“继续观看”行中的视频，该视频不应再次显示。测试隐藏的内容是否会在 24 小时后保持隐藏状态，即使在应用在 24 小时后打开后也是如此。确认隐藏一个项不会隐藏多个项。
    1. “继续观看”中的内容播出信息，包含完整元数据：卡片图片、应用名称、标题、电视内容的剧季和剧集编号
  6. 进度条中显示“检查进度”
  7. 用户观看了内容直到片尾字幕 - 内容未显示在“继续观看”中
  8. 确认“继续观看”行中未显示未看过的内容
  9. 确认 CW 项是按观看活动发生的时间（而非应用上次打开的时间或上一天）排序的
  10. 确认 CW 卡片上的剧集和季节详情与剧集内容的观看记录相符
  11. 确认已看完（已获得所有奖励或已看完）的项目不会显示在“继续观看”中
  12. 在观看剧集/电影/节目时关闭设备。“在观看剧集/电影/节目时关闭设备。验证在开启设备和其他电视时，CW 是否会在正确的位置显示正确的卡片和进度条
  13. 完整观看第 1 集后，关闭设备，然后进行验证
    1. 第 1 集会消失，并且不会再次显示在“继续观看”行中 [在第二部设备上以及开启测试设备时]
    2. 第 2 集（如果有）应显示在“继续观看”行中 [在第二部设备上和开启测试设备时]

  14. 第一种场景：TV1：Google 账号：mom，第三方账号 / 个人资料：账号 1/profile_1。观看内容并验证 CW 数据，显示第三方账号_1/个人资料_1 观看的内容

    1. TV2：Google 账号：mom。验证第一个场景中的 CW 数据。现在，使用其他账号登录第三方应用。第三方账号 / 个人资料：account_2 / profile_2。观看内容并验证 CW 数据是否显示了第三方账号_2/个人资料_2 观看的内容

  15. GoogleAccount：mom。未安装新设备支持请求 /第三方应用。在新设备（FDR 设备）上，验证 CW 会显示 GoogleAccount 上次使用的第三方应用中的数据。注意：如果 GAIA 尚未与其他设备上的第三方个人资料相关联，则 CW 行不应显示第三方内容

    1. GoogleAccount：mom。新设备支持请求 /第三方应用已安装但未登录。 在新设备（FDR 设备）上，验证 CW 会显示 GoogleAccount 上次使用的第三方应用中的数据。
    2. 注意：安装应用并登录后，CW 状态会反映已登录第三方应用的活跃第三方用户。
    3. 注意：如果 Google 账号尚未与第三方个人资料相关联，“继续观看”行不应显示第三方内容

Google TV iOS 应用中未显示“继续观看”选项。这是怎么回事？

您需要发送 iOS 深层链接，才能在 iOS 设备上显示“继续观看”功能。

我应该多久更新一次“继续观看”信息？我是否应频繁更新“继续观看”信息，例如每 15 秒更新一次？

不建议频繁更新。原因如下：

  • 性能影响：持续发送更新会给我们的服务器带来不必要的压力，可能会导致所有用户的系统运行速度变慢。
  • 不必要的数据：用户在积极观看时，其播放位置会不断变化。每隔几秒发送一次更新会产生大量冗余数据，这些数据对恢复播放没有帮助。

何时更新“继续观看”信息：

重点捕获用户观看进度中的重要变化。以下是关键场景：

  • 播放暂停或停止：当用户暂停或停止观看时，发送更新以存储其当前位置。
  • 应用关闭或在后台运行：如果用户在观看视频时退出应用或切换到其他应用，请发送更新以保存其进度。
  • 当用户从应用内的“继续观看”行中移除内容时

如何高效更新：

请利用视频播放器或应用生命周期中的事件触发更新，而不是按时间触发更新。例如：

  • onPause、onStop：视频播放暂停或停止时。
  • onAppClose、onAppBackgrounded：当应用关闭或移至后台时。

遵循这些准则，您可以确保高效使用资源，同时为用户提供流畅的“继续观看”体验。