本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 用戶端廣告追蹤
<a name="ad-reporting-client-side"></a>

使用 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，您可以將中繼資料傳送至播放裝置，以啟用用戶端追蹤以外的功能：

## 用戶端報告工作流程
<a name="ad-reporting-client-side-workflow"></a>

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

![\[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)

## 啟用用戶端追蹤
<a name="ad-reporting-client-side-enabling"></a>

您可以為每個工作階段啟用用戶端追蹤。播放器會對 `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]
```

## 廣告伺服器參數
<a name="ad-reporting-client-side-ad-server-parameters"></a>

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

## 原始互動查詢參數
<a name="ad-reporting-client-side-origin-interaction-query-parameters"></a>

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

## 工作階段設定的功能
<a name="ad-reporting-client-side-session-configured-features"></a>

使用工作階段初始化 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" 
           }
        }
```

### 報告模式參數
<a name="session-initialization-reporting-mode"></a>

您可以在初始化工作階段時指定報告模式，方法是在請求內文中包含 `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/dashmaster/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)。

## 用戶端追蹤的最佳實務
<a name="ad-reporting-client-side-best-practices"></a>

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

### 即時工作流程
<a name="ad-reporting-client-side-best-practices-live"></a>

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

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

### VOD 工作流程
<a name="ad-reporting-client-side-best-practices-vod"></a>

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

![\[VOD 工作流程的呼叫流程。在工作階段初始化且 MediaTailor 收到包含媒體的第一個資訊清單後，呼叫用戶端追蹤端點。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/vod-workflow-best-practice.png)


### 伺服器引導廣告插入
<a name="ad-reporting-client-side-best-practices-sgai"></a>

伺服器引導廣告插入 (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)。

# 用戶端廣告追蹤結構描述和屬性
<a name="ad-reporting-client-side-ad-tracking-schema"></a>

使用 MediaTailor 用戶端廣告追蹤功能，您可以將詳細的用戶端廣告追蹤資料整合到您的玩家環境。下列各節涵蓋整體廣告追蹤結構描述，以及構成結構描述的特定屬性和值。

## 結構描述
<a name="ad-reporting-client-side-ad-tracking-schema-table"></a>

下列 JSON 結構顯示 MediaTailor 用戶端廣告追蹤結構描述。此表示式說明結構描述的巢狀結構，以協助您了解不同部分之間的關係。

如需每個屬性的詳細資訊，請參閱 [Properties](#ad-reporting-client-side-ad-tracking-schema-properties)。

```
{
  "avails": [
    {
      "ads": [
        {
          "adID": "string",
          "adParameters": "string",
          "adSystem": "string",
          "adTitle": "string",
          "adVerifications": [
            {
              "executableResource": [
                {
                  "apiFramework": "string",
                  "type": "string",
                  "uri": "string",
                  "language": "string"
                }
              ],
              "javaScriptResource": [
                {
                  "apiFramework": "string",
                  "browserOptional": "string",
                  "uri": "string"
                }
              ],
              "trackingEvents": [
                {
                  "event": "string",
                  "uri": "string"
                }
              ],
              "vendor": "string",
              "verificationParameters": "string"
            }
          ],
          "companionAds": [
            {
              "adParameters": "string",
              "altText": "string",
              "attributes": {
                "adSlotId": "string",
                "apiFramework": "string",
                "assetHeight": "string",
                "assetWidth": "string",
                "expandedHeight": "string",
                "expandedWidth": "string",
                "height": "string",
                "id": "string",
                "pxratio": "string",
                "renderingMode": "string",
                "width": "string"
              },
              "companionClickThrough": "string",
              "companionClickTracking": "string",
              "htmlResource": "string",
              "iFrameResource": "string",
              "sequence": "string",
              "staticResource": "string",
              "trackingEvents": [
                {
                  "event": "string",
                  "uri": "string"
                }
              ]
            }
          ],
          "creativeId": "string",
          "creativeSequence": "string",
          "duration": "string",
          "durationInSeconds": number,
          "extensions": [
            {
              "type": "string",
              "content": "string"
            }
          ],
          "icons": [
            {
              "attributes": {
                "apiFramework": "string",
                "duration": "string",
                "height": "string",
                "offset": "string",
                "program": "string",
                "pxratio": "string",
                "width": "string",
                "xPosition": "string",
                "yPosition": "string"
              },
              "htmlResource": "string",
              "iconClicks": {
                "iconClickThrough": "string",
                "iconClickTracking": {
                  "id": "string"
                },
                "iconClickFallbackImages": [
                  {
                    "altText": "string",
                    "height": "string",
                    "width": "string",
                    "staticResource": {
                      "creativeType": "string",
                      "uri": "string"
                    }
                  }
                ]
              },
              "iconViewTracking": "string",
              "iFrameResource": "string",
              "staticResource": {
                "creativeType": "string",
                "uri": "string"
              }
            }
          ],
          "mediaFiles": {
            "adParameters": "string",
            "duration": "string",
            "durationInSeconds": number,
            "mediaFilesList": [
              {
                "apiFramework": "string",
                "delivery": "string",
                "height": "string",
                "maintainAspectRatio": "string",
                "mediaFileUri": "string",
                "mediaType": "string",
                "scalable": "string",
                "width": "string",
                "bitrate": "string"
              }
            ],
            "mezzanine": "string",
            "startTime": "string",
            "startTimeInSeconds": number,
            "trackingEvents": [
              {
                "beaconUrls": ["string"],
                "duration": "string",
                "durationInSeconds": number,
                "dateTime": "string",
                "eventId": "string",
                "eventType": "string",
                "startTime": "string",
                "startTimeInSeconds": number
              }
            ]
          },
          "startTime": "string",
          "startTimeInSeconds": number,
          "dateTime": "string",
          "adBreakTrackingEvents": [...],
          "vastAdId": "string"
        }
      ],
      "adType": "string",
      "availID": "string",
      "duration": "string",
      "durationInSeconds": number,
      "startTime": "string",
      "startTimeInSeconds": number,
      "dateTime": "string",
      "adMarkerDuration": "string",
      "adProgramDateTime": "string",
      "dashAvailabilityStartTime": "string",
      "hlsAnchorMediaSequenceNumber": "string"
    }
  ],
  "nonLinearAvails": [
    {
      "nonLinearAds": [...],
      "nonLinearAdsList": [...]
    }
  ],
  "nextToken": "string",
  "meta": {}
}
```

## Properties
<a name="ad-reporting-client-side-ad-tracking-schema-properties"></a>

下表列出用戶端追蹤 API 中的屬性、其定義、值類型和範例。


****  

| 屬性 | 定義 | 值類型 | 範例 | 
| --- | --- | --- | --- | 
|   adID  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html) 路徑： `/avails/ads/adId` VAST 映射：無  | String | 10 | 
|   adBreakTrackingEvents  |  從 VAST 回應攜帶 VMAP 追蹤事件的陣列。如需詳細資訊，請參閱 [VMAP 1.0 規格的第 ](https://www.iab.com/guidelines/vmap/)2.3.3 節。 路徑： `/avails/ads/adBreakTrackingEvents`  | 陣列 |  []  | 
|   adMarkerDuration  |  從資訊清單中的廣告標記觀察到的時段持續時間。  | String |  30  | 
|   adParameters  |  MediaTailor 從 VAST VPAID 傳遞給玩家的廣告參數字串。 路徑： `/avails/ads/adParameters` VAST 映射： `VAST/Ad/InLine/Creatives/Creative/Linear/AdParameters`  | String |  | 
|   adProgramDateTime  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html)  | String |  | 
|   ads  |  包含組成時段之廣告物件的陣列。這些廣告會依它們在資訊清單中顯示的順序列出。 路徑： `/avails/ads`  | 陣列 |  []  | 
|   adSystem  |  提供廣告的系統名稱。  請務必提供 值。如果您不提供值，可能會出現問題。   | String |  myADS  | 
|   adTitle  |  廣告的標題。  | String |  ad1  | 
|   adVerifications  |  包含執行第三方測量程式碼所需的資源和中繼資料，以驗證創意播放。如需此屬性的詳細資訊，請參閱 [VAST 4.2 規格的第 ](https://iabtechlab.com/standards/vast/)3.16 節。 MediaTailor 支援 `adVerifications` 做為 VAST 3 延伸節點。 路徑： `/avails/ads/adVerifications` VAST 映射： `VAST/Ad/InLine/AdVerifications`  | 陣列 |  []  | 
|   altText  |  配套廣告影像的替代文字。此文字可讓支援視覺障礙者描述性音訊的玩家回讀影像的描述。 路徑： `/avails/ads/companionAds/altText`  | String |  video sequence advertising sneakers  | 
|   apiFramework  |  設定為 `VPAID`，告知玩家此廣告是 VPAID 廣告。 可以出現在結構描述的多個位置。  | String |  VPAID  | 
|   availID  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html) 路徑： `/avails/availID`  | String |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html)  | 
|   avails  |  包含廣告休息時間物件或*時段*的陣列，顯示在作用中的資訊清單視窗中。時段會依資訊清單中顯示的順序列出。 路徑： `/avails`  | 陣列 |  []  | 
|   adType  |  廣告的類型。 路徑： `/avails/adType` 和 `/avails/ads/adType`  | String |  | 
|   dateTime  |  開始廣告時段或廣告的程式日期時間，採用 ISO 8601 秒格式。 路徑： `/avails/dateTime` 和 `/avails/ads/dateTime`  | String |  | 
|   duration  |  長度，以 ISO 8601 秒格式顯示。回應包含整個廣告時段和每個廣告和信標的持續時間，但信標持續時間一律為零。 路徑： `/avails/duration` 和 `/avails/ads/duration`  | String | 15.015 | 
|   durationInSeconds  |  長度，以秒格式顯示。 路徑： `/avails/durationInSeconds`和 `/avails/ads/durationInSeconds`  | Number |  | 
|   extensions  |  廣告伺服器使用的 VAST 自訂擴充功能。如需延伸模組的詳細資訊，請參閱 [VAST 4.2 規格的第 ](https://iabtechlab.com/standards/vast/)3.18 節。 路徑： `/avails/ads/extensions` VAST 映射： `VAST/Ad/InLine/Extensions`  | 陣列 | [] | 
|   icons  |  廣告的圖示元素。 路徑： `/avails/ads/icons` VAST 映射： `VAST/Ad/InLine/Creatives/Creative/Linear/Icons`  | 陣列 |  | 
|   mediaFiles  |  播放器在廣告時段所需的影片和其他資產。 路徑： `/avails/ads/mediaFiles`  | 物件 |  | 
|   nonLinearAvails  |  非線性廣告時段物件的陣列。 路徑： `/nonLinearAvails`  | 陣列 |  | 
|   executableResource  |  可執行的資源以進行驗證。 路徑： `/avails/ads/adVerifications/executableResource` VAST 映射： `VAST/Ad/InLine/AdVerifications/Verification/ExecutableResource`  | 陣列 |  | 
|   javaScriptResource  |  用於驗證的 JavaScript 資源。 路徑： `/avails/ads/adVerifications/javaScriptResource` VAST 映射： `VAST/Ad/InLine/AdVerifications/Verification/JavaScriptResource`  | 陣列 |  | 
|   trackingEvents  |  追蹤用於驗證或配套廣告的事件。 路徑： `/avails/ads/adVerifications/trackingEvents` 或 `/avails/ads/companionAds/trackingEvents`  | 陣列 |  | 
|   vendor  |  驗證廠商。 路徑： `/avails/ads/adVerifications/vendor` VAST 映射： `VAST/Ad/InLine/AdVerifications/Verification/@vendor`  | String |  | 
|   uri  |  指向可執行資產、影片資產或追蹤端點的 URI。 路徑：結構描述中的各種位置 VAST 映射：VATS 中的各種 CDATA 元素  | String | https://tracking.example.com/impression | 
|   verificationParameters  |  驗證參數。 路徑： `/avails/ads/adVerifications/verificationParameters` VAST 映射： `VAST/Ad/InLine/AdVerifications/Verification/VerificationParameters`  | String |  | 
|   attributes  |  相配廣告屬性，例如維度和轉譯模式。 路徑： `/avails/ads/companionAds/attributes`  | 物件 |  | 
|   companionClickThrough  |  當檢視器按一下配套廣告時，媒體播放器開啟的廣告商頁面 URL。 路徑： `/avails/ads/companionAds/companionClickThrough` VAST 映射： `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickThrough`  | String | https://aws.amazon.com/ | 
|   companionClickTracking  |  `companionClickThrough` 屬性的追蹤 URL。 路徑： `/avails/ads/companionAds/companionClickTracking` VAST 映射： `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/CompanionClickTracking`  | String | https://myads.com/beaconing/event=clicktracking | 
|   htmlResource  |  直接插入串流供應商 HTML 頁面的 CDATA 編碼 HTML。 路徑： `/avails/ads/companionAds/htmlResource` VAST 映射： `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/HTMLResource`  | String | <\$1[CDATA[<\$1doctype html><html><head><meta name=\$1"viewport\$1" content=\$1"width=1, initial-scale=1.0, minimum-scale=1.0,...]]> | 
|   iFrameResource  |  串流提供者載入 iframe 的 HTML 資源檔案 URL。 路徑： `/avails/ads/companionAds/iFrameResource` VAST 映射： `VAST/Ad/InLine/Creatives/Creative/CompanionAds/Companion/iFrameResource`  | String |  | 
|   sequence  |  VAST 回應中為創意指定的序列值。 路徑： `/avails/ads/companionAds/sequence`  | String | 1 | 
|   startTime  |  ISO 8601 秒格式的時間位置。對於 HLS，這是相對於播放工作階段的開頭。對於 DASH，這是相對於資訊清單的 AST （可用性開始時間）。回應中包含整段廣告時段、每則廣告與信標所要使用的開始時間。 路徑： `/avails/startTime` 和 `/avails/ads/startTime`  | String | PT18.581355S | 
|   startTimeInSeconds  |  以秒格式顯示的時間位置。對於 HLS，這是相對於播放工作階段的開頭。對於 DASH，這是相對於資訊清單的 AST （可用性開始時間）。回應中包含整段廣告時段、每則廣告與信標所要使用的開始時間。 路徑： `/avails/startTimeInSeconds` 和 `/avails/ads/startTimeInSeconds`  | Number | 18.581 | 
|   eventId  |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/ad-reporting-client-side-ad-tracking-schema.html)  | String |  | 
|   event  |  追蹤事件的名稱。 路徑： `/avails/ads/adVerifications/trackingEvents/event` 或 `/avails/ads/companionAds/trackingEvents/event`  | String | impression, start, firstQuartile, midpoint, thirdQuartile, complete | 
|   beaconUrls  |  MediaTailor 傳送廣告信標的 URL。 路徑： `/avails/ads/mediaFiles/trackingEvents/beaconUrls`  | 陣列 |  | 
|   bitrate  |  影片資產的位元速率。此屬性通常不包含在可執行資產中。  | String | 2048 | 
|   companionAds  |  一或多個配套廣告內容規格，每個規格指定要使用的資源檔案。配套廣告會伴隨廣告時段，並提供內容，例如廣告或橫幅周圍的影格，以在影片附近顯示。 路徑： `/avails/ads/companionAds`  | 陣列 | [] | 
|   creativeId  |  `Creative` 廣告標籤的`Id`屬性值。  | String | creative-1 | 
|   creativeSequence  |  根據 VAST 回應中的`Ad@id`值，廣告應播放的序列。  | String | 1 | 
|   dashAvailabilityStartTime  |  對於即時/動態 DASH，原始資訊清單`MPD@availabilityStartTime`的 。  | String | 2022-10-05T19:38:39.263Z | 
|   delivery  |  指出是否使用 `progressive`或 `streaming`通訊協定。  | String | progressive | 
|   eventType  |  信標的類型。 路徑： `/avails/ads/mediaFiles/trackingEvents/eventType`  | String | impression | 
|   height  |  影片資產的高度，以像素為單位。  | String | 360 | 
|   hlsAnchorMediaSequenceNumber  |  HLS 原始資訊清單中看到的第一個/最舊媒體序列的媒體序列編號。  | String | 77 | 
|   maintainAspectRatio  |  指出是否要在擴展時維護影片的長寬比。  | Boolean | true | 
|   mediaFilesList  |  指定玩家在廣告時段所需的視訊和其他資產。 路徑： `/avails/ads/mediaFiles/mediaFilesList`  | 陣列 | [] | 
|   mediaFileUri  |  指向可執行資產或影片資產的 URI。  | String | https://myad.com/ad/ad134/vpaid.js | 
|   mediaType  |  創意或配套資產的 MIME 類型。  | String | video/mp4 | 
|   meta  |  廣告的其他中繼資料。  | 物件 |  | 
|   mezzanine  |  如果 VPAID 廣告包含一個，則會指定中間 MP4 資產的 URL。 路徑： `/avails/ads/mediaFiles/mezzanine`  | String | https://gcdn.2mdn.net/videoplayback/id/itag/ck2/file/file.mp4 | 
|   nextToken  |  當存在此類值時，指向結果下一頁的字符值。  | String | UFQzOS44NzNTXzIwMjMtMDctMzFUMTY6NTA6MDYuMzUwNjI2ODQ1Wl8x | 
|   nonLinearAds  |  出現在影片內容旁的非線性廣告。  | 陣列 | [] | 
|   nonLinearAdsList  |  非線性廣告的清單。  | 陣列 | [] | 
|   scalable  |  指出是否要將視訊擴展到其他維度。  | Boolean | true | 
|   skipOffset  |  識別玩家何時提供略過控制項給使用者的時間值。  | String | 00:00:05 | 
|   staticResource  |  用於廣告元件的靜態創意檔案 URL。 路徑： `/avails/ads/companionAds/staticResource`  | String | https://very-interactive-ads.com/campaign1/file.json?c=1019113602 | 
|   vastAdId  |  `Ad` 標籤的`Id`屬性值。  | String | ad1 | 
|   width  |  影片資產的寬度，以像素為單位。  | String | 640 | 
|   xPosition  |  影片播放器中圖示的水平位置。可以是特定的像素值或「左」或「右」等位置。 路徑： `/avails/ads/icons/attributes/xPosition`  | String | left 或 10 | 
|   yPosition  |  影片播放器中圖示的垂直位置。可以是特定的像素值或「頂端」或「底部」等位置。 路徑： `/avails/ads/icons/attributes/yPosition`  | String | top 或 10 | 
|   iconClicks  |  包含圖示的點擊和追蹤資訊。 路徑： `/avails/ads/icons/iconClicks`  | 物件 |  | 
|   iconClickThrough  |  當檢視器按一下圖示時，媒體播放器開啟的廣告商頁面 URL。 路徑： `/avails/ads/icons/iconClicks/iconClickThrough`  | String | https://advertiser.com/landing-page | 
|   iconClickTracking  |  `iconClickThrough` 屬性的追蹤 URL。 路徑： `/avails/ads/icons/iconClicks/iconClickTracking`  | 物件 |  | 
|   iconClickFallbackImages  |  無法顯示圖示時要顯示的備用影像陣列。 路徑： `/avails/ads/icons/iconClicks/iconClickFallbackImages`  | 陣列 |  | 
|   iconViewTracking  |  檢視圖示時用於追蹤的 URL。 路徑： `/avails/ads/icons/iconViewTracking`  | String | https://tracking.example.com/icon-view | 
|   offset  |  圖示應該在廣告播放期間出現的時間位移。 路徑： `/avails/ads/icons/attributes/offset`  | String | 00:00:05 | 
|   program  |  與圖示相關聯的程式或倡議，例如「AdChoices」。 路徑： `/avails/ads/icons/attributes/program`  | String | AdChoices | 
|   pxratio  |  圖示或配套廣告的像素比率，用於高 DPI 顯示。 路徑： `/avails/ads/icons/attributes/pxratio` 或 `/avails/ads/companionAds/attributes/pxratio`  | String | 1 或 2 | 
|   type  |  資源或延伸項目的類型。 路徑： `/avails/ads/extensions/type` 或 `/avails/ads/adVerifications/executableResource/type`  | String | text/javascript | 
|   content  |  延伸模組的內容。 路徑： `/avails/ads/extensions/content`  | String |  | 
|   language  |  可執行資源的程式設計語言。 路徑： `/avails/ads/adVerifications/executableResource/language`  | String | javascript | 
|   browserOptional  |  指出 JavaScript 資源是否需要瀏覽器支援。 路徑： `/avails/ads/adVerifications/javaScriptResource/browserOptional`  | String | true 或 false | 
|   id  |  結構描述中各種元素的識別符。 路徑： `/avails/ads/companionAds/attributes/id` 或 `/avails/ads/icons/iconClicks/iconClickTracking/id`  | String | companion-1 | 
|   assetHeight  |  配套廣告資產的高度。 路徑： `/avails/ads/companionAds/attributes/assetHeight`  | String | 250 | 
|   assetWidth  |  配套廣告資產的寬度。 路徑： `/avails/ads/companionAds/attributes/assetWidth`  | String | 300 | 
|   expandedHeight  |  展開時配套廣告的高度。 路徑： `/avails/ads/companionAds/attributes/expandedHeight`  | String | 600 | 
|   expandedWidth  |  展開時配套廣告的寬度。 路徑： `/avails/ads/companionAds/attributes/expandedWidth`  | String | 600 | 
|   renderingMode  |  配套廣告的轉譯模式。 路徑： `/avails/ads/companionAds/attributes/renderingMode`  | String | default 或 transparent | 
|   adSlotId  |  應顯示配套廣告的廣告位置 ID。 路徑： `/avails/ads/companionAds/attributes/adSlotId`  | String | banner-1 | 
|   creativeType  |  創意資產的 MIME 類型。 路徑： `/avails/ads/icons/staticResource/creativeType`  | String | image/png | 

# 廣告追蹤活動時間
<a name="ad-reporting-client-side-ad-tracking-schema-activity-timing"></a>

透過用戶端報告，玩家必須以精確度發出追蹤事件 （信標）。使用 MediaTailor 用戶端追蹤結構描述，您可以確保每個時段、廣告、配套、浮水印和追蹤事件、時間和持續時間資訊都存在，並以不同的形式顯示。

使用下列 MediaTailor 金鑰/值對，讓播放器準確調整廣告事件活動，例如追蹤事件與播放位置：
+ [startTime](ad-reporting-client-side-ad-tracking-schema.md#property-starttime) 
+  [startTimeInSeconds](ad-reporting-client-side-ad-tracking-schema.md#property-starttimeinseconds) 
+  [adProgramDateTime](ad-reporting-client-side-ad-tracking-schema.md#property-adprogramdatetime) 
+  [adID](ad-reporting-client-side-ad-tracking-schema.md#property-adid)/[eventId](ad-reporting-client-side-ad-tracking-schema.md#property-eventid) 

HLS 和 DASH 實作 `startTime`和 的值`startTimeInSeconds`不同：
+ HLS - 這些`startTime`值是相對於播放工作階段的開頭。播放工作階段的開頭定義為時間零。廣告`startTime`是導致時段之前所有`EXT-INF`區段持續時間的累積值總和。廣告或追蹤事件所在區段的媒體序號也會對應至用戶端追蹤回應`eventId`中的 `adId`或 。
+ DASH：
  + 即時/動態資訊清單 - `startTime`值相對於 DASH 資訊清單`MPD@availabilityStartTime`的 。`MPD@avaibilityStartTime` 是使用串流之所有 MediaTailor 工作階段的計時錨點。
  + VOD/靜態資訊清單 - `startTime`值相對於播放工作階段的開頭。播放工作階段的開頭定義為時間零。時段內的每個廣告都包含在自己的`Period`元素中。`Period` 元素具有`@start`屬性，其值與用戶端追蹤承載中的`startTime`值相同。`PeriodId` 也會對應至用戶端追蹤回應`eventId`中的 `adId`或 。

**Example HLS：**  
在下列範例中，MediaTailor 工作階段已啟動，而下列資訊清單是第一個提供給用戶端的資訊清單：  

```
#EXTM3U
#EXT-X-VERSION:6
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:4603263
#EXT-X-DISCONTINUITY-SEQUENCE:0
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:23.295678Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_34.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:27.306345Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_35.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:31.317012Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_36.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:35.327679Z
#EXTINF:4.010667,
https://123.cloudfront.net/out/v1/index_1_37.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:39.338346Z
#EXTINF:2.538667,
https://123.cloudfront.net/out/v1/index_1_38.ts
#EXT-X-DISCONTINUITY
#EXT-X-KEY:METHOD=NONE
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:41.453Z
#EXTINF:2.0,
https://123.cloudfront.net/tm/asset_1080_4_8_00001.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:43.453Z
#EXTINF:2.0,
https://123.cloudfront.net/tm/asset_1080_4_8_00002.ts
#EXT-X-PROGRAM-DATE-TIME:2023-05-03T21:24:45.453Z
#EXTINF:2.0,
https://123.cloudfront.net/tm/asset_1080_4_8_00003.ts
```
在用戶端追蹤 JSON 承載中，適用下列值：  
+  `startTime`: `"PT18.581355S"` 
+  `startTimeInSeconds`: `18.581` 
+  `availProgramDateTime`: `"2023-05-03T21:24:41.453Z"` 
+  `adId`: `4603269` 

**Example DASH：**  
在下列範例中，MediaTailor 工作階段會在資訊清單中取得中繼。請注意，第二個期間的`@start`屬性值是廣告期間，其值與`MPD@availabilityStartTime`值相對。此值是 MediaTailor 針對所有工作階段寫入用戶端追蹤回應`startTime`欄位的值。  

```
<?xml version="1.0" encoding="UTF-8"?>
<MPD availabilityStartTime="2022-10-05T19:38:39.263Z" minBufferTime="PT10S" minimumUpdatePeriod="PT2S" profiles="urn:mpeg:dash:profile:isoff-live:2011" publishTime="2023-05-03T22:06:48.411Z" suggestedPresentationDelay="PT10S" timeShiftBufferDepth="PT1M30S" type="dynamic" xmlns="urn:mpeg:dash:schema:mpd:2011" xmlns:scte35="urn:scte:scte35:2013:xml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:mpeg:dash:schema:mpd:2011 http://standards.iso.org/ittf/PubliclyAvailableStandards/MPEG-DASH_schema_files/DASH-MPD.xsd">
    <BaseURL>https://123.channel-assembly.mediatailor.us-west-2.amazonaws.com/v1/channel/my-channel/</BaseURL>
    <Location>https://123.cloudfront.net/v1/dash/94063eadf7d8c56e9e2edd84fdf897826a70d0df/MediaTailor-Live-HLS-DASH/channel/channel1/dash.mpd?aws.sessionId=794a15e0-2a7f-4941-a537-9d71627984e5</Location>
    <Period id="1683151479166_1" start="PT5042H25M59.903S" xmlns="urn:mpeg:dash:schema:mpd:2011">
        <BaseURL>https://123.cloudfront.net/out/v1/f1a946be8efa45b0931ea35c9055fb74/ddb73bf548a44551a0059c346226445a/eaa5485198bf497284559efb8172425e/</BaseURL>
        <AdaptationSet ...>
            ...
        </AdaptationSet>
    </Period>
    <Period id="1683151599194_1_1" start="PT5042H27M59.931S">
        <BaseURL>https://123.cloudfront.net/tm/94063eadf7d8c56e9e2edd84fdf897826a70d0df/fpc5omz5wzd2rdepgieibp23ybyqyrme/</BaseURL>
        <AdaptationSet ...>
            ...
        </AdaptationSet>
    </Period>
</MPD>
```
在用戶端追蹤 JSON 承載中，適用下列值：  
+  `startTime`: `"PT5042H27M59.931S"` 
+  `startTimeInSeconds`: `18152879.931` 
+  `availProgramDateTime`： *null* 
+  `adId`: `1683151599194_1_1` 

# 用戶端廣告追蹤的玩家控制和功能
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls"></a>

MediaTailor 用戶端追蹤中繼資料支援各種玩家控制和功能。下列清單說明熱門的玩家控制項。

**Topics**
+ [刷新](#ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing)
+ [廣告倒數計時器](#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer)
+ [可略過的廣告](#ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads)
+ [廣告點擊](#ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough)
+ [配套廣告](#ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads)
+ [互動式廣告 (SIMID)](#ad-reporting-client-side-ad-tracking-schema-player-controls-simid-ads)
+ [互動式廣告 (VPAID)](#ad-reporting-client-side-ad-tracking-schema-player-controls-vpaid-ads)
+ [Google 為什麼使用此廣告 (WTA) 的圖示](#ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta)

## 刷新
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-scrubbing"></a>

為了增強播放體驗，玩家可以在播放時間軸中顯示廣告位置。MediaTailor 以用戶端追蹤回應中的`startTimeInSeconds`值形式提供這些廣告位置。

**注意**  
有些串流供應商可防止清除超過廣告位置。

![\[螢幕擷取畫面，顯示廣告播放的影片時間軸中的 MediaTailor 標記位置。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/scrubbing.png)


下列用戶端追蹤承載 JSON 回應顯示時段陣列根 JSON 物件內的時段 （廣告休息時間） 開始時間。玩家使用此資料在 28 秒時，在玩家時間軸上顯示廣告休息時間的位置。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [...],
      "availId": "7",
      "availProgramDateTime": null,
      "duration": "PT30S",
      "durationInSeconds": 30,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT28S",
      "startTimeInSeconds": 28
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMk0zNC44NjhTXzIwMjMtMDctMjFUMjA6MjM6MDcuNzc1NzE2MzAyWl8x",
  "nonLinearAvails": []
}
```

## 廣告倒數計時器
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-ad-countdown-timer"></a>

透過 MediaTailor，您可以使用廣告倒數計時器，協助您的觀眾在廣告休息時間檢視期間保持參與。對象可以使用計時器來了解廣告休息時間結束及其程式繼續的時間。

![\[顯示 MediaTailor 的螢幕擷取畫面，顯示廣告倒數計時器，告知觀眾在其程式繼續之前剩餘的時間。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/ad-countdown-timer.png)


在廣告倒數計時器中扮演角色的用戶端追蹤中繼資料中的元素為 `startTime`、`duration`、 `startTimeInSeconds`和 `durationInSeconds`。播放器會使用此中繼資料，以及其個別追蹤的工作階段經過時間，來判斷何時顯示計時器及其應計數的值。

下列用戶端追蹤承載 JSON 回應顯示顯示廣告倒數計時器所需的資訊。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [...],
      "availId": "7",
      "availProgramDateTime": null,
      "duration": "PT30S",
      "durationInSeconds": 30,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT28S",
      "startTimeInSeconds": 28
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMk0zNC44NjhTXzIwMjMtMDctMjFUMjA6MjM6MDcuNzc1NzE2MzAyWl8x",
  "nonLinearAvails": []
}
```

當工作階段的經過時間達到時段的開始時間時，播放器會顯示倒數計時器，其值符合時段的持續時間。倒數計時值會隨著經過的時間超過時段的開始時間而減少。

**Example 公式：HLS （即時和 VOD) 和 DASH (VOD) 的倒數計時器**  
+ `session_start_time` = 所有`EXT-INF`持續時間值的總和 - 三個最新`EXT-INF`媒體序列的持續時間值
+ 計時器值 = `duration` - (`session_elapsed_time` - `startTime`)

![\[圖表顯示廣告倒數計時器的計算，根據工作階段的開始時間和時段的開始時間，用於 HLS （即時和 VOD) 和 DASH (VOD) 資訊清單。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/ad-countdown-timer-hls-dash-vod.png)


**Example 公式：DASH 的倒數計時器 （即時）**  
+ `session_start_time` = （最新客群的 `startTime` \$1 `duration`) / `timescale` - `MPD@suggestedPresentationDelay`
+ 計時器值 = `duration` - (`session_elapsed_time` - `startTime`)

![\[圖表顯示即時 DASH 資訊清單的廣告倒數計時器計算，根據工作階段的開始時間和時段的開始時間。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/ad-countdown-timer-dash-live.png)


## 可略過的廣告
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-skippable-ads"></a>

*可略過的廣告*是廣告點，可讓檢視器略過一些廣告以繼續檢視程式。在 VAST 中， `Linear@skipOffset` 屬性會識別可略過的廣告。

下列 VAST 回應顯示如何使用可略過的廣告：

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad>
    <InLine>
      ...
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear skipoffset="00:00:05">
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <MediaFile id="EMT" delivery="progressive" width="640" height="360" type="video/mp4" bitrate="143" scalable="true" maintainAspectRatio="true"><![CDATA[https://ads.com/file.mp4]]></MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
      ...
    </InLine>
  </Ad>
</VAST>
```

下列用戶端追蹤承載 JSON 回應會顯示`ads`陣列內的廣告中繼資料。陣列包含 MediaTailor 從 VAST 回應取得`skipOffset`的值。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:11:40.693Z",
          "adSystem": "2.0",
          "adTitle": "AD-skiing-15",
          "adVerifications": [],
          "companionAds": [...],
          "creativeId": "1",
          "creativeSequence": "1",
          "duration": "PT15.015S",
          "durationInSeconds": 15.015,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": "00:00:05",
          "startTime": "PT9.943S",
          "startTimeInSeconds": 9.943,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://adserverbeaconing.com/v1/impression"
              ],
              "duration": "PT15.015S",
              "durationInSeconds": 15.015,
              "eventId": "2697726",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT9.943S",
              "startTimeInSeconds": 9.943
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2697726",
      "availProgramDateTime": "2023-07-31T16:11:40.693Z",
      "duration": "PT15.015S",
      "durationInSeconds": 15.015,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT9.943S",
      "startTimeInSeconds": 9.943
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "",
  "nonLinearAvails": []
}
```

## 廣告點擊
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-ad-clickthrough"></a>

按一下式 URIs 可讓廣告商測量廣告在吸引觀眾注意力方面的成功程度。檢視器按一下進行中廣告的作用中影片影格後，Web 瀏覽器會開啟廣告者首頁或行銷活動登陸頁面的 URI。玩家開發人員會決定點選行為，例如在廣告影片上覆蓋按鈕或標籤，並顯示要點選的訊息以進一步了解。玩家開發人員通常會在觀眾按一下作用中的影片影格後暫停廣告的影片。

![\[影片播放器中廣告點擊率的螢幕擷取畫面。觀眾按一下影片影格。播放器會暫停影片，然後開啟 Web 瀏覽器，將瀏覽者導向廣告者的首頁或行銷活動登陸頁面。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/ad-clickthrough.png)


MediaTailor 可以剖析和提供 VAST 回應中傳回的任何線性影片點擊事件 URLs。下列 VAST 回應顯示廣告點擊範例。

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad>
    <InLine>
      ...
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear>
            <Duration>00:00:15</Duration>
            <MediaFiles>
              <MediaFile id="EMT" delivery="progressive" width="1280" height="720" type="video/mp4" bitrate="143" scalable="true" maintainAspectRatio="true"><![CDATA[https://ads.com/file.mp4]]></MediaFile>
            </MediaFiles>
            <VideoClicks>
              <ClickThrough id="EMT"><![CDATA[https://aws.amazon.com]]></ClickThrough>
              <ClickTracking id="EMT"><![CDATA[https://myads.com/beaconing/event=clicktracking]]></ClickTracking>
            </VideoClicks>
          </Linear>
        </Creative>
      </Creatives>
      ...
    </InLine>
  </Ad>
</VAST>
```

下列用戶端追蹤承載 JSON 回應顯示 MediaTailor 如何在`trackingEvents`陣列中顯示點擊和點擊追蹤 URLs。`clickThrough` 事件類型代表點擊廣告，而`clickTracking`事件類型代表點擊追蹤 URL。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:53:40.577Z",
          "adSystem": "2.0",
          "adTitle": "1",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "00006",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT39.339S",
          "startTimeInSeconds": 39.339,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://aws.amazon.com"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "clickThrough",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=clicktracking"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698795",
              "eventProgramDateTime": null,
              "eventType": "clickTracking",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2698188",
      "availProgramDateTime": "2023-07-31T16:53:40.577Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT39.339S",
      "startTimeInSeconds": 39.339
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQzOS4zMzlTXzIwMjMtMDctMzFUMTY6NTQ6MDQuODA1Mzk2NTI5Wl8x",
  "nonLinearAvails": []
}
```

## 配套廣告
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-companion-ads"></a>

*配套廣告*會與線性創作一起顯示。使用配套廣告，透過顯示產品、標誌和品牌資訊來提高廣告點的有效性。顯示廣告可以具有快速回應 (QR) 代碼和可點選區域，以促進受眾參與。

MediaTailor 支援 VAST 回應中的配套廣告。它可以分別從 `StaticResource`、 `iFrameResource`和 `HTMLResource`節點傳遞中繼資料。

下列 VAST 回應顯示線性廣告和配套廣告的範例位置和格式。

```
<?xml version="1.0" encoding="UTF-8"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad>
    <InLine>
      ...
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear>
            <Duration>00:00:10</Duration>
            <MediaFiles>
              <MediaFile id="EMT" delivery="progressive" width="640" height="360" type="video/mp4" bitrate="143" scalable="true" maintainAspectRatio="true"><![CDATA[https://ads.com/file.mp4]]></MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
        <Creative id="2" sequence="1">
          <CompanionAds>
            <Companion id="2" width="300" height="250">
              <StaticResource creativeType="image/png"><![CDATA[https://emt.com/companion/9973499273]]></StaticResource>
              <TrackingEvents>
                <Tracking event="creativeView"><![CDATA[https://beacon.com/1]]></Tracking>
              </TrackingEvents>
              <CompanionClickThrough><![CDATA[https://beacon.com/2]]></CompanionClickThrough>
            </Companion>
            <Companion id="3" width="728" height="90">
              <StaticResource creativeType="image/png"><![CDATA[https://emt.com/companion/1238901823]]></StaticResource>
              <TrackingEvents>
                <Tracking event="creativeView"><![CDATA[https://beacon.com/3]]></Tracking>
              </TrackingEvents>
              <CompanionClickThrough><![CDATA[https://beacon.com/4]]></CompanionClickThrough>
            </Companion>
          </CompanionAds>
        </Creative>
      </Creatives>
      ...
    </InLine>
  </Ad>
</VAST>
```

資料會出現在`/avail/x/ads/y/companionAds`清單中的用戶端追蹤回應中。每個線性創作最多可包含 6 個配套廣告。如以下範例所示，配套廣告會出現在清單中

**注意**  
最佳實務是，應用程式開發人員應實作邏輯，在創作結束時明確移除或卸載配套廣告。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "0",
          "adParameters": "",
          "adProgramDateTime": null,
          "adSystem": "EMT",
          "adTitle": "sample",
          "adVerifications": [],
          "companionAds": [
            {
              "adParameters": null,
              "altText": null,
              "attributes": {
                "adSlotId": null,
                "apiFramework": null,
                "assetHeight": null,
                "assetWidth": null,
                "expandedHeight": null,
                "expandedWidth": null,
                "height": "250",
                "id": "2",
                "pxratio": null,
                "renderingMode": null,
                "width": "300"
              },
              "companionClickThrough": "https://beacon.com/2",  
              "companionClickTracking": null,
              "htmlResource": null,
              "iFrameResource": null,
              "sequence": "1",
              "staticResource": "https://emt.com/companion/9973499273",
              "trackingEvents": [
                {
                  "beaconUrls": [
                    "https://beacon.com/1"
                  ],
                  "eventType": "creativeView"
                }
              ]
            },
            {
              "adParameters": null,
              "altText": null,
              "attributes": {
                "adSlotId": null,
                "apiFramework": null,
                "assetHeight": null,
                "assetWidth": null,
                "expandedHeight": null,
                "expandedWidth": null,
                "height": "90",
                "id": "3",
                "pxratio": null,
                "renderingMode": null,
                "width": "728"
              },
              "companionClickThrough": "https://beacon.com/4",
              "companionClickTracking": null,
              "htmlResource": null,
              "iFrameResource": null,
              "sequence": "1",
              "staticResource": "https://emt.com/companion/1238901823",
              "trackingEvents": [
                {
                  "beaconUrls": [
                    "https://beacon.com/3"
                  ],
                  "eventType": "creativeView"
                }
              ]
            }
          ],
          "creativeId": "1",
          "creativeSequence": "1",
          "duration": "PT10S",
          "durationInSeconds": 10,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT0S",
          "startTimeInSeconds": 0,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://beacon.com/impression/1"
              ],
              "duration": "PT10S",
              "durationInSeconds": 10,
              "eventId": "0",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT0S",
              "startTimeInSeconds": 0
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "0",
      "availProgramDateTime": null,
      "duration": "PT10S",
      "durationInSeconds": 10,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT0S",
      "startTimeInSeconds": 0
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMFNfMjAyMy0wNy0wNlQyMToxMDowOC42NzQ4NDA1NjJaXzE%3D",
  "nonLinearAvails": []
}
```

## 互動式廣告 (SIMID)
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-simid-ads"></a>

*SecureInteractive Media Interface Definition* (SIMID) 是互動式廣告的標準，由互動式廣告局 (IAB) 在 VAST 4.x 標準中推出。SIMID 會將互動式元素的載入與播放器上的主要線性創意分離，並在 VAST 回應中參考兩者。MediaTailor 會在主要創意中拼接，以維持播放體驗，並將互動式元件的中繼資料放在用戶端追蹤回應中。

在下列範例 VAST 4 回應中，SIMID 承載位於`InteractiveCreativeFile`節點內。

```
<?xml version="1.0"?>
<VAST xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad id="1234567">
    <InLine>
      <AdSystem>SampleAdSystem</AdSystem>
      <AdTitle>Linear SIMID Example</AdTitle>
      <Description>SIMID example</Description>
      <Error>https://www.beacons.com/error</Error>
      <Impression>https://www.beacons.com/impression</Impression>
      <Creatives>
        <Creative sequence="1">
          <Linear>
            <Duration>00:00:15</Duration>
            <TrackingEvents>
                ...
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough id="123">https://aws.amazon.com</ClickThrough>
              <ClickTracking id="123">https://www.beacons.com/click</ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4">
                                https://interactive-ads.com/interactive-media-ad-sample/media/file.mp4
                            </MediaFile>
              <InteractiveCreativeFile type="text/html" apiFramework="SIMID" variableDuration="true">
                                https://interactive-ads.com/interactive-media-ad-sample/sample_simid.html
                            </InteractiveCreativeFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>
```

在下列 VAST 3 回應中，SIMID 承載位於`Extensions`節點內。

```
<?xml version="1.0"?>
<VAST xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad id="1234567">
    <InLine>
      <AdSystem>SampleAdSystem</AdSystem>
      <AdTitle>Linear SIMID Example</AdTitle>
      <Description>SIMID example</Description>
      <Impression>https://www.beacons.com/impression</Impression>
      <Creatives>
        <Creative id="1" sequence="1">
          <Linear>
            <Duration>00:00:15</Duration>
            <TrackingEvents>
                ...
            </TrackingEvents>
            <VideoClicks>
              <ClickThrough id="123">https://aws.amazon.com</ClickThrough>
              <ClickTracking id="123">https://myads.com/beaconing/event=clicktracking</ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" type="video/mp4">
                                https://interactive-ads.com/interactive-media-ad-sample/media/file.mp4
                            </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
      <Extensions>
        <Extension type="InteractiveCreativeFile">
          <InteractiveCreativeFile type="text/html" apiFramework="SIMID" variableDuration="true">
            https://interactive-ads.com/interactive-media-ad-sample/sample_simid.html
          </InteractiveCreativeFile>
        </Extension>
      </Extensions>
    </InLine>
  </Ad>
</VAST>
```

在下列用戶端追蹤回應中，SIMID 資料會出現在`/avails/x/ads/y/extensions`清單中。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:53:40.577Z",
          "adSystem": "2.0",
          "adTitle": "Linear SIMID Example",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "1",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [
            {
              "content": "<InteractiveCreativeFile type=\"text/html\" apiFramework=\"SIMID\" variableDuration=\"true\">\nhttps://interactive-ads.com/interactive-media-ad-sample/sample_simid.html</InteractiveCreativeFile>",
              "type": "InteractiveCreativeFile"
            }
          ],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT39.339S",
          "startTimeInSeconds": 39.339,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://aws.amazon.com"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "clickThrough",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=clicktracking"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698795",
              "eventProgramDateTime": null,
              "eventType": "clickTracking",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2698188",
      "availProgramDateTime": "2023-07-31T16:53:40.577Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT39.339S",
      "startTimeInSeconds": 39.339
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQzOS4zMzlTXzIwMjMtMDctMzFUMTY6NTQ6MDQuODA1Mzk2NTI5Wl8x",
  "nonLinearAvails": []
}
```

## 互動式廣告 (VPAID)
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-vpaid-ads"></a>

*影片播放器廣告界面定義* (VPAID) 指定廣告與影片播放器之間的通訊協定，以啟用廣告互動和其他功能。對於即時串流，MediaTailor 支援 VPAID 格式，方法是在時段內在 中拼接板塊區段，並將 VPAID 創意的中繼資料放置在影片播放器使用的用戶端追蹤回應中。播放器會下載 VPAID 檔案並播放線性創意，並執行用戶端的指令碼。玩家*不應該*播放板塊區段。

**注意**  
自 VAST 4.1 起已棄用 VPAID。

![\[VPAID 廣告播放圖表。MediaTailor 會在內容時間軸中拼接時段時段區段。播放器會在時段期間切換到 VPAID 資產。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/interactive-ads-vpaid.png)


下列範例顯示 VAST 回應中的 VPAID 內容。

```
<?xml version="1.0"?>
<VAST xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vast.xsd" version="3.0">
  <Ad id="1234567">
    <InLine>
      <AdSystem>GDFP</AdSystem>
      <AdTitle>VPAID</AdTitle>
      <Description>Vpaid Linear Video Ad</Description>
      <Error>http://www.example.com/error</Error>
      <Impression>http://www.example.com/impression</Impression>
      <Creatives>
        <Creative sequence="1">
          <Linear>
            <Duration>00:00:00</Duration>
            <TrackingEvents>
              <Tracking event="start">http://www.example.com/start</Tracking>
              <Tracking event="firstQuartile">http://www.example.com/firstQuartile</Tracking>
              <Tracking event="midpoint">http://www.example.com/midpoint</Tracking>
              <Tracking event="thirdQuartile">http://www.example.com/thirdQuartile</Tracking>
              <Tracking event="complete">http://www.example.com/complete</Tracking>
              <Tracking event="mute">http://www.example.com/mute</Tracking>
              <Tracking event="unmute">http://www.example.com/unmute</Tracking>
              <Tracking event="rewind">http://www.example.com/rewind</Tracking>
              <Tracking event="pause">http://www.example.com/pause</Tracking>
              <Tracking event="resume">http://www.example.com/resume</Tracking>
              <Tracking event="fullscreen">http://www.example.com/fullscreen</Tracking>
              <Tracking event="creativeView">http://www.example.com/creativeView</Tracking>
              <Tracking event="acceptInvitation">http://www.example.com/acceptInvitation</Tracking>
            </TrackingEvents>
            <AdParameters><![CDATA[ {"videos":[ {"url":"https://my-ads.com/interactive-media-ads/media/media_linear_VPAID.mp4","mimetype":"video/mp4"}]} ]]></AdParameters>
            <VideoClicks>
              <ClickThrough id="123">http://google.com</ClickThrough>
              <ClickTracking id="123">http://www.example.com/click</ClickTracking>
            </VideoClicks>
            <MediaFiles>
              <MediaFile delivery="progressive" apiFramework="VPAID" type="application/javascript" width="640" height="480"> https://googleads.github.io/googleads-ima-html5/vpaid/linear/VpaidVideoAd.js </MediaFile>
            </MediaFiles>
          </Linear>
        </Creative>
      </Creatives>
    </InLine>
  </Ad>
</VAST>
```

下列範例顯示追蹤資訊。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "1",
          "adParameters": "",
          "adProgramDateTime": "2023-07-31T16:53:40.577Z",
          "adSystem": "2.0",
          "adTitle": "1",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "00006",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT39.339S",
          "startTimeInSeconds": 39.339,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://aws.amazon.com"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698188",
              "eventProgramDateTime": null,
              "eventType": "clickThrough",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            },
            {
              "beaconUrls": [
                "https://myads.com/beaconing/event=clicktracking"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "2698795",
              "eventProgramDateTime": null,
              "eventType": "clickTracking",
              "startTime": "PT39.339S",
              "startTimeInSeconds": 39.339
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "2698188",
      "availProgramDateTime": "2023-07-31T16:53:40.577Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT39.339S",
      "startTimeInSeconds": 39.339
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQzOS4zMzlTXzIwMjMtMDctMzFUMTY6NTQ6MDQuODA1Mzk2NTI5Wl8x",
  "nonLinearAvails": []
}{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "2922274",
          "adParameters": "",
          "adProgramDateTime": "2023-08-14T19:49:53.998Z",
          "adSystem": "Innovid Ads",
          "adTitle": "VPAID",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "",
          "creativeSequence": "",
          "duration": "PT16.016S",
          "durationInSeconds": 16.016,
          "extensions": [],
          "mediaFiles": {
            "mediaFilesList": [
              {
                "apiFramework": "VPAID",
                "bitrate": 0,
                "codec": null,
                "delivery": "progressive",
                "height": 9,
                "id": "",
                "maintainAspectRatio": false,
                "maxBitrate": 0,
                "mediaFileUri": "http://my-ads.com/mobileapps/js/vpaid/1h41kg?cb=178344c0-8e67-281a-58ca-962e4987cd60&deviceid=&ivc=",
                "mediaType": "application/javascript",
                "minBitrate": 0,
                "scalable": false,
                "width": 16
              }
            ],
            "mezzanine": "http://my-ads.com/mobileapps/js/vpaid/1h41kg?cb=178344c0-8e67-281a-58ca-962e4987cd60&deviceid=&ivc="
          },
          "skipOffset": null,
          "startTime": "PT8M42.289S",
          "startTimeInSeconds": 522.289,
          "trackingEvents": [
            {
              "beaconUrls": [
                "about:blank"
              ],
              "duration": "PT16.016S",
              "durationInSeconds": 16.016,
              "eventId": "2922274",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT8M42.289S",
              "startTimeInSeconds": 522.289
            }
          ],
          "vastAdId": "1h41kg"
        }
      ],
      "availId": "2922274",
      "availProgramDateTime": "2023-08-14T19:49:53.998Z",
      "duration": "PT16.016S",
      "durationInSeconds": 16.016,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT8M42.289S",
      "startTimeInSeconds": 522.289
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQ4TTQyLjI4OVNfMjAyMy0wOC0xNFQxOTo1MDo0MS4zOTc5MjAzODVaXzE%3D",
  "nonLinearAvails": []
}
```

## Google 為什麼使用此廣告 (WTA) 的圖示
<a name="ad-reporting-client-side-ad-tracking-schema-player-controls-google-wta"></a>

*AdChoices* 是一項產業標準，可為瀏覽者提供他們看到的廣告相關資訊，包括這些廣告的鎖定目標。

![\[Google 為什麼使用此廣告 (WTA) 標誌。WTA 會通知瀏覽者他們看到的廣告，包括這些廣告的鎖定目標。\]](http://docs.aws.amazon.com/zh_tw/mediatailor/latest/ug/images/google-wta.png)


MediaTailor 用戶端追蹤 API 支援在 VAST 回應的 VAST 延伸節點中攜帶的圖示中繼資料。如需 VAST 回應中 WTA 的詳細資訊，請參閱[此範例 VAST XML 回應](https://storage.googleapis.com/interactive-media-ads/ad-tags/ima_wta_sample_vast_3.xml)。

**注意**  
MediaTailor 目前僅支援 VAST 第 3 版。

```
<VAST>
    <Ad>  
    <InLine>  
       ...
      <Extensions>
        <Extension type="IconClickFallbackImages">
          <IconClickFallbackImages program="GoogleWhyThisAd">
            <IconClickFallbackImage width="400" height="150">
              <AltText>Alt icon fallback</AltText>
              <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png]]></StaticResource>
            </IconClickFallbackImage>
          </IconClickFallbackImages>
          <IconClickFallbackImages program="AdChoices">
            <IconClickFallbackImage width="400" height="150">
              <AltText>Alt icon fallback</AltText>
              <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=1x]]></StaticResource>
            </IconClickFallbackImage>
            <IconClickFallbackImage width="800" height="300">
              <AltText>Alt icon fallback</AltText>
              <StaticResource creativeType="image/png"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=2x]]></StaticResource>
            </IconClickFallbackImage>
          </IconClickFallbackImages>
        </Extension>
      </Extensions>
    </InLine>
  </Ad>
</VAST>
```

下列範例顯示`/avails/x/ads/y/extensions`清單中的用戶端追蹤回應。

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "0",
          "adParameters": "",
          "adProgramDateTime": null,
          "adSystem": "GDFP",
          "adTitle": "Google Why This Ad VAST 3 Sample",
          "adVerifications": [],
          "companionAds": [],
          "creativeId": "7891011",
          "creativeSequence": "1",
          "duration": "PT10S",
          "durationInSeconds": 10,
          "extensions": [
            {
              "content": "<IconClickFallbackImages program=\"GoogleWhyThisAd\">      
                          <IconClickFallbackImage height=\"150\" width=\"400\">      
                          <AltText>Alt icon fallback</AltText>      
                          <StaticResource creativeType=\"image/png\"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png]]>
                          </StaticResource>     
                          </IconClickFallbackImage>    
                          </IconClickFallbackImages>     
                          <IconClickFallbackImages program=\"AdChoices\">     
                          <IconClickFallbackImage height=\"150\" width=\"400\">     
                          <AltText>Alt icon fallback</AltText>       
                          <StaticResource creativeType=\"image/png\"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=1x]]>
                          </StaticResource>      
                          </IconClickFallbackImage>      
                          <IconClickFallbackImage height=\"300\" width=\"800\">       
                          <AltText>Alt icon fallback</AltText>       
                          <StaticResource creativeType=\"image/png\"><![CDATA[https://storage.googleapis.com/interactive-media-ads/images/wta_dialog.png?size=2x]]>
                          </StaticResource>      
                          </IconClickFallbackImage>     
                          </IconClickFallbackImages>",
              "type": "IconClickFallbackImages"
            }
          ],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": "00:00:03",
          "startTime": "PT0S",
          "startTimeInSeconds": 0,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://example.com/view"
              ],
              "duration": "PT10S",
              "durationInSeconds": 10,
              "eventId": "0",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT0S",
              "startTimeInSeconds": 0
            }
          ],
          "vastAdId": "123456"
        }
      ],
      "availId": "0",
      "availProgramDateTime": null,
      "duration": "PT10S",
      "durationInSeconds": 10,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT0S",
      "startTimeInSeconds": 0
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMFNfMjAyMy0wNy0wNlQyMDo0MToxNy45NDE4MDM0NDhaXzE%3D",
  "nonLinearAvails": []
}
```

# 用戶端信標
<a name="ad-reporting-client-side-beaconing"></a>

透過用戶端追蹤`startTimeInSeconds`元素，您可以使用 MediaTailor 來支援信標計時。

下列 JSON 回應顯示主要信標類型：印模、開始、四分位數和完成。

**注意**  
互動式廣告局 (IAB) Video Impression Measurement Guidelines 指出，廣告曝光需要廣告內容載入用戶端，並且至少開始向玩家轉譯的時間。如需詳細資訊，請參閱 IAB [網站上的數位影片廣告服務範本 (VAST)](https://www.iab.com/guidelines/vast/)。

```
{
  "avails": [
    {
      "ads": [
        {
          "adId": "8104385",
          "duration": "PT15.100000078S",
          "durationInSeconds": 15.1,
          "startTime": "PT17.817798612S",
          "startTimeInSeconds": 17.817,
          "trackingEvents": [
          {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=impression"
              ],
              "duration": "PT15.100000078S",
              "durationInSeconds": 15.1,
              "eventId": "8104385",
              "eventType": "impression",
              "startTime": "PT17.817798612S",
              "startTimeInSeconds": 17.817
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=start"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104385",
              "eventType": "start",
              "startTime": "PT17.817798612S",
              "startTimeInSeconds": 17.817
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=firstQuartile"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104386",
              "eventType": "firstQuartile",
              "startTime": "PT21.592798631S",
              "startTimeInSeconds": 21.592
            },
             {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=midpoint"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104387",
              "eventType": "midpoint",
              "startTime": "PT25.367798651S",
              "startTimeInSeconds": 25.367
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=thirdQuartile"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104388",
              "eventType": "thirdQuartile",
              "startTime": "PT29.14279867S",
              "startTimeInSeconds": 29.142
            },
            {
              "beaconUrls": [
                "http://exampleadserver.com/tracking?event=complete"
              ],
              "duration": "PT0S",
              "durationInSeconds": 0.0,
              "eventId": "8104390",
              "eventType": "complete",
              "startTime": "PT32.91779869S",
              "startTimeInSeconds": 32.917
            }
          ]
        }
      ],
      "availId": "8104385",
      "duration": "PT15.100000078S",
      "durationInSeconds": 15.1,
      "startTime": "PT17.817798612S",
      "startTimeInSeconds": 17.817
    }
  ]
}
```

# 混合模式搭配伺服器端廣告信標
<a name="ad-reporting-hybrid-mode"></a>

MediaTailor 支援混合模式進行工作階段追蹤。在此模式中，服務會發出播放相關的廣告追蹤事件，但讓工作階段可使用完整的用戶端追蹤承載

若要使用播放字首啟用混合追蹤，玩家會根據您的通訊協定，使用下列其中一種格式的請求初始化新的 MediaTailor 播放工作階段：

**Example ：HLS 格式**  

```
POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       },
       "reportingMode":"server"
    }
```

**Example ：DASH 格式**  

```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       },
       "reportingMode":"server"
    }
```

MediaTailor 會在混合模式中維護下列追蹤事件：
+ 印象
+ Start
+ 第一分位數
+ 中點
+ 第三分位數
+ 完成
+ `breakStart` (vmap)
+ `breakEnd` (vmap)

# 用戶端廣告追蹤整合
<a name="ad-reporting-client-side-ad-tracking-integrations"></a>

本節說明 MediaTailor 與各種用戶端廣告追蹤伺服器之間的整合。

**Topics**
+ [開啟測量 SDK](#ad-reporting-client-side-ad-tracking-integrations-open-measurement-sdk)
+ [Datazoom 免費播放器 SDKs](#ad-reporting-client-side-ad-tracking-integrations-dz)
+ [Roku 廣告架構 (RAF)](#ad-reporting-client-side-ad-tracking-integrations-raf)
+ [TheoPlayer](#ad-reporting-client-side-ad-tracking-integrations-theoplayer)
+ [MediaTailor SDK](#ad-reporting-client-side-ad-tracking-integrations-mediatailor-sdk)

## 開啟測量 SDK
<a name="ad-reporting-client-side-ad-tracking-integrations-open-measurement-sdk"></a>

互動式廣告局 (IAB) 開放式測量 SDK (OM SDK) 可促進提供給 Web 影片和原生應用程式環境之廣告的第三方可視性和驗證測量。

對於較舊的 VAST 第 3 版文件，驗證碼應與延伸節點一起載入，延伸類型為 `AdVerifications`。延伸節點的根`AdVerifications`節點具有與 VAST 4.1 元素相同的結構描述。

為了簡化 OM 開發套件的採用，MediaTailor 已與 Datazoom 合作，提供免費玩家SDKs，這些開發套件已針對 Open Measurement 進行設定和驗證。如需詳細資訊，請參閱[Datazoom 免費播放器 SDKs](#ad-reporting-client-side-ad-tracking-integrations-dz)。

**注意**  
MediaTailor 目前僅支援 VAST 第 3 版。

**Example ：VATT 3 中的驗證節點，4.1 版之前**  

```
...
<Extensions>
    <Extension type="AdVerifications">
        <AdVerifications>
            <Verification vendor="company.com-omid">
                <JavaScriptResource apiFramework="omid" browserOptional="true">
                    <![CDATA[https://verification.com/omid_verification.js]]>
                </JavaScriptResource>
                <TrackingEvents>
                    <Tracking event="verificationNotExecuted">
                        <![CDATA[https://verification.com/trackingurl]]>
                    </Tracking>
                </TrackingEvents>
                <VerificationParameters>
                    <![CDATA[verification params key/value pairs]]>
                </VerificationParameters>
            </Verification>
        </AdVerifications>
    </Extension>
</Extensions>
```

MediaTailor 會從`<Extensions>`節點擷取`AdVerifications`資料，並將其放入用戶端追蹤回應中的`adVerifications`陣列。

**Example ：用戶端追蹤回應中的 adVerifications 陣列**  

```
{
  "avails": [
    {
      "adBreakTrackingEvents": [],
      "adMarkerDuration": null,
      "ads": [
        {
          "adId": "3062770",
          "adParameters": "",
          "adProgramDateTime": "2023-08-23T16:25:40.914Z",
          "adSystem": "2.0",
          "adTitle": "AD-polarbear-15",
          "adVerifications": [
            {
              "executableResource": [],
              "javaScriptResource": [
                {
                  "apiFramework": "omid",
                  "browserOptional": "true",
                  "uri": "https://verification.com/omid_verification.js"
                }
              ],
              "trackingEvents": [
                {
                  "event": "verificationNotExecuted",
                  "uri": "https://verification.com/trackingurl"
                }
              ],
              "vendor": "company.com-omid",
              "verificationParameters": "verification params key value pairs"
            }
          ],
          "companionAds": [],
          "creativeId": "00006",
          "creativeSequence": "1",
          "duration": "PT14.982S",
          "durationInSeconds": 14.982,
          "extensions": [
            {
              "content": "<AdVerifications>\n\t\t\t\t\t\t<Verification vendor=\"company.com-omid\">\n\t\t\t\t\t\t\t<JavaScriptResource apiFramework=\"omid\" browserOptional=\"true\"><![CDATA[https://verification.com/omid_verification.js;]]></JavaScriptResource>\n\t\t\t\t\t\t\t<TrackingEvents>\n\t\t\t\t\t\t\t\t<Tracking event=\"verificationNotExecuted\"><![CDATA[;https://verification.com/trackingurl;]]></Tracking>\n\t\t\t\t\t\t\t</TrackingEvents>\n\t\t\t\t\t\t\t<VerificationParameters><![CDATA[verification params key/value pairs;]]></VerificationParameters>\n\t\t\t\t\t\t</Verification>\n\t\t\t\t\t</AdVerifications>",
              "type": "AdVerifications"
            }
          ],
          "mediaFiles": {
            "mediaFilesList": [],
            "mezzanine": ""
          },
          "skipOffset": null,
          "startTime": "PT10.11S",
          "startTimeInSeconds": 10.11,
          "trackingEvents": [
            {
              "beaconUrls": [
                "https://n8ljfs0h09.execute-api.us-west-2.amazonaws.com/v1/impression"
              ],
              "duration": "PT14.982S",
              "durationInSeconds": 14.982,
              "eventId": "3062770",
              "eventProgramDateTime": null,
              "eventType": "impression",
              "startTime": "PT10.11S",
              "startTimeInSeconds": 10.11
            }
          ],
          "vastAdId": ""
        }
      ],
      "availId": "3062770",
      "availProgramDateTime": "2023-08-23T16:25:40.914Z",
      "duration": "PT14.982S",
      "durationInSeconds": 14.982,
      "meta": null,
      "nonLinearAdsList": [],
      "startTime": "PT10.11S",
      "startTimeInSeconds": 10.11
    }
  ],
  "dashAvailabilityStartTime": null,
  "hlsAnchorMediaSequenceNumber": null,
  "nextToken": "UFQxMC4xMVNfMjAyMy0wOC0yM1QxNjoyNjoyNC4yNDYxMDIxOTBaXzE%3D",
  "nonLinearAvails": []
}
```

**注意**  
與 IAB Tech Lab 互動，以確保應用程式每年獲得認證，以確保合規性。

如需 OM SDK 的詳細資訊，請參閱 IAB Tech Lab 網站上的 [Open Measurement SDK](https://iabtechlab.com/standards/open-measurement-sdk/)。

## Datazoom 免費播放器 SDKs
<a name="ad-reporting-client-side-ad-tracking-integrations-dz"></a>

為了更容易採用玩家SDKs，MediaTailor 已與 Datazoom 合作，提供使用 和 [與 Google Ad Manager 的用戶端 AWS Elemental MediaTailor 整合](gam-integration-pal.md) IAB Tech 設定和測試的免費玩家SDKs[開啟測量 SDK](#ad-reporting-client-side-ad-tracking-integrations-open-measurement-sdk)。

Datazoom 播放器 SDK 支援下列功能：
+ 即時和 VOD 播放清單
+ DASH 和 HLS 規格
+ 玩家廠商支援 Bitmovin、exoplayer、Android 媒體播放器、Apple AVPlayer、Brightcove、Chromecast Receiver、Dash.js、hls.js、JWPlayer、Shaka player、 THEO player、Video.js、Roku 等
+ IAB Tech Lab Open Measurement 認證，在所選裝置上可用
+ 點擊式事件處理
+ 廣告事件發送器，例如廣告倒數計時器、廣告浮水印和非線性事件、廣告休息時間開始、廣告休息時間結束
+ 用戶端廣告信標
+ Google 程式設計存取程式庫 (PAL) SDK，作為選用的組態設定

Datazoom 也提供玩家 SDKs 支援的付費分析和遙測服務。客戶可以從 Datazoom 管理主控台選擇加入和控制玩家 SDK 遙測。若要存取 Datazoom 播放器 SDKs，以及進一步了解附加價值遙測和分析服務，請使用 [Datazoom 網站上的](https://www.datazoom.io/partner-aws)聯絡資訊。

## Roku 廣告架構 (RAF)
<a name="ad-reporting-client-side-ad-tracking-integrations-raf"></a>

Roku 廣告架構 (RAF) 在整個 Roku 平台上維持一致的廣告體驗。所有頻道，包括影片廣告，必須符合 Roku 的 RAF 認證要求。值得注意的是，應用程式必須一律使用透過 RAF 觸發的用戶端事件。MediaTailor 作為伺服器端廣告插入 (SSAI) 供應商，支援用戶端事件觸發。RAFX SSAI 轉接器提供 SSAI 資訊清單伺服器或接合器和 RAF 的介面。這些界面包括：
+ 剖析`masterURL`回應並擷取 `playURL`、 `AdURL`和廣告中繼資料。
+ 將 MediaTailor SSAI 廣告中繼資料轉換為可使用 RAF 的廣告中繼資料，並設定 RAF 進行播放。
+ 觀察串流事件和定時中繼資料。
+ 即時比對串流事件、廣告中繼資料和射擊事件像素。
+ `AdURL`依 MediaTailor SSAI 資訊清單伺服器的需求 Ping/polling ，然後剖析並重新設定 RAF。

如需 RAF SSAI 轉接器的詳細資訊，請參閱 [Roku 網站上的使用 Roku 轉接器實作伺服器端廣告插入](https://developer.roku.com/docs/developer-program/advertising/ssai-adapters.md)。

## TheoPlayer
<a name="ad-reporting-client-side-ad-tracking-integrations-theoplayer"></a>

與 MediaTailor 的 TheoPlayer 整合會執行下列動作：
+ 為 VOD 和即時工作流程提供支援 HLS 和 DASH 的 MediaTailor 用戶端事件追蹤功能。
+ 僅支援線性廣告傳送追蹤信標。
+ 停用廣告期間的搜尋。不過，當使用者尋求超過廣告休息時間時，沒有用於播放廣告的邏輯。

如需 TheoPlayer 中 SSAI 的詳細資訊，以及檢閱適用於 MediaTailor 的 Web、Android、iOS 和 tvOS SDKs，請參閱 TheoPlayer 網站上的 [MediaTailor](https://docs.theoplayer.com/how-to-guides/01-ads/12-mediatailor.md)。

## MediaTailor SDK
<a name="ad-reporting-client-side-ad-tracking-integrations-mediatailor-sdk"></a>

AWS Elemental 維護以 JavaScript 為基礎的軟體開發套件 (SDK)。 AWS Elemental 依原狀提供 SDK，沒有隱含保證。使用 SDK 做為參考示範，以簡化您使用 MediaTailor 的入門。開發套件示範如何與 MediaTailor 用戶端追蹤 API 互動。SDK 實作 HTML5-based玩家的用戶端廣告追蹤和報告。SDK 會初始化 MediaTailor 用戶端報告工作階段，然後定期請求廣告追蹤資訊。在播放期間，軟體開發套件會在偵測到新的廣告事件時發出廣告追蹤事件。

MediaTailor SDK 支援下列功能：
+ 即時和 VOD 播放清單
+ DASH 和 HLS 規格
+ 點擊式事件處理
+ 廣告事件發送器
+ 自訂事件掛鉤
+ 用戶端廣告信標。如需傳送廣告信標的詳細資訊，請參閱 [用戶端信標](ad-reporting-client-side-beaconing.md)。

**注意**  
提交 AWS 支援票證以接收 MediaTailor 的 JavaScript 開發套件範例。您會收到套件及其檔案的下載連結。

## 使用 GetTracking 分頁廣告信標
<a name="gettracking"></a>

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

`GetTracking` 傳回一個`NextToken`值，您可以透過分頁傳回的信標清單來縮小傳回信標的數量。您可以循環瀏覽這些`NextToken`值，以尋找廣告信標`StartTimeInSeconds`欄位的所需值。
+ 在第一次呼叫 時`GetTracking`，會傳回資訊清單視窗中的所有可能廣告，包括每個廣告的 `NextToken`和 值。
+ 如果`GetTracking`請求*不包含* `NextToken`，則會傳回資訊清單視窗中的所有廣告。
+ 如果`GetTracking`請求包含 ，`NextToken`但沒有要傳回的新信標，MediaTailor 會傳回您在原始請求上傳送`NextToken`的相同值。
+ 當沒有更多與廣告對應的信標時， 會從其回應`GetTracking`中移除該廣告。
+ 的權杖會在 24 小時後`GetTracking`過期。如果`NextToken`值超過 24 小時，下次呼叫 會`GetTracking`傳回 null 值 `NextToken`。

### 從玩家進行 GetTracking 的廣義呼叫序列
<a name="gettracking.generalsequence"></a>

從用戶端播放器，`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. 如有必要，請再次循環播放傳回的廣告，直到您找到要播放的確切廣告為止。

#### 延伸範例
<a name="gettracking.extendedexample"></a>

此範例說明如何使用 `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
    }
  ]
}
```