Client-side 广告追踪

使用 AWS Elemental MediaTailor 客户端跟踪 API，您可以在直播工作流程中加入广告插播期间的玩家控件。在客户端跟踪中，玩家或客户向广告决策服务器 (ADS) 和其他广告验证实体发出跟踪事件，例如曝光量和四分位数广告信标。这些事件既跟踪整体广告时段状态，也跟踪每个广告插播时间内的单个广告的可用性。了解有关曝光量和四分位数 (ADS) 和其他广告验证实体的更多信息。有关曝光量和四分位数广告信标的更多信息，请参阅。Client-side 信标有关 ADS 和其他广告验证实体的更多信息，请参阅Client-side 广告跟踪集成。

有关向 ADS 传递玩家参数和会话数据以进行客户端跟踪的信息，请参阅MediaTailor ADS 请求的玩家变量和。MediaTailor ADS 请求的会话变量

Client-side 跟踪启用了如下功能：

使用 MediaTailor 客户端跟踪 API，您可以向播放设备发送元数据，该设备除了支持客户端跟踪之外还能启用其他功能：

Client-side 报告工作流程

下图显示了从会话初始化到广告播放和信标的完整客户端报告工作流程：

客户端报告工作流程包括以下步骤：

该工作流程支持广告倒计时器、点击功能、伴随广告、可跳过广告和 VAST 图标显示等高级功能，以实现隐私合规。

启用客户端跟踪

您可以为每个会话启用客户端跟踪。玩家POST向 MediaTailor 配置的会话初始化前缀端点创建 HTTP。或者，玩家可以发送额外的元数据， MediaTailor 以便在进行广告调用、调用源以获取清单以及在会话级别调用或禁用 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 结构的最顶层是一个 J adsParams SON 对象。该对象内部有 key/value 几对， MediaTailor 可以在所有会话请求中读取并发送到广告服务器。 MediaTailor 支持以下广告服务器：

Origin 交互查询参数

JSON 结构最顶层的任何预留 key/value 对，例如adsParamsavailSuppressionoverlayAvails、和，都不会以查询参数的形式添加到原始请求网址中。向源发出的 MediaTailor 每个会话清单请求都包含这些查询参数。源会忽略无关的查询参数。例如， MediaTailor 可以使用这些 key/value 对向源发送访问令牌。

Session-configured features

使用会话初始化 JSON 结构来启用、禁用或覆盖overlayAvailsavailSuppression、和等 MediaTailor功能。adSignaling会话初始化期间传递的任何功能配置都会覆盖 MediaTailor 配置级别的设置。

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"                     
           }
        }

POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.mpd

        {
            "adsParams": {
               "deviceType": "androidmobile",
               "uid": "xjhhddli-9189901-uic" 
           }
        }

报告模式参数

通过在请求正文中加入reportingMode参数，可以在初始化会话时指定报告模式。此参数控制是 MediaTailor 对会话执行客户端还是服务器端广告跟踪。

POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.m3u8

        {
            "adsParams": {
               "deviceType": "ipad",
               "uid": "abdgfdyei-2283004-ueu"                     
           },
           "reportingMode": "server"
        }

POST mediatailorURL/v1/session/hashed-account-id/origin-id/asset-id.mpd

        {
            "adsParams": {
               "deviceType": "androidmobile",
               "uid": "xjhhddli-9189901-uic" 
           },
           "reportingMode": "client"
        }

成功的响应是200带有响应正文的 HTTP。正文包含一个带有manifestUrl和trackingUrl密钥的 JSON 对象。这些值是相对网址，玩家可以将其用于播放和广告事件跟踪目的。

{
  "manifestUrl": "/v1/dashmaster/hashed-account-id/origin-id/asset-id.m3u8?aws.sessionId=session-id",
  "trackingUrl": "/v1/tracking/hashed-account-id/origin-id/session-id"
}

有关客户端跟踪架构的更多信息，请参阅。Client-side 广告跟踪架构和属性

客户端跟踪的最佳实践

本节概述了直播和视频点播（VOD） MediaTailor 工作流程中客户端跟踪的最佳实践。

直播工作流程

按照与 HLS 的每个目标持续时间或 DASH 的最小更新周期相匹配的间隔对跟踪端点进行轮询，以便始终获得最新的广告跟踪元数据。在创意人员可能具有交互式或叠加组件的工作流程中，匹配此间隔尤为重要。

VOD 工作流程

成功初始化会话后，在 MediaTailor 收到第一个包含媒体的清单后，您只需要调用一次跟踪端点。

Server-guided 广告插入

Server-guided 广告插入 (SGAI) 会话不使用 GetTracking API。取而代之的是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 方法实现客户端跟踪时：

使用以下方式浏览广告信标 GetTracking

使用终GetTracking端节点缩小向玩家返回的广告数量。例如，如果清单窗口很宽，跨越很长时间，则返回的广告信标的数量可能会影响玩家的表现。

GetTracking返回一个NextToken值，您可以使用该值通过浏览返回的信标列表来缩小返回信标的数量。您可以循环浏览这些NextToken值，找到广告信标StartTimeInSeconds字段的所需值。

GetTracking 来自玩家的通用调用顺序

来自客户端玩家的GetTracking请求是一个 POST，其请求正文包含与令牌相关的广告NextToken和信标。

https://YouMediaTailorUrl/v1/tracking
{

     "NextToken": "value"
     .
     .
     .
}      
    

GetTracking与一起使用的一般顺序NextToken如下：

扩展示例

此示例说明如何使用 GetTracking's NextToken 来限制返回给玩家的广告信标的数量。

MediaTailor 收到GetTracking请求。该响应包含一个 ID 为 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 响应 JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb。

MediaTailor 使用与上次通话中设置的StartTimeInSeconds广告和信标相匹配NextToken的广告和信标进行响应。

假设现在的响应中除了之前的 ID 为 9935407 的广告外，还包括另一个 ID 为 9235407 的广告。ID 为 9235407 的信标有 StartTimeInSeconds s 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
    }
  ]
}