本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 客户端广告跟踪 使用 AWS Elemental MediaTailor 客户端跟踪 API，您可以在直播工作流程中加入广告时段的播放器控件。在客户端跟踪中，玩家或客户端向广告决策服务器 (ADS) 和其他广告验证实体发送跟踪事件，例如展示次数和四分位数广告信标。这些事件既跟踪整体广告中断状态，也跟踪每个广告间隔时间内的单个广告投放情况。有关展示次数和四分位数 (ADS) 以及其他广告验证实体的更多信息。有关展示次数和四分位数广告信标的更多信息，请参阅。[客户端信标](ad-reporting-client-side-beaconing.md)有关 ADS 和其他广告验证实体的更多信息，请参阅。[客户端广告跟踪集成](ad-reporting-client-side-ad-tracking-integrations.md) 有关将玩家参数和会话数据传递给 ADS 以进行客户端跟踪的信息，请参阅[MediaTailor ADS 请求的玩家变量](variables-player.md)和[MediaTailor ADS 请求的会话变量](variables-session.md)。 客户端跟踪支持以下功能： + 广告时段倒计时器-有关更多信息，请参阅。[广告倒计时器](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer) + 广告点击量-有关更多信息，请参阅。[广告点击](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough) + 展示随播广告-有关更多信息，请参阅[配套广告](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads)。 + 可跳过的广告-有关更多信息，请参阅。[可跳过的广告](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads) + 显示 VAST 图标以实现隐私合规性-有关更多信息，请参阅[Google 的图标为什么是这个广告 (WTA)](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta)。 + 控制广告期间玩家的擦洗-有关更多信息，请参阅[擦洗](ad-reporting-client-side-ad-tracking-schema-player-controls.md#ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing)。 使用 MediaTailor 客户端跟踪 API，除了客户端跟踪之外，您还可以将元数据发送到启用其他功能的播放设备： ## 客户端报告工作流程 下图显示了从会话初始化到广告播放和信标设置的完整客户端报告工作流程： ![MediaTailor 客户端报告序列图，显示了从会话初始化到广告播放和信标的整个工作流程中，视频播放器、广告决策服务器、内容来源和广告验证服务之间的互动。 MediaTailor](http://docs.aws.amazon.com/zh_cn/mediatailor/latest/ug/images/tracking_flow.png) 客户端报告工作流程包括以下步骤： 1. **会话初始化**-视频播放器向会 MediaTailor 话端点发送 POST 请求，其中包含 JSON 元数据`adsParams`，包括原始令牌和会话功能。 MediaTailor 用`manifestUrl`和对会话`trackingUrl`进行响应。 1. **清单请求和广告决策**-玩家从中请求个性化清单 MediaTailor。 MediaTailor 从来源请求原始内容清单，使用玩家参数向广告决策服务器 (ADS) 发出广告请求，接收包含广告元数据的 VAST 响应，并向玩家提供带有广告标记的个性化清单。 1. **跟踪数据检索**-玩家定期轮询跟踪网址（匹配HLS的目标持续时间或达世币的最小更新周期）。 MediaTailor 返回 JSON 跟踪元数据，其中包含可用信息、广告、跟踪事件 URLs、信标和广告验证数据。 1. **广告播放和信标-在广告中断期间，玩家解析跟踪元数据，在广告开始呈现时触发曝光信标，在适当的时间发射四分**位数信标（开始、firstQuartile、midpoint、thirdQuartile、完成），必要时加载和执行广告验证，并将事件发送到第三方验证服务。 JavaScript viewability/verification 1. **持续轮询**-玩家在整个会话中继续轮询跟踪网址，以接收有关即将推出的广告时段和动态内容的更新元数据。 此工作流程支持高级功能，例如广告倒计时计时器、点击功能、配套广告、可跳过的广告和符合隐私要求的 VAST 图标显示。 **Topics** + [客户端报告工作流程](#ad-reporting-client-side-workflow) + [启用客户端跟踪](#ad-reporting-client-side-enabling) + [广告服务器参数](#ad-reporting-client-side-ad-server-parameters) + [源站交互查询参数](#ad-reporting-client-side-origin-interaction-query-parameters) + [会话配置的功能](#ad-reporting-client-side-session-configured-features) + [客户端跟踪的最佳实践](#ad-reporting-client-side-best-practices) + [客户端广告跟踪架构和属性](ad-reporting-client-side-ad-tracking-schema.md) + [广告追踪活动时机](ad-reporting-client-side-ad-tracking-schema-activity-timing.md) + [用于客户端广告跟踪的玩家控制和功能](ad-reporting-client-side-ad-tracking-schema-player-controls.md) + [客户端信标](ad-reporting-client-side-beaconing.md) + [带有服务器端广告信标的混合模式](ad-reporting-hybrid-mode.md) + [客户端广告跟踪集成](ad-reporting-client-side-ad-tracking-integrations.md) + [通过广告信标进行寻呼 GetTracking](#gettracking) ## 启用客户端跟踪 您可以为每个会话启用客户端跟踪。玩家`POST`向 MediaTailor 配置的会话初始化前缀端点创建 HTTP。或者，玩家可以发送其他元数据， MediaTailor 以便在进行广告调用、调用 Origin 获取清单以及在会话级别调用或禁用 MediaTailor功能时使用。 以下示例显示了 JSON 元数据的结构： ``` { "adsParams": { # 'adsParams' is case sensitive "param1": "value1", # key is not case sensitive "param2": "value2", # Values can contain spaces. For example, 'value 2' is an allowed value. }, "origin_access_token":"abc123", # this is an example of a query parameter designated for the origin "overlayAvails":"on" # 'overlayAvails' is case sensitive. This is an example of a feature that is enabled at the session level. } ``` 使用 MediaTailor 控制台或 API 配置 ADS 请求模板网址以引用这些参数。在以下示例中，`player_params.param1`是的玩家参数`param1`，`player_params.param2`是的玩家参数`param2`。 ``` https://my.ads.com/path?{{param1=[player_params.param1]}}&{{param2=[player_params.param2]}} ``` ## 广告服务器参数 JSON 结构的最顶层是一个 JS `adsParams` ON 对象。该对象内部有 MediaTailor 可以读取所有会话请求并将其发送到广告服务器的 key/value 配对。 MediaTailor 支持以下广告服务器： + 谷歌广告管理器 + SpringServe + FreeWheel + Publica ## 源站交互查询参数 JSON 结构最顶层中的任何保留 key/value 对（例如`adsParams``availSuppression``overlayAvails`、和）都不会以查询参数的形式添加到原始请求网址中。向源发出的 MediaTailor 每个会话清单请求都包含这些查询参数。Origin 会忽略多余的查询参数。例如， MediaTailor 可以使用 key/value 配对将访问令牌发送到源。 ## 会话配置的功能 使用会话初始化 JSON 结构启用、禁用或覆盖诸如`overlayAvails``availSuppression`、和之类的 MediaTailor功能。`adSignaling`会话初始化期间传递的任何功能配置都会覆盖 MediaTailor 配置级别的设置。 **注意** MediaTailor 在会话初始化时提交的元数据是不可变的，并且在会话期间无法添加其他元数据。使用 SCTE-35 标记来携带会话期间发生变化的数据。有关更多信息，请参阅 [MediaTailor ADS 请求的会话变量](variables-session.md)。 **Example : 为 HLS 执行客户端广告跟踪** ``` POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8 { "adsParams": { "deviceType": "ipad" # This value does not change during the session. "uid": "abdgfdyei-2283004-ueu" } } ``` **Example : 对 DASH 执行客户端广告跟踪** ``` POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.mpd { "adsParams": { "deviceType": "androidmobile", "uid": "xjhhddli-9189901-uic" } } ``` ### 报告模式参数 在初始化会话时，您可以通过在请求正文中包含`reportingMode`参数来指定报告模式。此参数控制 MediaTailor 对会话执行客户端广告跟踪还是服务器端广告跟踪。 + `client`-玩家执行广告跟踪并向广告服务器发送信标。如果未指定，则`reportingMode`这是默认模式。 + `server`- MediaTailor 执行服务器端广告跟踪并将信标直接发送到广告服务器。 **Example 服务器端报告模式下的会话初始化** ``` POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8 { "adsParams": { "deviceType": "ipad", "uid": "abdgfdyei-2283004-ueu" }, "reportingMode": "server" } ``` **Example 使用客户端报告模式进行会话初始化（显式）** ``` POST {{mediatailorURL}}/v1/session/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.mpd { "adsParams": { "deviceType": "androidmobile", "uid": "xjhhddli-9189901-uic" }, "reportingMode": "client" } ``` **注意** 该`reportingMode`参数是在会话初始化时设置的，不能在会话期间更改。如果未指定，`reportingMode`则 MediaTailor 默认为客户端报告以保持向后兼容性。 成功的响应是`200`带有响应正文的 HTTP。正文包含一个带有`manifestUrl`和`trackingUrl`密钥的 JSON 对象。这些值是玩家可用于播放和广告事件跟踪目的的相对 URLs 值。 ``` { "manifestUrl": "/v1/{{dash}}{{master}}/{{hashed-account-id}}/{{origin-id}}/{{asset-id}}.m3u8?aws.sessionId={{session-id}}", "trackingUrl": "/v1/tracking/{{hashed-account-id}}/{{origin-id}}/{{session-id}}" } ``` 有关客户端跟踪架构的更多信息，请参阅[客户端广告跟踪架构和属性](ad-reporting-client-side-ad-tracking-schema.md)。 ## 客户端跟踪的最佳实践 本节概述了直播和 VOD MediaTailor 工作流程中客户端跟踪的最佳实践。 ### 实时工作流程 按照与 HLS 的每个目标持续时间或 DASH 的最短更新周期相匹配的时间间隔对跟踪端点进行轮询，以便始终获得最新的广告跟踪元数据。在广告素材可能包含交互式或叠加组件的工作流程中，匹配此间隔尤其重要。 **注意** 有些玩家支持事件监听器，这可以用作投票的替代方案。例如，需要为每个会话启用 MediaTailor 广告 ID 装饰功能。有关更多信息，请参阅 [广告 ID 装饰](ad-id-decoration.md)。使用此功能可以在每个广告上添加日期范围 (HLS) 或事件元素 (DASH) 标识符。玩家可以使用这些清单标签作为提示，为会话调用 MediaTailor跟踪端点。 ### VOD 工作流程 成功初始化会话后，在 MediaTailor 收到第一个包含媒体的清单后，您只需调用一次跟踪端点即可。 ![VOD 工作流程的呼叫流程。在会话初始化并 MediaTailor 收到第一个包含媒体的清单后，调用客户端跟踪端点。](http://docs.aws.amazon.com/zh_cn/mediatailor/latest/ug/images/vod-workflow-best-practice.png) ### 服务器引导的广告插入 服务器引导式广告插入 (SGAI) 会话不使用 API。`GetTracking`相反，当你使用时`aws.reportingMode=CLIENT`，当玩家请求广告内容时，会在每个素材资源列表响应的`TRACKING`部分 MediaTailor提供跟踪信息。会话初始化响应不包括`trackingUrl`。 客户端跟踪的 SGAI 会话的资产列表响应具有以下结构： ``` { "ASSETS": [ { "DURATION": 20.0, "URI": "https://cdn.example.com/ad1/master.m3u8" }, { "DURATION": 10.0, "URI": "https://cdn.example.com/ad2/master.m3u8" } ], "TRACKING": { ...VAST tracking events and beacon URLs for each ad... } } ``` 在 SGAI 方法实现客户端跟踪时： + 从资产列表响应中解析该`TRACKING`部分，而不是调用 `GetTracking` + 使用素材资源列表中 URLs 提供的跟踪信息来报告广告事件 + 根据玩家中的实际广告播放事件发射追踪信标 + 在获取素材资源列表时独立处理每个广告插播时间的跟踪 **重要** 只有在设置后`aws.reportingMode=CLIENT`，该`TRACKING`部分才会包含在资产列表中。使用服务器端报告（SGAI 的默认设置）时，会省 MediaTailor 略该`TRACKING`栏目，改为在广告中嵌入信标数据。 URIs 有关更多信息，请参阅 [使用服务器引导广告插入 (SGAI) 进行服务器端跟踪](ad-reporting-server-side-sgai.md)。 ## 通过广告信标进行寻呼 GetTracking 使用`GetTracking`端点缩小向玩家返回的广告数量。例如，如果清单窗口很宽，跨越很长时间，则返回的广告信标数量可能会影响玩家的表现。 `GetTracking`返回一个`NextToken`值，您可以使用该值通过分页浏览返回的信标列表来缩小返回的信标数量。您可以循环浏览这些`NextToken`值，找到广告信标`StartTimeInSeconds`字段的所需值。 + 在第一次调用`GetTracking`时，将返回所有可能落在清单窗口中的广告，包括每个广告的 a `NextToken` 和值。 + 如果`GetTracking`请求*不*包含 a`NextToken`，则会返回清单窗口中的所有广告。 + 如果`GetTracking`请求包含`NextToken`但没有新的信标可返 MediaTailor 回，则返回与您在原始请求中发送`NextToken`的信标相同的值。 + 当不再有与广告对应的信标时，`GetTracking`会将该广告从其响应中移除。 + 代币将在 24 小时后`GetTracking`过期。如果`NextToken`值大于 24 小时，则下一次调用将`GetTracking`返回空值`NextToken`。 ### GetTracking 来自玩家的广义调用顺序 来自客户端玩家的`GetTracking`请求是一个 POST，其请求正文包含与令牌相关的广告`NextToken`和信标。 ``` https://YouMediaTailorUrl/v1/tracking { "NextToken": "value" . . . } ``` `GetTracking`与一起使用的一般顺序`NextToken`如下： 1. 拨打第一个电话`GetTracking`。 将返回所有广告和信标以及后续调`NextToken`用的第一个广告和信标。 1. 如果的值为空，`NextToken`则 MediaTailor 返回所有广告信标。 1. 如果已过期，`NextToken`则 MediaTailor 返回一条 HTTP 返回码 400 错误消息。 重新调用`GetTracking`以检索有效的 `NextToken` s。 1. 扫描整个响应，`StartTimeInSeconds`找到位于所需范围内的广告信标。 1. 使用与所需值`GetTracking``NextToken`关联的值对进行新调用`StartTimeInSeconds`。 1. 如有必要，请再次浏览返回的广告，直到找到想要播放的确切广告。 #### 扩展示例 此示例说明如何使用`GetTracking`限制返回`NextToken`给玩家的广告信标的数量。 MediaTailor 收到`GetTracking`请求。响应中包含一个标识为 9935407 的广告和两个`StartTimeInSeconds`值分别为 52.286 和 48.332 秒的信标。 MediaTailor 发送 JSON 响应`NextToken`，如下所示： ``` { "NextToken": JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb "avails": [ { "ads": [ { "adId": "9935407", "adVerifications": [], "companionAds": [], "creativeId": "", "creativeSequence": "", "duration": "PT15S", "durationInSeconds": 15, "extensions": [], "mediaFiles": { "mediaFilesList": [], "mezzanine": "" }, "startTime": "PT30S", "StartTimeInSeconds": 45, "trackingEvents": [ { "beaconUrls": [ "http://adserver.com/tracking?event=Impression " ], "duration": "PT0S", "durationInSeconds": 0, "eventId": "9935414", "eventType": "secondQuartile", "startTime": "PT52.286S", "StartTimeInSeconds": 52.286 }, { "beaconUrls": [ "http://adserver.com/tracking?event=firstQuartile" ], "duration": "PT0S", "durationInSeconds": 0, "eventId": "9935412", "eventType": "firstQuartile", "startTime": "PT48.332S", "StartTimeInSeconds": 48.332 } ], "vastAdId": "" } ], "startTime": "PT46.47S", "StartTimeInSeconds": 46.47 } ] } ``` 在下一个`GetTracking`请求中，使用以下`NextToken`值进行 MediaTailor 响应： JF57ITe48t1441mv7Tm LKu ZLrox DzfIslp 6Bi SNL1 IJmz PVMDN0lqr BYycg Mb KEb。 MediaTailor 使用与上次通话中设置的`StartTimeInSeconds`广告和信标相匹配`NextToken`的广告和信标进行响应。 假设现在响应中除了上一则编号为 9935407 的广告之外，还包括另一则编号为 9235407 的广告。广告编号为 9235407 的信标有 `StartTimeInSeconds` 132.41 和 70.339。 MediaTailor 遍历会话中的所有信标，以选择`StartTimeInSeconds`大于 52.286 秒的信标，即广告中 ID 为 9235407 的信标 3 和信标 4： ``` { "NextToken": ZkfknvbfsdgfbsDFRdffg12EdffecFRvhjyjfhdfhnjtsg5SDGN "avails": [ { "ads": [ { "adId": "9235407", "adVerifications": [], "companionAds": [], "creativeId": "", "creativeSequence": "", "duration": "PT15.816S", "durationInSeconds": 19.716, "extensions": [], "mediaFiles": { "mediaFilesList": [], "mezzanine": "" }, "startTime": "PT2M0S", "StartTimeInSeconds": 120.0, "trackingEvents": [ { "beaconUrls": [ "http://adserver.com/tracking?event=complete" ], "duration": "PT0S", "durationInSeconds": 0, "eventId": "8935414", "eventType": "firstQuartile", "startTime": "PT1M10.330S", "StartTimeInSeconds": 70.339 }, { "beaconUrls": [ "http://adserver.com/tracking?event=thirdQuartile" ], "duration": "PT0S", "durationInSeconds": 0, "eventId": "8935412", "eventType": "secondQuartile", "startTime": "PT2M12.41S", "StartTimeInSeconds": 132.41 } ], "vastAdId": "" }, ], "startTime": "PT36.47S", "StartTimeInSeconds": 36.47 } ] } ```