Engage SDK 常见问题解答

发布常见问题解答

谁管理内容发布作业？

应用开发者管理内容发布作业，并向 Engage 服务发送请求。通过这种方式，开发者合作伙伴可以更好地控制何时以及如何向用户发布内容。这可以避免过于频繁地唤醒合作伙伴应用来发布内容。

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

虽然从技术上讲，开发者可以只发布一个集群，但我们强烈建议包含更多集群。否则，开发者将错过通过其内容提升用户参与度的机会。我们强烈建议为每个垂直领域发布所有集群类型。

当应用运行时，开发者合作伙伴应该多久使用工作管理器发布一次数据？

这由开发者合作伙伴决定。Google 建议每天发布一到两次通用推荐内容，并对购物车、重新排序和其他延续内容使用事件驱动方法（例如，在用户将商品添加到购物车或用户中途停止观看电影时，将工作器作为回调启动）。对于社交应用，在每次使用应用后发布更新的推荐集群至关重要。社交应用用户对最新推荐更感兴趣，并且理想情况下希望一篇帖子最多只出现一次。

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

删除 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>

我如何计算集成的影响？

深层链接是追踪归因的好方法。将用户带到您应用的深层链接 URL 可以包含额外的追踪参数。例如 - "http://xx/deeplink?source_tag=engage"。

开发者可以添加自己的追踪参数并提供归因来计算影响。

Engage for TV 2.0 常见问题解答

一般问题

Continue Watching 2.0 是什么？

Continue Watching 2.0 (Video Discovery API) 将“从上次中断的地方继续”体验提升到了一个新的水平！这是一项重大升级，允许观众在更广泛的设备上无缝恢复其内容。想象一下，在您的 Google TV 上开始观看一部电影，然后通勤时毫不费力地在手机上继续观看——这就是 Continue Watching 2.0 的强大之处。

这个新系统旨在通过在整个 Google 生态系统中提供流畅、无摩擦的体验来提高观众参与度和留存率。

使用 Continue Watching 2.0 有什么好处？

答：无论用户使用何种设备，Continue Watching 2.0 都能让观看者比以往任何时候都更容易地从他们上次中断的地方继续观看您的内容。其工作原理如下：

• Google 生态系统中的无缝体验：在您的 Google TV 上开始观看，然后在您的 Android 手机、iPhone 或 Android 平板电脑上无缝继续。它甚至可以在您尚未安装应用的设备上运行！
• 提高参与度和留存率：Continue Watching 2.0 有助于将用户带回您的应用，即使是在新设备上。通过让用户恢复观看他们喜爱的节目，您将增加他们继续观看的可能性。
• 更广的覆盖范围：除了 Google TV，Continue Watching 2.0 还适用于其他 Android 媒体体验，例如 Play Cubes 和其他 Google 媒体应用。
• 向后兼容：如果您已经在使用旧的“接下来观看”功能，没问题！Continue Watching 2.0 是向后兼容的，因此您现有的集成仍然有效。

重要提示：所有新的 Continue Watching 集成都必须使用 Continue Watching 2.0。较旧的“跨设备接下来播放”系统正在逐步淘汰。

哪些界面支持 Continue Watching 2.0？

1. Google TV
2. Android TV（仅限设备端，但支持 Engage SDK）
3. Google TV Android 移动应用
4. Google TV iOS 移动应用
5. Play Cubes
6. Google 娱乐空间
7. iOS 设备（通过 REST API 集成）。

Engage SDK 是用于 Continue Watching 2.0 吗？

是的，Engage SDK 用于 Continue Watching 2.0。它与 Continue Watching 2.0 集成是必需的。

Continue Watching 2.0 对所有人开放吗？

Continue Watching 2.0 正在分阶段推出。

• 抢先体验：我们最初通过抢先体验计划 (EAP) 授予精选合作伙伴访问权限。
• 扩展访问：我们正在努力使所有开发者很快都能使用 Continue Watching 2.0。

为了确保顺利成功地发布，我们已采取保护措施来管理发布。这包括 Continue Watching 2.0 端的允许列表以及 Engage SDK 中的单独检查。无论您是 EAP 合作伙伴还是希望尽快加入，请联系我们，以便我们可以在您开始集成 Engage SDK 之前设置访问权限。

是否有推荐的图片尺寸？

图片要求已在“创建实体”部分更新。

有了这个新的 API 文档，Google 服务器从客户端拉取的 Continue Watching 数据会反映在所有设备上吗？

新的 API 为 Continue Watching 带来了显著优势，包括：

• 在 Google TV 上实现无缝体验：用户可以在一台 Google TV 上开始观看，并在登录相同帐号的任何其他 Google TV 上恢复观看。此功能也适用于较旧的 Android TV 版本。

• 移动应用集成：Continue Watching 在适用于 Android 和 iOS 的 Google TV 移动应用上可用，允许用户在电视和移动设备之间无缝切换。

• 增强用户留存：即使在未安装应用或用户未登录的设备上，Continue Watching 也会提示用户重新参与您的应用，从而提高留存率。

• 扩展到其他平台：此集成将 Continue Watching 扩展到其他 Google 媒体平台，例如 Android、Play Cubes、平板电脑以及 Android 上的其他 Google 媒体应用和界面，最大限度地提高用户在所有设备上的参与度。

我可以向 Continuation 集群发布的实体数量有什么限制？

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

如果我尝试发布超过 5 个实体会发生什么？

如果您的发布请求超出 5 个实体的限制，EngageSDK 将拒绝您的请求。您需要减少请求中的实体数量才能成功发布。您应该只包含用户上次停止观看的实体，因此在大多数情况下，只有少数此类实体。当此类实体超过 5 个时，您可以选择最近的那些进行发布。

为什么实体数量有限制？

Google TV 上的“继续观看”行显示来自各种媒体提供商的内容。限制每个提供商的实体数量可确保用户看到来自所有他们喜爱来源的各种内容，从而促进公平和平衡的用户体验。

验证应用问题

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

是的，在提交 APK 之前，使用验证应用测试您的应用至关重要。

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

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

通过预先识别和解决任何问题，您可以避免被拒绝和重新提交的挫败感。

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

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

验证应用旨在发现您的 Continue Watching 2.0 集成中存在的潜在问题。以下是开发者经常遇到的一些常见错误：

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

• 链接缺失：确保为您的内容提供有效的特定平台 URI（链接）。这些链接告诉系统在哪里可以找到您在每个平台上的内容。
• 标题缺失：不要忘记为您的所有内容添加标题。这有助于用户识别他们正在观看的内容。
• 图像宽高比：确保与您的内容关联的所有图像的宽高比接近 16:9。这可确保您的图像在不同屏幕上正确显示。

适用于电视剧集

• 完整的剧集信息：请务必包含节目名称、剧集编号和季编号。这有助于组织剧集，并允许用户在系列中导航。
• 准确的播放位置：仔细检查上次播放位置是否小于或等于剧集的总时长。这可确保用户从正确的位置恢复观看。

适用于电影

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

适用于直播视频

• 广播公司信息：包含直播的广播公司名称。

适用于视频剪辑

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

请记住：验证应用将标记这些问题，让您可以在提交应用之前修复它们。这可以节省您的时间，并为您的用户提供更流畅的体验。

帐号和个人资料问题

我的应用使用匿名用户登录。Continue Watching 2.0 仍然需要 AccountProfile 吗？

AccountProfile 专为使用个人用户帐号的应用而设计。但是，我们理解有些应用（例如您的应用）可能依赖匿名登录。在这种情况下，Continue Watching 2.0 的工作方式如下：

• AccountProfile 在技术上是必需的，但是...即使您的应用没有用户帐号系统，您仍然可以集成 Continue Watching 2.0。
• 限于设备端使用：Continue Watching 2.0 的跨设备功能依赖于跨不同设备识别用户。由于匿名登录无法提供此功能，因此该功能将仅限于用户当前设备。
• 如何配置：要进行此设置，您需要禁用跨设备同步。这可确保 Continue Watching 条目仅显示在开始观看内容的特定设备上。

总之：虽然您可以使用匿名登录集成 Continue Watching 2.0，但用户只能在同一设备上恢复内容。

当我的应用同时支持 accountId 和 profileId 时，我可以使用仅包含 accountId 而不包含 profileId 的 AccountProfile 吗？

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

• 一致的身份识别：accountId 识别用户，而 profileId 区分该用户帐号中的不同个人资料（如果适用）。同时提供两者可确保 Continue Watching 准确跟踪和显示每个独立个人资料的内容。
• 防止错误：在不同的 API 调用中不一致地使用 accountId 和 profileId 可能会导致意外行为和错误。例如，如果您在将内容添加到 Continue Watching 时同时包含两者，但在删除内容时只使用 accountId，系统可能无法正确识别和移除目标项目。

Continue Watching 2.0 是否需要 profileId？

• accountId 是必需的。这标识了跨设备的用户。
• profileId 对良好的用户体验至关重要。虽然在技术上是可选的，但如果您的服务支持多个个人资料（如许多流媒体服务那样），则强烈建议使用 profileId。为什么它如此重要？因为如果没有 profileId，Continue Watching 可能会显示同一帐号中其他个人资料的内容。这可能会给您的用户带来混乱和沮丧的体验。
• 简而言之：提供 profileId 可确保 Continue Watching 准确反映每个人的观看历史。除非您的应用不支持帐号内个人资料的概念，否则您应该提供它。

Google 如何在他们这一端使用 profileId？

如果服务提供不同的个人资料来观看内容，accountId 和 profileId 将用于将设备上观看的内容与设备上登录的 Google 帐号关联。Google 会将 ContinueWatching 数据记录到 accountId-profileId 组合中。登录同一 Google 帐号的任何 Google 设备都将从同一关联的 accountId-profileId(s) 获取最新更新的数据，并显示在其 ContinueWatching 行中。

实施 Continue Watching 2.0 是否需要帐号关联？

不需要帐号关联。它正在被降级，所有相关用例将由新的设备权限 API 覆盖。

跨设备同步问题

当用户同意时，“跨设备同步”意味着什么？

在用户同意“跨设备同步”后，他们正在观看的内容将保存到 Google TV 服务器，让他们可以在任何已登录设备上无缝地从上次中断的地方继续观看。未经同意，他们的观看历史记录将仅保留在当前设备上。

我们可以将“跨设备同步”设置为 false 吗？

UserConsentToSyncAcrossDevices 标志控制用户 ContinuationCluster 数据是否在他们的设备（电视、手机、平板电脑等）之间同步。如果此标志设置为 false，则继续观看仅发生在同一设备上。

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

如何在非 Android 设备上获得分享观看历史的同意？哪些数据点会从非 Android 设备分享到第三方服务器？

同意是在用户级别（个人资料或帐号级别）收集的。一旦获得同意，基于参与度的“继续观看”负载可以发送到任何地方，这样 Google 就可以在用户拥有部分或接下来参与的任何实体上，在任何设备上反映用户的普遍恢复状态（而无需在每个设备或平台上重新征求同意）。合作伙伴将发送用户的最新“继续观看”状态（根据规范），并与个人资料 ID 关联（该 ID 已存入 Android）。

用户同意是在用户级别（即配置文件或账户级别）收集的。一旦获得同意，基于用户互动情况的继续观看负载数据就可以发送到任何地方，以便 Google 能够反映用户在任何设备上的跨设备续播状态，涵盖用户曾部分参与或即将参与的所有实体（无需在每个设备或平台再次征求同意）。合作伙伴将发送用户的最新继续观看状态（根据规范），该状态与存储在 Android 上的配置文件 ID 相关联。

REST API 问题

有关于 REST API 的文档吗？

REST API 的预计推出时间是 2025 年 3 月，这已在 Continue Watching 2.0 开发者文档中注明。

旧版“接下来观看”问题

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

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

测试和集成问题

LastPlayBackPositionTimeMillis 和 duration 有什么区别？

LastPlayBackPositionTimeMillis 应反映用户停止观看时的播放时长（以毫秒为单位）（例如，10 分 5 秒为 605000 毫秒）。它绝不能大于实体的总时长。

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

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

以下是我们的 QA 为 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 帐号：妈妈，第三方帐号/个人资料：帐号 1/个人资料 1。观看内容并验证 CW 数据显示了第三方帐号 1/个人资料 1 观看的内容。

    1. TV2：Google 帐号：妈妈。验证第一个场景中的 CW 数据。现在以不同的帐号登录第三方应用。第三方帐号/个人资料：帐号 2/个人资料 2。观看内容并验证 CW 数据显示了第三方帐号 2/个人资料 2 观看的内容。

15. Google 帐号：妈妈。新设备情况/第三方应用未安装。在新设备（出厂重置设备）上，验证 CW 显示 Google 帐号上次使用的第三方应用的数据。注意：如果 GAIA 尚未与其他设备上的第三方个人资料关联，CW 行不应显示第三方内容。

    1. Google 帐号：妈妈。新设备情况/第三方应用已安装但未登录。在新设备（出厂重置设备）上，验证 CW 显示 Google 帐号上次使用的第三方应用的数据。
    2. 注意：当应用安装并登录后，CW 状态将反映登录到第三方应用的活跃第三方用户。
    3. 注意：如果 Google 帐号尚未与第三方个人资料关联，则“继续观看”行不应显示第三方内容。

我们没有看到 Google TV iOS 应用中显示“继续观看”。发生了什么？

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

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

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

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

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

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

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

如何高效更新

与其定时更新，不如利用视频播放器或应用生命周期中的事件来触发更新。例如：

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

通过遵循这些指南，您将确保高效利用资源，同时仍为用户提供无缝的“继续观看”体验。