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

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