Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Konstruksi tawaran dan templating Halaman ini menjelaskan cara membuat MediaTailor permintaan tawaran OpenRTB dari template Anda, cara kerja interpolasi variabel, dan nilai apa yang ditetapkan secara otomatis. MediaTailor ## Bidang konfigurasi Saat Anda mengaktifkan Pengoptimalan Hasil pada konfigurasi pemutaran, Anda menyediakan empat bidang: | Bidang | Deskripsi | Diperlukan | | --- | --- | --- | | PublisherId | ID penerbit APS Anda (diperoleh dari pendaftaran APS). Disuntikkan ke dalam app.publisher.id setiap permintaan tawaran. | Ya | | Region | Wilayah APS: AMERICASEUROPE,, atauASIA\_PACIFIC. Menentukan titik akhir APS. | Ya | | MinimumUnfilledDuration | Detik minimum yang belum terisi diperlukan sebelum MediaTailor memicu permintaan tawaran. Juga digunakan sebagaiimp.video.minduration. | Ya | | OpenRtbTemplate | Template ORTB JSON Anda (maks 100 KB). Mendefinisikan badan permintaan tawaran. | Ya | ## Bagaimana permintaan tawaran dibuat Jika jeda iklan memiliki durasi yang tidak terisi tersisa, MediaTailor membuat permintaan tawaran dengan langkah-langkah berikut: 1. **Interpolasi template. ** MediaTailor menyelesaikan`{{session.*}}`,,,`{{player_params.*}}`, `{{avail.*}}` `{{request.*}}``{{asset.*}}`, dan `{{scte.*}}` placeholder di template Anda menggunakan sintaks templating [ Mustache standar. ](https://mustache.github.io/mustache.5.html) Kumis menggunakan tanda kurung keriting ganda`{{ }}`, yang berbeda dari tanda kurung persegi yang `[ ]` digunakan dalam substitusi variabel URL ADS. 1. **Penguraian JSON. ** Template yang diinterpolasi diurai sebagai JSON. 1. **Ekstraksi lapangan dan validasi. ** MediaTailormengekstrak bidang wajib dan melempar `BidRequestConfigurationError` jika ada yang hilang atau kosong. 1. **Injeksi lapangan hardcode. ** MediaTailor mengganti atau menyuntikkan bidang yang dikelolanya secara otomatis menggunakan nilai dari konfigurasi konsol dan konteks yang tersedia saat ini (misalnya, `app.publisher.id` dari ID Penerbit yang dikonfigurasi, dari durasi tak ter `imp.video.maxduration` isi yang dihitung). 1. **Serialisasi dan penyerahan. ** Final BidRequest diserialkan ke JSON dan dikirim sebagai HTTP POST ke titik akhir APS. **penting** Jika ada bidang wajib yang hilang atau kosong setelah interpolasi, permintaan tawaran gagal dengan `BidRequestConfigurationError` a dan tidak ada permintaan yang dikirim ke APS. Kesalahan dicatat tetapi pemutaran berlanjut secara normal (gagal-buka). ## Template default konsol Saat Anda mengaktifkan Pengoptimalan Hasil di MediaTailor konsol, templat yang telah diisi sebelumnya berikut disediakan sebagai titik awal. Anda harus menyesuaikan nilai untuk aplikasi Anda: ``` { "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 penjelasan: ** | Bidang | Kategori | Apa yang harus dilakukan | | --- | --- | --- | | imp[0].bidfloor | Opsional (default: 1.0) | Tetapkan CPM minimum Anda. Default konsol adalah $5. Lebih rendah untuk tingkat pengisian yang lebih baik selama pengujian. | | app.id | APS Direkomendasikan | Pengidentifikasi aplikasi Anda. Pemain harus mengirimplayerParams.app\_id. | | app.name | APS Direkomendasikan | Nama aplikasi Anda. Pemain harus mengirimplayerParams.app\_name. | | app.bundle | Wajib | ID bundel aplikasi Anda. Pemain harus mengirimplayerParams.bundle, atau mengganti dengan nilai statis (disarankan). | | app.storeurl | Wajib | URL toko aplikasi Anda. Pemain harus mengirimplayerParams.storeurl, atau mengganti dengan nilai statis (disarankan). | | app.domain | APS Direkomendasikan | Domain aplikasi Anda. Pemain harus mengirimplayerParams.domain. | | app.content.genre | APS Direkomendasikan | Diisi dari metadata aset sumber konten. | | app.content.contentrating | APS Direkomendasikan | Diisi dari metadata aset sumber konten. | | device.dnt | APS Direkomendasikan | Bendera Jangan Lacak. Pemain harus mengirimplayerParams.dnt. | | device.ua | Wajib | Secara otomatis diisi dari User-Agent header pemirsa hingga{{session.user\_agent}}. Tidak diperlukan parameter pemain. | | device.ip | Wajib | Secara otomatis diisi dari IP pemirsa melalui{{session.client\_ip}}. Tidak diperlukan parameter pemain. | | device.ifa | APS Direkomendasikan | ID Iklan. Pemain harus mengirimplayerParams.device\_ifa. | | device.w / device.h | APS Direkomendasikan | Dimensi layar. Pemain harus mengirimplayerParams.device\_width/device\_height. | | device.language | APS Direkomendasikan | Bahasa perangkat. Pemain harus mengirimplayerParams.language. | | device.model | APS Direkomendasikan | Model perangkat. Pemain harus mengirimplayerParams.model. | | device.os / device.osv | APS Direkomendasikan | OS dan versi. Pemain harus mengirimplayerParams.os/osv. | | device.devicetype | Dapat diganti (default: 3) | Jenis perangkat IAB. Pemain harus mengirimplayerParams.devicetype. Defaultnya 3 (CTV) jika kosong. | | device.make | APS Direkomendasikan | Produsen perangkat. Pemain harus mengirimplayerParams.make. | | user.consent | APS Direkomendasikan (UE) | String persetujuan GDPR (TCF). Pemain harus mengirimplayerParams.consent. | | regs.gdpr | APS Direkomendasikan (UE) | Bendera GDPR (0 atau 1). Pemain harus mengirimplayerParams.gdpr. | | regs.us\_privacy | APS Direkomendasikan (AS) | String CCPA (misalnya,1YNY). Pemain harus mengirimplayerParams.us\_privacy. | | regs.gpp | APS Direkomendasikan | String persetujuan Platform Privasi Global. Pemain harus mengirimplayerParams.gpp\_consent. Lebih disukai us\_privacy untuk tingkat pengisian yang lebih baik. | | regs.gpp\_sid | APS Direkomendasikan | ID bagian GPP (misalnya, [7] untuk Nasional AS). Pemain harus mengirimplayerParams.gpp\_sid. | **penting** Default konsol digunakan `{{player_params.*}}` untuk bidang wajib seperti `app.bundle` dan`app.storeurl`. Jika pemain Anda tidak mengirimkan parameter ini, permintaan tawaran akan gagal`BidRequestConfigurationError`. Untuk bidang yang sama untuk setiap sesi (biasanya`app.bundle`,, `app.storeurl``app.name`, dan pengidentifikasi tingkat aplikasi lainnya), pertimbangkan untuk mengganti placeholder dengan nilai statis (misalnya,). `"bundle": "com.yourcompany.app"` Jangan membuat hardcode bidang yang bervariasi per penampil, seperti`device.ua`,, `device.ip``device.ifa`, GDPR dan string persetujuan GPP, atau peraturan atau bidang objek pengguna apa pun. Itu harus berasal dari `{{session.*}}` atau`{{player_params.*}}`. **catatan** Default konsol tidak termasuk `video.mimes` atau `video.protocols` dalam template. MediaTailor menggunakan nilai fallback hardcode (`["video/mp4"]`untuk mimes, `[1,2,3,4,5,6,7,8]` untuk protokol) ketika ini tidak disediakan. Anda dapat menambahkannya ke template Anda jika Anda ingin membatasi format yang didukung. ## Interpolasi template (templating kumis) Template ORTB Anda menggunakan [ sintaks templating ](https://mustache.github.io/mustache.5.html) Mustache untuk substitusi nilai dinamis. Placeholder menggunakan tanda kurung keriting ganda. `{{ }}` ### Variabel template yang tersedia Template ORTB Anda dapat menggunakan variabel dinamis yang sama yang tersedia di templat URL ADS. Ini termasuk variabel sesi (misalnya,`{{session.user_agent}}`,`{{session.client_ip}}`), parameter pemain (`{{player_params.*}}`), metadata aset (`{{asset.*}}`), konteks tersedia (`{{avail.*}}`), dan data sinyal SCTE (`{{scte.*}}`). Untuk daftar lengkap variabel yang tersedia dan deskripsinya, lihat[MediaTailor variabel iklan dinamis untuk permintaan ADS](variables.md). Untuk bagaimana nilai parameter MediaTailor URL-decodes pemain sebelum menggantinya ke dalam template, lihat [Perilaku pengkodean dan decoding](#yield-optimization-bid-construction-encoding) nanti di halaman ini. Variabel yang paling umum digunakan dalam template ORTB adalah: + `{{session.user_agent}}`: User-Agent Header penampil (digunakan untuk`device.ua`). + `{{session.client_ip}}`: Alamat IP penampil (digunakan untuk`device.ip`). + `{{player_params.*}}`: Nilai khusus yang diteruskan oleh pemain selama inisialisasi sesi. + `{{asset.*}}`: Metadata konten dari asal (misalnya,`asset.genre`,`asset.content_rating`). **Awas** Selalu bungkus placeholder dalam tanda kutip, bahkan untuk bidang numerik seperti `dnt` atau. `devicetype` Jika placeholder diselesaikan ke string kosong dan tidak dikutip (misalnya,`"dnt": {{player_params.dnt}}`), hasilnya adalah JSON tidak valid dan seluruh permintaan tawaran gagal dengan a. `BidRequestConfigurationError` Gunakan `"dnt": "{{player_params.dnt}}"` sebagai gantinya. APS menerima bidang numerik yang diteruskan sebagai string. Perilaku ini dirancang karena substitusi string kosong mengutip otomatis akan bertentangan dengan mode Raw-JSON yang digunakan di tempat lain di interpolator. Kendala didokumentasikan daripada ditegakkan. Lihat juga [Perilaku pengkodean dan decoding](#yield-optimization-bid-construction-encoding) cara MediaTailor menangani nilai param pemain sebelum interpolasi. ### Cara melewati parameter pemain Ada dua cara untuk melewati parameter pemain selama inisialisasi sesi. **Metode 1: Permintaan POST dengan badan JSON (disarankan) ** ``` 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" } } ``` Metode ini lebih disukai karena menghindari URL-encoding masalah dengan nilai kompleks seperti string agen pengguna. **Metode 2: Parameter kueri URL ** ``` GET https:///v1/session///master.m3u8 ?playerParams.app_id=558775_example ``` Dengan metode ini, nilai harus ada URL-encoded. MediaTailor URL-decodes sebelum interpolasi. ### Perilaku pengkodean dan decoding MediaTailor melakukan ** satu tingkat decoding URL ** pada nilai parameter pemain sebelum menginterpolasinya ke dalam template. Ini berlaku terlepas dari bagaimana parameter dilewatkan (parameter kueri badan POST atau URL). **Contoh nilai yang didekodekan: ** | Nilai dikirim | Nilai setelah decoding (digunakan dalam template) | | --- | --- | | 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) | **Poin kunci: ** + MediaTailor mendekode ke ** satu tingkat saja**. Double-encoded nilai (misalnya,`%2520`) akan diterjemahkan ke`%20`, bukan ke spasi. + **Nilai tubuh POST ** juga diterjemahkan. Jika badan POST Anda berisi URL-encoded nilai, nilai-nilai tersebut akan diterjemahkan sebelum interpolasi. + **Nilai teks biasa ** (tanpa pengkodean) melewati tidak berubah. + Setelah decoding dan interpolasi, seluruh template diurai sebagai JSON. Karakter khusus dalam nilai yang diinterpolasi (seperti tanda kutip yang tidak lolos atau garis miring terbalik) dapat merusak penguraian JSON. **Tip** Jika pemain Anda mengirimkan nilai yang sudah berupa teks biasa (bukan URL-encoded), mereka bekerja apa adanya. Anda hanya perlu mengetahui decoding jika pemain Anda menilai URL-encodes sebelum mengirimnya. ### Apa yang terjadi ketika variabel hilang Jika pemain tidak mengirim parameter yang direferensikan dalam template Anda (misalnya, `{{player_params.app_name}}` tetapi tidak ada `app_name` di parameter pemain), placeholder diselesaikan ke string kosong. ** ** `""` **Damp ** ak: Jika string kosong berada di bidang wajib (seperti`app.bundle`), permintaan tawaran gagal`BidRequestConfigurationError`. Jika ada di bidang opsional, APS menerima nilai kosong yang dapat menyebabkan respons tanpa tawaran (HTTP 204). ## Apa yang MediaTailor ditetapkan secara otomatis Bidang berikut selalu diatur dengan MediaTailor menggunakan nilai dari konfigurasi konsol Anda dan konteks yang tersedia saat ini. Jika Anda menyertakan ini dalam template Anda, nilai-nilai Anda diganti: | Bidang | Sumber | | --- | --- | | id | Auto-generated: {sessionId}\_{availId} format (misalnya,abc123-def456\_78901). Berguna untuk menghubungkan permintaan tawaran dengan log sesi. | | app.publisher.id | Anda PublisherId dari konfigurasi konsol. | | imp[0].video.minduration | Anda MinimumUnfilledDuration dari konfigurasi konsol. | | imp[0].video.maxduration | Dihitung: detik aktual yang belum terisi untuk keuntungan ini. | | imp[0].video.maxseq | Dihitung:floor(unfilled\_duration / 6). | | imp[0].video.poddur | Dihitung: detik aktual yang belum terisi untuk keuntungan ini. | | ext.integrationType | Selalu disetel ke"EMT". | ## Langkah selanjutnya + Untuk referensi bidang demi bidang lengkap, lihat. [Referensi bidang ORTB](yield-optimization-ortb-reference.md) + Untuk templat copy-paste, lihat. [Contoh templat](yield-optimization-examples.md)