翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# 入札の構築とテンプレート化
<a name="yield-optimization-bid-construction"></a>

このページでは、MediaTailor がテンプレートから OpenRTB 入札リクエストを構築する方法、変数補間の仕組み、MediaTailor が自動的に設定する値について説明します。

## 設定フィールド
<a name="yield-optimization-bid-construction-config-fields"></a>

再生設定で収量最適化を有効にする場合は、次の 4 つのフィールドを指定します。


| フィールド | 説明 | 必須 | 
| --- | --- | --- | 
| PublisherId | APS パブリッシャー ID (APS 登録から取得）。すべての入札リクエストapp.publisher.idで に挿入されます。 | はい | 
| Region | APS リージョン: AMERICAS、EUROPE、または ASIA\_PACIFIC。APS エンドポイントを決定します。 | はい | 
| MinimumUnfilledDuration | MediaTailor が入札リクエストをトリガーするまでに必要な最小未入力秒数。としても使用されますimp.video.minduration。 | はい | 
| OpenRtbTemplate | ORTB JSON テンプレート (最大 100 KB)。入札リクエスト本文を定義します。 | はい | 

## 入札リクエストの構築方法
<a name="yield-optimization-bid-construction-how"></a>

広告時間枠に未入力の期間が残っている場合、MediaTailor は次のステップで入札リクエストを作成します。

1. **テンプレート補間。**MediaTailor は`{{session.*}}`、標準の [Mustache テンプレート構文](https://mustache.github.io/mustache.5.html)を使用して、テンプレート内の 、`{{asset.*}}`、、`{{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 に送信されません。エラーはログに記録されますが、再生は正常に続行されます (失敗-オープン）。

## コンソールのデフォルトテンプレート
<a name="yield-optimization-bid-construction-default-template"></a>

MediaTailor コンソールで yield Optimization を有効にすると、開始点として次の事前入力済みテンプレートが提供されます。アプリケーションの値をカスタマイズする必要があります。

```
{
  "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 USD です。テスト中のフィルレートを向上させるには、 を低くします。 | 
| 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 推奨 | Do Not Track フラグ。プレイヤーは を送信する必要がありますplayerParams.dnt。 | 
| device.ua | 必須 | ビューワーの User-Agent ヘッダーから を介して自動的に入力されます{{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 推奨 | OS とバージョン。プレイヤーは 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。 | 

**重要**  
コンソールのデフォルトは、 `app.bundle`や などの必須フィールド`{{player_params.*}}`に を使用します`app.storeurl`。プレイヤーがこれらのパラメータを送信しない場合、入札リクエストは で失敗します`BidRequestConfigurationError`。すべてのセッションで同じフィールド (通常は `app.bundle`、`app.storeurl`、`app.name`、およびその他のアプリケーションレベルの識別子) の場合は、プレースホルダーを静的値 (例: ) に置き換えることを検討してください`"bundle": "com.yourcompany.app"`。`device.ua`、、、`device.ip``device.ifa`GDPR、GPP 同意文字列、reg やユーザーオブジェクトフィールドなど、ビューワーごとに異なるフィールドをハードコードしないでください。これらは `{{session.*}}`または から取得する必要があります`{{player_params.*}}`。

**注記**  
コンソールのデフォルトには、テンプレート`video.protocols`に `video.mimes`または は含まれません。MediaTailor は、ハードコードされたフォールバック値 (`["video/mp4"]`mimes の場合は 、プロトコル`[1,2,3,4,5,6,7,8]`の場合は ) を指定しない場合に使用します。サポートされている形式を制限する場合は、テンプレートに追加できます。

## テンプレート補間 (Mustache テンプレート)
<a name="yield-optimization-bid-construction-interpolation"></a>

ORTB テンプレートは[、動的値置換に Mustache テンプレート構文](https://mustache.github.io/mustache.5.html)を使用します。プレースホルダーは二重括弧 を使用します`{{ }}`。

### 使用可能なテンプレート変数
<a name="yield-optimization-bid-construction-variables"></a>

ORTB テンプレートは、ADS URL テンプレートで使用できるのと同じ動的変数を使用できます。これには、セッション変数 (、 など`{{session.client_ip}}`)`{{session.user_agent}}`、プレイヤーパラメータ ()、アセットメタデータ (`{{player_params.*}}`)、可用性コンテキスト (`{{asset.*}}`)、SCTE シグナルデータ (`{{avail.*}}`) が含まれます`{{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 は文字列として渡される数値フィールドを受け入れます。この動作は、空の文字列置換の自動引用が補間器の他の場所で使用されている raw-JSON モードと競合するため、設計上行われます。制約は強制されるのではなく文書化されます。MediaTailor [エンコードとデコードの動作](#yield-optimization-bid-construction-encoding)が補間前にプレイヤーパラメータ値を処理する方法については、「」も参照してください。

### プレイヤーパラメータを渡す方法
<a name="yield-optimization-bid-construction-pass-params"></a>

セッションの初期化中にプレイヤーパラメータを渡すには、2 つの方法があります。

**方法 1: JSON 本文を使用した POST リクエスト (推奨)**

```
POST https://<mediatailor-endpoint>/v1/session/<config-hash>/<origin-id>/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://<mediatailor-endpoint>/v1/session/<config-hash>/<origin-id>/master.m3u8
  ?playerParams.app_id=558775_example
```

この方法では、値は URL エンコードする必要があります。MediaTailor は、補間前に URL デコードします。

### エンコードとデコードの動作
<a name="yield-optimization-bid-construction-encoding"></a>

MediaTailor は、プレイヤーパラメータ値をテンプレートに補間する前に、**1 レベルの 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 は **1 つのレベルにのみ**デコードします。二重エンコードされた値 ( など`%2520`) は、スペースではなく `%20`にデコードされます。
+ **POST 本文の値**もデコードされます。POST 本文に URL エンコードされた値が含まれている場合、補間前にデコードされます。
+ **プレーンテキスト値** (エンコーディングなし) は変更されずにパススルーされます。
+ デコードと補間の後、テンプレート全体が JSON として解析されます。補間された値の特殊文字 (エスケープされていない引用符やバックスラッシュなど) は、JSON 解析を中断する可能性があります。

**ヒント**  
プレイヤーがすでにプレーンテキスト (URL エンコードされていない) の値を送信した場合、プレイヤーはそのまま動作します。デコードに注意する必要があるのは、送信する前にプレイヤー URL が値をエンコードする場合のみです。

### 変数が欠落している場合にどうなるか
<a name="yield-optimization-bid-construction-missing-variable"></a>

プレイヤーがテンプレートで参照されているパラメータを送信しない場合 (たとえば、プレイヤーパラメータ`app_name`に `{{player_params.app_name}}`がない場合）、プレースホルダーは**空の文字列** に解決されます`""`。

**影響:** 空の文字列が必須フィールド ( など`app.bundle`) にある場合、入札リクエストは で失敗します`BidRequestConfigurationError`。オプションフィールドにある場合、APS は入札なし (HTTP 204) レスポンスを引き起こす可能性のある空の値を受け取ります。

## MediaTailor が自動的に設定する内容
<a name="yield-optimization-bid-construction-auto-set"></a>

次のフィールドは常に、コンソール設定の値と現在の表示コンテキストを使用して 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"。 | 

## 次の手順
<a name="yield-optimization-bid-construction-next-steps"></a>
+ field-by-fieldリファレンスについては、「」を参照してください[ORTB フィールドリファレンス](yield-optimization-ortb-reference.md)。
+ コピー/貼り付けテンプレートについては、「」を参照してください[テンプレートの例](yield-optimization-examples.md)。