本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 用戶端廣告追蹤 使用 AWS Elemental MediaTailor 用戶端追蹤 API，您可以在串流工作流程的廣告休息時間整合玩家控制。在用戶端追蹤中，玩家或用戶端會向廣告決策伺服器 (ADS) 和其他廣告驗證實體發出追蹤事件，例如曝光和四分位數廣告信標。這些事件會追蹤整個廣告休息時間狀態，以及每個休息時間內的個別廣告時段。如需印模和四分位數 (ADS) 和其他廣告驗證實體的詳細資訊。如需印模和四分位數廣告信標的詳細資訊，請參閱 [用戶端信標](ad-reporting-client-side-beaconing.md)。如需 ADS 和其他廣告驗證實體的詳細資訊，請參閱 [用戶端廣告追蹤整合](ad-reporting-client-side-ad-tracking-integrations.md)。 如需有關將玩家參數和工作階段資料傳遞至 ADS 以進行用戶端追蹤的資訊，請參閱 [ADS 請求的 MediaTailor 播放器變數](variables-player.md)和 [ADS 請求的 MediaTailor 工作階段變數](variables-session.md)。 用戶端追蹤會啟用下列功能： + Ad-break 倒數計時器 - 如需詳細資訊，請參閱 [廣告倒數計時器](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_tw/mediatailor/latest/ug/images/tracking_flow.png) 用戶端報告工作流程包含下列步驟： 1. **工作階段初始化** - 影片播放器傳送 POST 請求至 MediaTailor 工作階段端點，其中包含 JSON 中繼資料，包括 `adsParams`、原始字符和工作階段功能。MediaTailor 會以 `manifestUrl`和 `trackingUrl` 回應工作階段。 1. **資訊清單請求和廣告決策** - 玩家向 MediaTailor 請求個人化資訊清單。MediaTailor 會從原始伺服器請求原始內容資訊清單、使用玩家參數向廣告決策伺服器 (ADS) 提出廣告請求、接收具有廣告中繼資料的 VAST 回應，以及向玩家提供具有廣告標記的個人化資訊清單。 1. **追蹤資料擷取** - 玩家定期輪詢追蹤 URL （符合 HLS 的目標持續時間或 DASH 的最短更新期間）。MediaTailor 會傳回包含時段、廣告、追蹤事件、信標 URLs 和廣告驗證資料的 JSON 追蹤中繼資料。 1. **廣告播放和信標** - 在廣告休息時間期間，玩家會剖析追蹤中繼資料、在廣告開始轉譯時觸發曝光信標、在適當的時間觸發四分位數信標 （開始、firstQuartile、中點、thirdQuartile、完成）、載入並執行廣告驗證 JavaScript，並視需要傳送可檢視性/驗證事件給第三方驗證服務。 1. **持續輪詢** - 播放器在整個工作階段中持續輪詢追蹤 URL，以接收即將到來的廣告休息時間和動態內容的更新中繼資料。 此工作流程可啟用進階功能，例如廣告倒數計時器、點選功能、配套廣告、可略過的廣告和 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 在進行廣告呼叫、呼叫資訊清單的原始伺服器，以及在工作階段層級調用或停用 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 標記來攜帶工作階段期間變更的資料。如需詳細資訊，請參閱[ADS 請求的 MediaTailor 工作階段變數](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)。 ## 用戶端追蹤的最佳實務 本節概述 MediaTailor 中即時和 VOD 工作流程的用戶端追蹤最佳實務。 ### 即時工作流程 以符合 HLS 每個目標持續時間的間隔輪詢追蹤端點，或 DASH 的最短更新期間，以便一律擁有最新的廣告追蹤中繼資料。在創作者可能具有互動式或浮水印元件的工作流程中，比對此間隔特別重要。 **注意** 有些玩家支援事件接聽程式，可做為輪詢的替代方案。例如，每個工作階段都需要啟用 MediaTailor 廣告 ID 裝飾功能。如需詳細資訊，請參閱[廣告 ID 裝飾](ad-id-decoration.md)。使用此功能會將日期範圍 (HLS) 或事件元素 (DASH) 識別符放在時段中的每個廣告上。玩家可以使用這些資訊清單標籤做為提示，來呼叫工作階段的 MediaTailor 追蹤端點。 ### VOD 工作流程 成功初始化工作階段後，MediaTailor 收到第一個包含媒體的資訊清單後，您只需要呼叫追蹤端點一次。 ![VOD 工作流程的呼叫流程。在工作階段初始化且 MediaTailor 收到包含媒體的第一個資訊清單後，呼叫用戶端追蹤端點。](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/vod-workflow-best-practice.png) ### 伺服器引導廣告插入 伺服器引導廣告插入 (SGAI) 工作階段不使用 `GetTracking` API。反之，當您使用 時`aws.reportingMode=CLIENT`，MediaTailor 會在玩家請求廣告內容時，在每個資產清單回應的 `TRACKING`區段中提供追蹤資訊。工作階段初始化回應不包含 `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`，會傳回資訊清單視窗中的所有可能廣告，包括每個廣告的 `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`如下： 1. 第一次呼叫 `GetTracking`。 所有廣告和信標，以及`NextToken`後續呼叫的第一個 都會傳回。 1. 如果 的值`NextToken`為 null，MediaTailor 會傳回所有廣告信標。 1. 如果 `NextToken` 已過期，MediaTailor 會傳回 HTTP 傳回碼 400 錯誤訊息。 對 進行新的呼叫`GetTracking`，以擷取有效的 `NextToken`。 1. 掃描整個回應，尋找所需範圍內廣告信標的 `StartTimeInSeconds` 。 1. 對 進行新的呼叫，`GetTracking`其值為 與所需的 `NextToken`相關聯`StartTimeInSeconds`。 1. 如有必要，請再次循環播放傳回的廣告，直到您找到要播放的確切廣告為止。 #### 延伸範例 此範例說明如何使用 `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 } ] } ```