本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 競價建構和範本
此頁面說明 MediaTailor 如何從您的範本建置 OpenRTB 競價請求、變數插補的運作方式，以及 MediaTailor 自動設定哪些值。
## 組態欄位
當您在播放組態上啟用產出最佳化時，您會提供四個欄位：
| 欄位 | 說明 | 必要 |
| --- | --- | --- |
| PublisherId | 您的 APS 發佈者 ID （從 APS 註冊取得）。在每次出價請求app.publisher.id時注入 。 | 是 |
| Region | APS 區域：AMERICAS、 EUROPE或 ASIA\_PACIFIC。決定 APS 端點。 | 是 |
| MinimumUnfilledDuration | MediaTailor 觸發出價請求之前所需的最短未填充秒數。也用作 imp.video.minduration。 | 是 |
| OpenRtbTemplate | 您的 ORTB JSON 範本 （最大 100 KB)。定義出價請求內文。 | 是 |
## 如何建構出價請求
當廣告休息時間剩餘未填滿的持續時間時，MediaTailor 會在下列步驟中建構出價請求：
1. **範本插補。**MediaTailor 會使用標準 [Mustache 範本](https://mustache.github.io/mustache.5.html)語法來解析範本中的 `{{asset.*}}`、、`{{session.*}}``{{player_params.*}}``{{avail.*}}``{{request.*}}`、 和 預留`{{scte.*}}`位置。Mustache 使用雙大括號 `{{ }}`，這與 ADS URL 變數替換`[ ]`中使用的方括號不同。
1. **JSON 剖析。**插入的範本會剖析為 JSON。
1. **欄位擷取和驗證。**MediaTailor 會擷取必要欄位，並在有任何遺失或空白`BidRequestConfigurationError`時擲回 。
1. **硬式編碼欄位注入。**MediaTailor 會使用主控台組態中的值和目前時段內容 （例如，`app.publisher.id`從設定的發佈者 ID，`imp.video.maxduration`從計算的未填充持續時間） 來覆寫或插入其自動管理的欄位。
1. **序列化和提交。**最終 BidRequest 會序列化至 JSON，並以 HTTP POST 的形式傳送至 APS 端點。
**重要**
如果插入後有任何必要欄位遺失或空白，競價請求會失敗，且`BidRequestConfigurationError`不會將請求傳送至 APS。會記錄錯誤，但繼續正常播放 （失敗開啟）。
## 主控台預設範本
當您在 MediaTailor 主控台中啟用產出最佳化時，會提供下列預先填入的範本做為起點。您應該為您的應用程式自訂值：
```
{
"imp": [
{
"bidfloor": 5
}
],
"app": {
"id": "{{player_params.app_id}}",
"name": "{{player_params.app_name}}",
"bundle": "{{player_params.bundle}}",
"storeurl": "{{player_params.storeurl}}",
"domain": "{{player_params.domain}}",
"content": {
"genre": "{{asset.genre}}",
"contentrating": "{{asset.content_rating}}"
}
},
"device": {
"dnt": "{{player_params.dnt}}",
"ua": "{{session.user_agent}}",
"ip": "{{session.client_ip}}",
"ifa": "{{player_params.device_ifa}}",
"w": "{{player_params.device_width}}",
"h": "{{player_params.device_height}}",
"language": "{{player_params.language}}",
"model": "{{player_params.model}}",
"os": "{{player_params.os}}",
"osv": "{{player_params.osv}}",
"devicetype": "{{player_params.devicetype}}",
"make": "{{player_params.make}}"
},
"user": {
"consent": "{{player_params.consent}}"
},
"regs": {
"gdpr": "{{player_params.gdpr}}",
"us_privacy": "{{player_params.us_privacy}}",
"gpp": "{{player_params.gpp_consent}}",
"gpp_sid": "{{player_params.gpp_sid}}"
}
}
```
**Field-by-field說明：**
| 欄位 | Category | 處理方式 |
| --- | --- | --- |
| imp[0].bidfloor | 選用 （預設：1.0) | 設定您的最低 CPM。主控台預設為 5 美元。較低的 可在測試期間獲得更好的填充率。 |
| app.id | APS 建議 | 您的應用程式識別符。玩家必須傳送 playerParams.app\_id。 |
| app.name | APS 建議 | 您的應用程式名稱。玩家必須傳送 playerParams.app\_name。 |
| app.bundle | 強制性 | 您的應用程式套件 ID。玩家必須傳送 playerParams.bundle，或以靜態值取代 （建議）。 |
| app.storeurl | 強制性 | 您的應用程式存放區 URL。玩家必須傳送 playerParams.storeurl，或以靜態值取代 （建議）。 |
| app.domain | APS 建議 | 您的應用程式網域。玩家必須傳送 playerParams.domain。 |
| app.content.genre | APS 建議 | 填入內容來源資產中繼資料。 |
| app.content.contentrating | APS 建議 | 填入內容來源資產中繼資料。 |
| device.dnt | APS 建議 | 請勿追蹤旗標。玩家必須傳送 playerParams.dnt。 |
| device.ua | 強制性 | 透過 從檢視器的使用者代理程式標頭自動填入{{session.user\_agent}}。不需要玩家參數。 |
| device.ip | 強制性 | 透過 從檢視器的 IP 自動填入{{session.client\_ip}}。不需要玩家參數。 |
| device.ifa | APS 建議 | 廣告 ID。玩家必須傳送 playerParams.device\_ifa。 |
| device.w / device.h | APS 建議 | 螢幕維度。玩家必須傳送 playerParams.device\_width / device\_height。 |
| device.language | APS 建議 | 裝置語言。玩家必須傳送 playerParams.language。 |
| device.model | APS 建議 | 裝置模型。玩家必須傳送 playerParams.model。 |
| device.os / device.osv | APS 建議 | 作業系統和版本。玩家必須傳送 playerParams.os / osv。 |
| device.devicetype | 可覆寫 （預設：3) | IAB 裝置類型。玩家必須傳送 playerParams.devicetype。如果為空，則預設為 3 (CTV)。 |
| device.make | APS 建議 | 裝置製造商。玩家必須傳送 playerParams.make。 |
| user.consent | APS 建議 (EU) | GDPR 同意字串 (TCF)。玩家必須傳送 playerParams.consent。 |
| regs.gdpr | APS 建議 (EU) | GDPR 旗標 (0 或 1)。玩家必須傳送 playerParams.gdpr。 |
| regs.us\_privacy | APS 建議 （美國） | CCPA 字串 （例如 1YNY)。玩家必須傳送 playerParams.us\_privacy。 |
| regs.gpp | APS 建議 | 全球隱私權平台同意字串。玩家必須傳送 playerParams.gpp\_consent。優先於 us\_privacy，以獲得更好的填充率。 |
| regs.gpp\_sid | APS 建議 | GPP IDs （例如，[7]美國國民）。玩家必須傳送 playerParams.gpp\_sid。 |
**重要**
主控台預設會將 `{{player_params.*}}`用於必要欄位，例如 `app.bundle`和 `app.storeurl`。如果您的玩家未傳送這些參數，競價請求將失敗，並顯示 `BidRequestConfigurationError`。對於每個工作階段相同的欄位 （通常是 `app.bundle`、`app.name`、 和其他應用程式層級識別符）`app.storeurl`，請考慮將預留位置取代為靜態值 （例如 `"bundle": "com.yourcompany.app"`)。請勿硬式編碼每個檢視器不同的欄位，例如 `device.ua`、`device.ip`、`device.ifa`、GDPR 和 GPP 同意字串，或任何規則或使用者物件欄位。這些必須來自 `{{session.*}}`或 `{{player_params.*}}`。
**注意**
主控台預設值不包含 範本`video.protocols`中的 `video.mimes`或 。未提供時，MediaTailor 會使用硬式編碼的後援值 (`["video/mp4"]` 代表 mimes， `[1,2,3,4,5,6,7,8]`代表通訊協定）。如果您想要限制支援的格式，您可以將它們新增至範本。
## 範本插補 (Mustache templating)
您的 ORTB 範本使用 [Mustache 範本](https://mustache.github.io/mustache.5.html)語法進行動態值替換。預留位置使用雙大括號 `{{ }}`。
### 可用的範本變數
您的 ORTB 範本可以使用 ADS URL 範本中可用的相同動態變數。這些包括工作階段變數 （例如，、`{{session.client_ip}}`)`{{session.user_agent}}`、玩家參數 (`{{player_params.*}}`)、資產中繼資料 (`{{asset.*}}`)、時段內容 (`{{avail.*}}`) 和 SCTE 訊號資料 ()`{{scte.*}}`。
如需可用變數的完整清單及其說明，請參閱 [ADS 請求的 MediaTailor 動態廣告變數](variables.md)。如需 MediaTailor URL 如何在將玩家參數值替換為範本之前解碼，請參閱本頁[編碼和解碼行為](#yield-optimization-bid-construction-encoding)稍後的 。
ORTB 範本中最常用的變數為：
+ `{{session.user_agent}}`：檢視器的 User-Agent 標頭 （用於 `device.ua`)。
+ `{{session.client_ip}}`：檢視器的 IP 地址 （用於 `device.ip`)。
+ `{{player_params.*}}`：玩家在工作階段初始化期間傳遞的自訂值。
+ `{{asset.*}}`：來自原始伺服器的內容中繼資料 （例如，`asset.genre`、`asset.content_rating`)。
**警告**
一律以引號包裝預留位置，即使是 `dnt`或 等數字欄位也是如此`devicetype`。如果預留位置解析為空字串且未引用 （例如 `"dnt": {{player_params.dnt}}`)，則結果為無效的 JSON，而且整個競價請求會失敗，並顯示 `BidRequestConfigurationError`。請改用 `"dnt": "{{player_params.dnt}}"`。APS 接受以字串傳遞的數值欄位。這種行為是設計成因為自動引用空字串替換會與插補器中其他位置使用的原始 JSON 模式衝突。已記錄限制條件，而不是強制執行。另請參閱[編碼和解碼行為](#yield-optimization-bid-construction-encoding)，了解 MediaTailor 如何在插入前處理玩家參數值。
### 如何傳遞玩家參數
有兩種方式可在工作階段初始化期間傳遞玩家參數。
**方法 1：使用 JSON 內文提出 POST 請求 （建議）**
```
POST https:///v1/session///master.m3u8
Content-Type: application/json
{
"playerParams": {
"app_id": "558775_example",
"slot_id": "608109df-2378-4bc5-8da5-24bc355f01a4",
"os": "Tizen",
"make": "Samsung",
"model": "Tizen TV",
"language": "en",
"us_privacy": "1YNY"
}
}
```
此方法為偏好方法，因為它可避免使用者代理程式字串等複雜值的 URL 編碼問題。
**方法 2：URL 查詢參數**
```
GET https:///v1/session///master.m3u8
?playerParams.app_id=558775_example
```
使用此方法時，值必須以 URL 編碼。MediaTailor URL 會在插入前解碼它們。
### 編碼和解碼行為
MediaTailor 在將玩家參數值插入範本之前，會先對玩家參數值執行**一個層級的 URL 解碼**。無論傳遞參數的方式為何 (POST 內文或 URL 查詢參數），這都適用。
**解碼值的範例：**
| 傳送的值 | 解碼後的值 （用於範本） |
| --- | --- |
| Test%20Os | Test Os |
| https%3A%2F%2Flocalhost | https://localhost |
| foo%20bar | foo bar |
| Mozilla%2F5.0%20(SMART-TV) | Mozilla/5.0 (SMART-TV) |
**重點：**
+ MediaTailor **只會解碼為一個層級**。雙編碼值 （例如 `%2520`) 將解碼為 `%20`，而不是空格。
+ **POST 內文值**也會解碼。如果您的 POST 內文包含 URL 編碼的值，則會在插入前解碼這些值。
+ **純文字值 **（無編碼） 傳遞不變。
+ 解碼和插補之後，整個範本會剖析為 JSON。插入值中的特殊字元 （例如未逸出的引號或反斜線） 可能會中斷 JSON 剖析。
**提示**
如果您的播放器傳送已經是純文字 （非 URL 編碼） 的值，則它們會正常運作。如果您的玩家 URL 編碼值在傳送之前，您只需要知道解碼。
### 當變數遺失時會發生什麼情況
如果播放器未傳送範本中參考的參數 （例如，`{{player_params.app_name}}`但播放器參數`app_name`中沒有 )，則預留位置會解析為**空字串** `""`。
**影響：**如果空字串位於必要欄位 （如 `app.bundle`)，則出價請求會失敗並顯示 `BidRequestConfigurationError`。如果它在選用欄位中，則 APS 會收到一個空值，這可能會導致無競價 (HTTP 204) 回應。
## MediaTailor 會自動設定哪些項目
MediaTailor 一律使用主控台組態中的值和目前時段內容來設定下列欄位。如果您在範本中包含這些項目，則會覆寫您的值：
| 欄位 | 來源 |
| --- | --- |
| id | 自動產生： {sessionId}\_{availId} 格式 （例如 abc123-def456\_78901)。用於將競價請求與工作階段日誌建立關聯。 |
| app.publisher.id | PublisherId 主控台組態中的 。 |
| imp[0].video.minduration | MinimumUnfilledDuration 主控台組態中的 。 |
| imp[0].video.maxduration | 計算：此時段的實際未填充秒數。 |
| imp[0].video.maxseq | 計算：floor(unfilled\_duration / 6)。 |
| imp[0].video.poddur | 計算：此時段的實際未填充秒數。 |
| ext.integrationType | 一律設定為 "EMT"。 |
## 後續步驟
+ 如需完整的field-by-field參考，請參閱 [ORTB 欄位參考](yield-optimization-ortb-reference.md)。
+ 如需複製貼上範本，請參閱 [範例 範本](yield-optimization-examples.md)。