用戶端廣告追蹤

使用 AWS Elemental MediaTailor 用戶端追蹤 API，您可以在串流工作流程的廣告休息時間整合玩家控制。在用戶端追蹤中，玩家或用戶端會向廣告決策伺服器 (ADS) 和其他廣告驗證實體發出追蹤事件，例如曝光和四分位數廣告信標。這些事件會追蹤整個廣告休息時間狀態，以及每個休息時間內的個別廣告時段。如需印模和四分位數 (ADS) 和其他廣告驗證實體的詳細資訊。如需印模和四分位數廣告信標的詳細資訊，請參閱 用戶端信標。如需 ADS 和其他廣告驗證實體的詳細資訊，請參閱 用戶端廣告追蹤整合。

如需將玩家參數和工作階段資料傳遞至 ADS 以進行用戶端追蹤的相關資訊，請參閱 ADS 請求的 MediaTailor 播放器變數和 ADS 請求的 MediaTailor 工作階段變數。

用戶端追蹤會啟用下列功能：

使用 MediaTailor 用戶端追蹤 API，您可以將中繼資料傳送至播放裝置，除了啟用用戶端追蹤之外，還啟用 功能：

用戶端報告工作流程

下圖顯示從工作階段初始化到廣告播放和信標的完整用戶端報告工作流程：

用戶端報告工作流程包含下列步驟：

此工作流程可啟用進階功能，例如廣告倒數計時器、點擊功能、配套廣告、可略過的廣告和 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 請求範本 URL 以參考這些參數。在下列範例中， player_params.param1是 的玩家參數param1，而 player_params.param2是 的玩家參數param2。

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

廣告伺服器參數

在 JSON 結構的最上層是 adsParams JSON 物件。在此物件中是 MediaTailor 可以在所有工作階段請求中讀取和傳送到廣告伺服器的金鑰/值對。MediaTailor 支援下列廣告伺服器：

原始互動查詢參數

JSON 結構最上層內的任何預留金鑰/值對，例如 adsParams、 availSuppression和 overlayAvails，都不會以查詢參數的形式新增至原始伺服器請求 URL。MediaTailor 對原始伺服器提出的每個工作階段資訊清單請求都包含這些查詢參數。原始伺服器會忽略不必要的查詢參數。例如，MediaTailor 可以使用金鑰/值對將存取權杖傳送至原始伺服器。

工作階段設定的功能

使用工作階段初始化 JSON 結構來啟用、停用或覆寫 MediaTailor 功能availSuppression，例如 overlayAvails、 和 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 物件。這些值是玩家可用於播放和廣告事件追蹤目的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"
}

如需用戶端追蹤結構描述的詳細資訊，請參閱 用戶端廣告追蹤結構描述和屬性。

用戶端追蹤的最佳實務

本節概述 MediaTailor 中即時和 VOD 工作流程的用戶端追蹤最佳實務。

即時工作流程

以與 HLS 的每個目標持續時間或 DASH 的最短更新期間相符的間隔輪詢追蹤端點，以永遠擁有最新的廣告追蹤中繼資料。在創作者可能具有互動式或浮水印元件的工作流程中，符合此間隔特別重要。

VOD 工作流程

成功初始化工作階段後，MediaTailor 收到第一個包含媒體的資訊清單後，您只需要呼叫追蹤端點一次。

伺服器引導廣告插入

伺服器引導廣告插入 (SGAI) 工作階段不使用 GetTracking API。相反地，當玩家請求廣告內容時，追蹤資訊會在每個資產清單回應的 TRACKING區段中提供。

實作 SGAI 方法的用戶端追蹤時：

使用 GetTracking 分頁廣告信標

使用GetTracking端點來縮小傳回給玩家的廣告數量。例如，如果資訊清單視窗很寬，跨越許多時間，傳回的廣告信標數量可能會影響玩家效能。

GetTracking 傳回一個NextToken值，您可以透過分頁傳回的信標清單來縮小傳回信標的數量。您可以循環瀏覽這些NextToken值，以尋找廣告信標StartTimeInSeconds欄位的所需值。

從玩家進行 GetTracking 的廣義呼叫序列

從用戶端播放器，GetTracking請求是具有請求內文的 POST，其中包含與字符相關的 NextToken 和廣告和信標。

https://YouMediaTailorUrl/v1/tracking
{

     "NextToken": "value"
     .
     .
     .
}      
    

GetTracking 搭配 使用 的一般順序NextToken如下：

延伸範例

此範例示範如何使用 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請求中，MediaTailor 會以 NextToken值回應：JF57ITe48t1441mv7TmLKuZLroxDzfIslp6BiSNL1IJmzPVMDN0lqrBYycgMbKEb。

MediaTailor 回應的廣告和信標與上一個呼叫NextToken的 中StartTimeInSeconds設定的 相符。

假設現在回應包含 ID 為 9235407 的另一個廣告，以及 ID 為 9935407 的上一個廣告。廣告 ID 9235407 的信標具有 132.41 StartTimeInSeconds和 70.339。

MediaTailor 會逐一查看工作階段中的所有信標，從 ID 為 9235407 的廣告中選取StartTimeInSeconds大於 52.286 秒的信標 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
    }
  ]
}