启用客户端跟踪广告服务器参数源站交互查询参数会话配置的功能客户端跟踪的最佳实践通过广告信标进行寻呼 GetTracking

客户端广告跟踪

使用 AWS Elemental MediaTailor 客户端跟踪API，你可以在直播工作流程中加入广告中断期间的播放器控件。在客户端跟踪中，玩家或客户端向广告决策服务器 (ADS) 和其他广告验证实体发送跟踪事件，例如展示次数和四分位数广告信标。有关展示次数和四分位数广告信标的更多信息，请参阅。客户端信标有关ADS和其他广告验证实体的更多信息，请参阅。客户端广告跟踪集成

客户端跟踪支持以下功能：

广告时段倒计时器-有关更多信息，请参阅。广告倒计时器
广告点击量-有关更多信息，请参阅。广告点击
展示随播广告-有关更多信息，请参阅配套广告。
可跳过的广告-有关更多信息，请参阅。可跳过的广告
显示隐私合规性VAST图标-有关更多信息，请参阅Google 的图标为什么是这个广告 (WTA)。
控制广告期间玩家的擦洗-有关更多信息，请参阅擦洗。

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

主题

启用客户端跟踪

您可以为每个会话启用客户端跟踪。玩家创建 MediaTailor 配置的HTTPPOST会话初始化前缀端点。或者，玩家可以发送其他元数据， 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请求模板URL以引用这些参数。在以下示例中，player_params.param1是的玩家参数param1，player_params.param2是的玩家参数param2。


https://my.ads.com/path?param1=[player_params.param1]&param2=[player_params.param2]

广告服务器参数

JSON结构的最顶层是一个adsParamsJSON对象。该对象内部有键/值对， MediaTailor 可以在所有会话请求中读取并发送到广告服务器。 MediaTailor 支持以下广告服务器：

谷歌广告管理器
SpringServe
FreeWheel
Publica

源站交互查询参数

JSON结构最顶层中的任何保留键/值对（例如adParamsavailSuppressionoverlayAvails、和）都不会以查询参数的形式添加到原始请求URL中。向源发出的 MediaTailor 每个会话清单请求都包含这些查询参数。Origin 会忽略多余的查询参数。例如， MediaTailor 可以使用键/值对将访问令牌发送到源。

会话配置的功能

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

注意

MediaTailor 在会话初始化时提交的元数据是不可变的，并且在会话期间无法添加其他元数据。使用 SCTE -35 个标记来携带会话期间发生变化的数据。有关更多信息，请参阅使用会话变量。

例 : 对以下各项进行客户端广告跟踪 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"                     
           }
        }

例 : 对以下各项进行客户端广告跟踪 DASH


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

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

成功的响应是HTTP200带有响应主体的响应。正文包含一个带有 a manifestUrl 和 trackingUrl key 的JSON对象。这些值是玩家可用于播放和广告事件跟踪目的的相对URLs值。


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

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

客户端跟踪的最佳实践

本节概述了在实时和VOD工作流程中 MediaTailor 进行客户端跟踪的最佳实践。

实时工作流程

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

注意

有些玩家支持事件监听器，这可以用作投票的替代方案。例如，需要为每个会话启用 MediaTailor 广告 ID 装饰功能。有关更多信息，请参阅广告 ID 装饰。使用此功能可在每个广告上添加日期范围 (HLSDASH) 或事件元素 () 标识符。玩家可以使用这些清单标签作为提示，为会话调用 MediaTailor 跟踪端点。

VOD工作流程

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

工作流程的呼叫VOD流程。在会话初始化并 MediaTailor 收到第一个包含媒体的清单后，调用客户端跟踪端点。

通过广告信标进行寻呼 GetTracking

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

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

在第一次调用GetTracking时，将返回所有可能落在清单窗口中的广告，包括每个广告的 a NextToken 和值。
如果GetTracking请求不包含 aNextToken，则会返回清单窗口中的所有广告。
如果GetTracking请求包含NextToken但没有新的信标可返 MediaTailor 回，则返回与您在原始请求中发送NextToken的信标相同的值。
当不再有与广告对应的信标时，GetTracking会将该广告从其响应中移除。
代币将在 24 小时后GetTracking过期。如果NextToken值大于 24 小时，则下一次调用将GetTracking返回空值NextToken。

GetTracking 来自玩家的广义调用顺序

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



https://YouMediaTailorUrl/v1/tracking
{

     "NextToken": "value"
     .
     .
     .
}

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

拨打第一个电话GetTracking。

将返回所有广告和信标以及后续调NextToken用的第一个广告和信标。
如果的值为空，NextToken则 MediaTailor 返回所有广告信标。
如果已过期，NextToken则 MediaTailor 返回一条HTTP返回代码 400 的错误消息。

重新调用GetTracking以检索有效的 NextToken s。
扫描整个响应，StartTimeInSeconds找到位于所需范围内的广告信标。
使用与所需值GetTrackingNextToken关联的值对进行新调用StartTimeInSeconds。
如有必要，请再次浏览返回的广告，直到找到想要播放的确切广告。

扩展示例

此示例说明如何使用GetTracking限制返回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 响应：JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0 lqrBYycg M bKEb。

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

假设现在响应中除了上一则编号为 9935407 的广告之外，还包括另一则编号为 9235407 的广告。广告编号为 9235407 的信标有 StartTimeInSeconds s 132.41 和 70.339，如下图所示。

用于按GetTrackingAPI端点处理的多个广告示例，每个广告都有多个广告信标

MediaTailor 遍历会话中的所有信标，以选择StartTimeInSeconds大于 52.286 秒的信标，它们是广告中编号为 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
    }
  ]
}

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

服务器端跟踪

广告跟踪架构和属性