用戶端報告工作流程啟用用戶端追蹤廣告伺服器參數原始互動查詢參數工作階段設定的功能用戶端追蹤的最佳實務使用 GetTracking 分頁廣告信標

用戶端廣告追蹤

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

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

用戶端追蹤功能如下所示：

Ad-break 倒數計時器 - 如需詳細資訊，請參閱廣告倒數計時器。
廣告點擊 – 如需詳細資訊，請參閱廣告點擊。
顯示配套廣告 - 如需詳細資訊，請參閱相配廣告。
可略過的廣告 - 如需詳細資訊，請參閱可略過的廣告。
隱私權合規的 VAST 圖示顯示 - 如需詳細資訊，請參閱 Google 為什麼使用此廣告 (WTA) 的圖示。
在廣告期間控制玩家清理 - 如需詳細資訊，請參閱擦洗。

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

用戶端報告工作流程

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

MediaTailor 用戶端報告序列圖顯示從工作階段初始化到廣告播放和信標的完整工作流程期間，影片播放器、MediaTailor、廣告決策伺服器、內容原始伺服器和廣告驗證服務之間的互動。

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

工作階段初始化 - 影片播放器傳送 POST 請求至 MediaTailor 工作階段端點，其中包含 JSON 中繼資料，包括 adsParams、原始字符和工作階段功能。MediaTailor 會以 manifestUrl和 trackingUrl 回應工作階段。
資訊清單請求和廣告決策 - 玩家向 MediaTailor 請求個人化資訊清單。MediaTailor 會從原始伺服器請求原始內容資訊清單、使用玩家參數向廣告決策伺服器 (ADS) 提出廣告請求、接收具有廣告中繼資料的 VAST 回應，以及向玩家提供具有廣告標記的個人化資訊清單。
追蹤資料擷取 - 玩家定期輪詢追蹤 URL （符合 HLS 的目標持續時間或 DASH 的最短更新期間）。MediaTailor 會傳回包含時段、廣告、追蹤事件、信標 URLs 和廣告驗證資料的 JSON 追蹤中繼資料。
廣告播放和信標 - 在廣告休息時間期間，玩家會剖析追蹤中繼資料、在廣告開始轉譯時觸發曝光信標、在適當的時間觸發四分位數信標（開始、firstQuartile、中點、thirdQuartile、完成）、載入並執行廣告驗證 JavaScript，並視需要傳送可檢視性/驗證事件給第三方驗證服務。
持續輪詢 - 播放器在整個工作階段中持續輪詢追蹤 URL，以接收即將到來的廣告休息時間和動態內容的更新中繼資料。

此工作流程可啟用進階功能，例如廣告倒數計時器、點選功能、配套廣告、可略過的廣告和 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 支援下列廣告伺服器：

Google 廣告管理員
SpringServe
FreeWheel
Publica

原始互動查詢參數

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

工作階段設定的功能

使用工作階段初始化 JSON 結構來啟用、停用或覆寫 MediaTailor 功能availSuppression，例如 overlayAvails、和 adSignaling。工作階段初始化期間傳遞的任何功能組態都會覆寫 MediaTailor 組態層級的設定。

注意

工作階段初始化時提交至 MediaTailor 的中繼資料不可變，而且無法在工作階段期間新增其他中繼資料。使用 SCTE-35 標記來攜帶工作階段期間變更的資料。如需詳細資訊，請參閱MediaTailor 工作階段變數。

範例：執行 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" 
           }
        }

報告模式參數

您可以在初始化工作階段時指定報告模式，方法是在請求內文中包含 reportingMode 參數。此參數控制 MediaTailor 是否執行工作階段的用戶端或伺服器端廣告追蹤。

client - 玩家執行廣告追蹤，並將信標傳送至廣告伺服器。如果reportingMode未指定，則此為預設模式。
server - 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"
        }

注意

reportingMode 參數是在工作階段初始化時設定，無法在工作階段期間變更。如果未指定 reportingMode ，MediaTailor 會預設為用戶端報告，以維持回溯相容性。

成功的回應是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 的最短更新期間，以便一律擁有最新的廣告追蹤中繼資料。在創作者可能具有互動式或浮水印元件的工作流程中，比對此間隔特別重要。

注意

有些玩家支援事件接聽程式，可用於替代輪詢。例如，每個工作階段都需要啟用 MediaTailor 廣告 ID 裝飾功能。如需詳細資訊，請參閱廣告 ID 裝飾。使用此功能會將日期範圍 (HLS) 或事件元素 (DASH) 識別符放在時段中的每個廣告上。玩家可以使用這些資訊清單標籤做為提示，來呼叫工作階段的 MediaTailor 追蹤端點。

VOD 工作流程

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

使用 GetTracking 分頁廣告信標

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

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

在第一次呼叫時GetTracking，會傳回資訊清單視窗中的所有可能廣告，包括每個廣告的 NextToken和值。
如果GetTracking請求不包含 NextToken，則會傳回資訊清單視窗中的所有廣告。
如果GetTracking請求包含，NextToken但沒有要傳回的新信標，MediaTailor 會傳回您在原始請求上傳送NextToken的相同值。
當沒有更多與廣告對應的信標時，會從其回應GetTracking中移除該廣告。
的權杖會在 24 小時後GetTracking過期。如果NextToken值超過 24 小時，下次呼叫會GetTracking傳回 null 值 NextToken。

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

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



https://YouMediaTailorUrl/v1/tracking
{

     "NextToken": "value"
     .
     .
     .
}

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

第一次呼叫 GetTracking。

所有廣告和信標，以及NextToken後續呼叫的第一個都會傳回。
如果的值NextToken為 null，MediaTailor 會傳回所有廣告信標。
如果 NextToken 已過期，MediaTailor 會傳回 HTTP 傳回碼 400 錯誤訊息。

對進行新的呼叫GetTracking，以擷取有效的 NextToken。
掃描整個回應，尋找所需範圍內StartTimeInSeconds廣告信標的。
對進行新的呼叫，GetTracking其值為，與所需的 NextToken相關聯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請求中，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
    }
  ]
}

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

伺服器端追蹤

廣告追蹤結構描述和屬性