MediaTailor referensi parameter MediaTailor alias konfigurasi MediaTailor melewati parameter ADS MediaTailorpemecahan masalah alias

MediaTailor variabel iklan dinamis

AWS Elemental MediaTailor permintaan ke server keputusan iklan (ADS) mencakup informasi tentang sesi penayangan saat ini. Informasi ini membantu ADS memilih iklan terbaik untuk diberikan dalam tanggapannya. Saat mengonfigurasi template ADS dalam MediaTailor konfigurasi, Anda dapat menyertakan variabel dinamis, juga dikenal sebagai makro. Variabel dinamis adalah string yang dapat diganti.

Variabel dinamis dapat mengambil bentuk berikut:

Nilai statis — Nilai yang tidak berubah dari satu sesi ke sesi berikutnya. Misalnya, jenis respons yang MediaTailor diharapkan dari ADS.
Variabel domain — Variabel dinamis yang dapat digunakan untuk domain URL, seperti my-ads-serverbagian.com dari URL http://my-ads-server.com. Lihat perinciannya di MediaTailor variabel domain.
Data sesi — Nilai dinamis yang disediakan oleh MediaTailor untuk setiap sesi, misalnya, ID sesi. Lihat perinciannya di MediaTailor variabel sesi.
Data pemain — Nilai dinamis yang disediakan oleh pemain untuk setiap sesi. Ini menjelaskan penampil konten dan membantu ADS menentukan iklan mana yang MediaTailor harus dimasukkan ke dalam aliran. Lihat perinciannya di MediaTailor variabel pemain.

MediaTailor referensi parameter dan batasan

AWS Elemental MediaTailor memberikan informasi komprehensif tentang batasan karakter parameter, batasan panjang, dan format yang didukung untuk parameter kueri manifes dan parameter ADS.

Pembatasan karakter parameter kueri manifes

Parameter kueri manifes mendukung karakter tertentu dan memiliki batasan panjang yang ditentukan.

Karakter yang didukung (tanpa pengkodean URL)

Anda dapat menggunakan karakter berikut secara langsung dalam parameter kueri manifes:

Karakter alfanumerik (A-Z, a-z, 0-9)
Periode (.)
Tanda hubung (-)
Garis bawah (_)
Garis miring terbalik (\)

Karakter yang didukung dengan pengkodean URL

Karakter khusus berikut didukung saat dikodekan URL:

periode (.) = %2E
tanda hubung (-) = %2D
garis bawah (_) = %5F
persen (%) =% 25
tilde (~) = %7E
garis miring ke depan (/) = %2F
tanda bintang (*) = %2A
sama dengan (=) = %3D
pertanyaan (?) = %3F

Dukungan pengkodean URL

MediaTailor mendukung tanda persen (%) saat Anda menggunakannya dalam pengkodean URL (misalnya, hello%20world = hello world). Anda dapat menggunakan karakter yang dikodekan URL, selama mereka adalah pengkodean URL yang valid sesuai dengan spesifikasi HTTP.

Karakter yang tidak didukung

Anda tidak dapat menggunakan karakter berikut dalam parameter kueri manifes tanpa pengkodean URL::,,, ? & =%, / (garis miring maju).

penting

MediaTailor tidak mendukung karakter ganda seperti%%% atau ==. Anda tidak dapat menggunakan full URLs sebagai nilai parameter kueri manifes karena pembatasan karakter.

Keterbatasan panjang

Panjang total semua parameter kueri manifes (kunci dan nilai digabungkan) tidak boleh melebihi 2000 karakter.

Batasan panjang parameter ADS

Batasan panjang berikut berlaku untuk parameter yang digunakan dalam permintaan ke ADS:

Nama parameter ADS: Maksimum 10.000 karakter
Nilai parameter ADS: Maksimum 25.000 karakter
URL ADS: Maksimal 25.000 karakter

MediaTailor alias konfigurasi dan penggantian variabel dinamis

AWS Elemental MediaTailor alias konfigurasi memungkinkan penggantian variabel dinamis di domain URL dan bidang lain yang didukung. Gunakan fitur ini untuk menggunakan beberapa domain dan mengkonfigurasi secara dinamis URLs selama inisialisasi sesi.

Bidang yang didukung untuk penggantian variabel dinamis

Anda dapat menggunakan variabel dinamis di bidang konfigurasi berikut:

VideoContentSourceUrl
AdDecisionServerUrl
LivePreroll.AdDecisionServerUrl
AdSegmentUrlPrefix
ContentSegmentUrlPrefix
TranscodeProfileName
SlateAdUrl
StartUrl
EndUrl

Aturan parameter tingkat domain

Bila Anda menggunakan variabel dinamis di bagian domain URLs, pembatasan berikut berlaku:

Semua variabel dinamis yang digunakan dalam domain harus ditentukan sebagai ConfigurationAliases
Hanya bisa player_params
Daftar nilai alias harus lengkap
Alias tidak valid atau hilang menghasilkan kesalahan HTTP 400

ConfigurationAliases Struktur parameter API

ConfigurationAliases Parameter menggunakan struktur JSON berikut:


{
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
            "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        }
    }
}

Konsistensi API

playerParamssekarang didukung sebagai alternatif untuk ads dan adsParams untuk meningkatkan konsistensi API.

Perilaku mundur untuk alias yang hilang

Ketika alias konfigurasi tidak ditemukan atau tidak valid, MediaTailor mengimplementasikan perilaku fallback berikut:

Variabel domain: Jika alias variabel domain hilang atau tidak valid, permintaan gagal dengan kode status HTTP 400. Semua variabel domain harus memiliki alias yang valid didefinisikan.
Variabel non-domain: Untuk variabel yang digunakan dalam bagian non-domain URLs (seperti elemen jalur atau parameter kueri), alias yang hilang menghasilkan penggantian string kosong.
Validasi konfigurasi: MediaTailor memvalidasi bahwa semua alias yang diperlukan ada selama pembuatan konfigurasi dan operasi pembaruan.

Kasus penggunaan multi-konfigurasi tingkat lanjut

Alias konfigurasi memungkinkan arsitektur multi-konfigurasi canggih untuk skenario berikut:

Perutean geografis: Permintaan rute ke berbagai asal atau server iklan berdasarkan lokasi penampil menggunakan alias khusus wilayah. Untuk panduan implementasi, lihat CloudFront Origin Failover.
Perutean berbasis konten: Mengarahkan jenis konten yang berbeda ke asal khusus atau saluran pemrosesan. Untuk konfigurasi perilaku routing, lihatSiapkan perilaku perutean CDN untuk MediaTailor.
Skenario failover: Menerapkan asal cadangan dan server iklan dengan failover otomatis menggunakan alias switching. Untuk implementasi terperinci, lihat Menerapkan ketahanan Multi-wilayah untuk dengan MQAR MediaTailor danRencanakan integrasi CDN Anda untuk AWS Elemental MediaTailor.
Pengujian A/B: Uji berbagai server iklan, asal, atau konfigurasi dengan merutekan lalu lintas berdasarkan parameter pemain. Untuk panduan pengujian beban, lihat Mempersiapkan dan menjalankan pengujian kinerja untuk Amazon CloudFront dengan pemantauan pengguna nyata.
Pengoptimalan khusus perangkat: Optimalkan penayangan konten dan penayangan iklan untuk berbagai jenis atau kemampuan perangkat. Untuk panduan komprehensif, lihatSiapkan pemfilteran manifes dengan MediaTailor, MediaPackage, dan CDN.
Load balancing: Mendistribusikan beban di beberapa server asal atau iklan menggunakan perutean dinamis. Untuk panduan implementasi, lihat Menerapkan ketahanan Multi-wilayah untuk dengan MQAR MediaTailor danRencanakan integrasi CDN Anda untuk AWS Elemental MediaTailor.

contoh Konfigurasi lengkap dengan alias

Contoh berikut menunjukkan konfigurasi lengkap yang mencakup alias konfigurasi dan variabel domain dinamis:


PUT /playbackConfiguration
{
    "Name": "aliasedConfig",
    "AdDecisionServerUrl": "https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=[player_params.ad_type]",
    "VideoContentSourceUrl": "https://[player_params.origin_domain].mediapackage.[player_params.region].amazonaws.com/out/v1/[player_params.endpoint_id]",
    
    "AdSegmentUrlPrefix": "https://[player_params.ad_cdn_domain]/ads/",
    "ContentSegmentUrlPrefix": "https://[player_params.content_cdn_domain]/content/",
    "TranscodeProfileName": "[player_params.transcode_profile]",
    "SlateAdUrl": "https://[player_params.slate_domain]/slate/[player_params.slate_type].mp4",
    "StartUrl": "https://[player_params.tracking_domain]/start?session=[session.id]",
    "EndUrl": "https://[player_params.tracking_domain]/end?session=[session.id]",
    
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc",
            "iad": "xyz"
        },
        "player_params.region": {
            "pdx": "us-west-2",
            "iad": "us-east-1"
        },
        "player_params.endpoint_id": {
            "pdx": "abcd",
            "iad": "wxyz"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        },
        "player_params.ad_cdn_domain": {
            "pdx": "ads-west.cdn.example.com",
            "iad": "ads-east.cdn.example.com"
        },
        "player_params.content_cdn_domain": {
            "pdx": "content-west.cdn.example.com",
            "iad": "content-east.cdn.example.com"
        },
        "player_params.transcode_profile": {
            "mobile": "mobile_optimized",
            "desktop": "high_quality",
            "tv": "4k_profile"
        },
        "player_params.slate_domain": {
            "pdx": "slate-west.example.com",
            "iad": "slate-east.example.com"
        },
        "player_params.slate_type": {
            "standard": "default_slate",
            "branded": "brand_slate"
        },
        "player_params.tracking_domain": {
            "pdx": "tracking-west.example.com",
            "iad": "tracking-east.example.com"
        }
    }
}

contoh Inisialisasi sesi dengan alias

Menggunakan konfigurasi sebelumnya, buat permintaan inisialisasi sesi yang menentukan variabel pemain dan alias:


POST master.m3u8
{
    "playerParams": {
        "origin_domain": "pdx",
        "region": "pdx", 
        "endpoint_id": "pdx",
        "ad_type": "customized",
        "ad_cdn_domain": "pdx",
        "content_cdn_domain": "pdx",
        "transcode_profile": "mobile",
        "slate_domain": "pdx",
        "slate_type": "branded",
        "tracking_domain": "pdx"
    }
}

contoh Aliran pemrosesan parameter

MediaTailor menggantikan string alias dengan nilai yang dipetakan dalam alias konfigurasi. Pemrosesan menghasilkan permintaan berikut:

Permintaan ADS:


https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345

VideoContentSource permintaan:


https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd

AdSegmentUrlPrefix:
```
https://ads-west.cdn.example.com/ads/
```

ContentSegmentUrlPrefix:


https://content-west.cdn.example.com/content/

TranscodeProfileName:
```
mobile_optimized
```

SlateAdUrl:


https://slate-west.example.com/slate/brand_slate.mp4

StartUrl:


https://tracking-west.example.com/start?session=[session.id]

EndUrl:


https://tracking-west.example.com/end?session=[session.id]

MediaTailor meneruskan parameter ke ADS

AWS Elemental MediaTailor mendukung pengaturan variabel dinamis dalam MediaTailor permintaan ke ADS menggunakan langkah-langkah berikut.

Untuk informasi tentang pemformatan yang didukung untuk parameter kueri, lihatMediaTailor referensi parameter dan batasan.
Untuk alias konfigurasi dan variabel domain, lihatMediaTailor alias konfigurasi dan penggantian variabel dinamis.
Untuk penyesuaian tambahan pada permintaan ADS, lihat. Penggunaan lanjutan

Metode inisialisasi sesi

MediaTailor mendukung beberapa metode untuk inisialisasi sesi dan penerusan parameter:

POST dengan Badan Permintaan:


POST <master>.m3u8
{
    "adsParams": {"param1": "value1", "param2": "value2"},
    "playerParams": {"param3": "value3"}
}

Parameter Kueri di URL:


GET <master>.m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3

penting

Anda hanya dapat menentukan parameter sekali, pada waktu inisialisasi. Alias konfigurasi diselesaikan ke nilai aktual sebelum meneruskan.

Untuk meneruskan informasi sesi dan pemain ke ADS

Bekerja dengan ADS untuk menentukan informasi yang diperlukan untuk merespons kueri iklan AWS Elemental MediaTailor.
Buat konfigurasi MediaTailor yang menggunakan URL permintaan ADS template yang memenuhi persyaratan ADS. Di URL, sertakan parameter statis dan sertakan placeholder untuk parameter dinamis. Masukkan URL templat Anda di bidang server keputusan iklan konfigurasi.

Dalam contoh URL template berikut, correlation menyediakan data sesi, dan deviceType menyediakan data pemain:
```
https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType]
```
Pada pemain, konfigurasikan permintaan inisiasi sesi AWS Elemental MediaTailor untuk memberikan parameter untuk data pemain. Sertakan parameter Anda dalam permintaan inisiasi sesi, dan hilangkan dari permintaan berikutnya untuk sesi tersebut.

Jenis panggilan yang dilakukan pemain untuk menginisialisasi sesi menentukan apakah pemain (klien) atau MediaTailor (server) menyediakan pelaporan pelacakan iklan untuk sesi tersebut. Untuk informasi tentang dua opsi ini, lihatMelaporkan data pelacakan iklan .

Lakukan salah satu jenis panggilan berikut, tergantung apakah Anda menginginkan pelaporan pelacakan iklan sisi server atau klien. Dalam kedua contoh panggilan, userID ditujukan untuk ADS dan auth_token ditujukan untuk asal:
- (Opsi) Panggilan untuk pelaporan pelacakan iklan sisi server — Awali parameter yang ingin Anda kirim MediaTailor ke ADS. ads Biarkan awalan mati untuk parameter yang ingin Anda kirim MediaTailor ke server asal:
  
  Contoh berikut menunjukkan permintaan masuk untuk HLS dan DASH ke. AWS Elemental MediaTailor MediaTailor menggunakan deviceType dalam permintaannya ke ADS dan auth_token dalam permintaannya ke server asal.
  
  Contoh HLS:
```
GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh
```
  Contoh DASH:
```
GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh
```
- (Opsi) Panggilan untuk pelaporan pelacakan iklan sisi klien — Berikan parameter untuk ADS di dalam objek. adsParams
  
  Contoh HLS:
```
POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }
```
  Contoh DASH:
```
POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }
```

Saat pemain memulai sesi, AWS Elemental MediaTailor ganti variabel dalam URL permintaan ADS template dengan data sesi dan parameter pemainads. Ini melewati parameter yang tersisa dari pemain ke server asal.

contoh MediaTailor permintaan dengan variabel iklan

Contoh berikut menunjukkan panggilan ke ADS dan server asal AWS Elemental MediaTailor yang sesuai dengan contoh panggilan inisialisasi sesi pemain sebelumnya:

MediaTailor memanggil ADS dengan data sesi dan jenis perangkat pemain:
```
https://my.ads.server.com/path?correlation=896976764&deviceType=ipad
```

MediaTailor memanggil server asal dengan token otorisasi pemain.

Contoh HLS:


https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh

Contoh DASH:


https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh

Penggunaan lanjutan

Anda dapat menyesuaikan permintaan ADS dengan berbagai cara dengan data pemain dan sesi. Anda hanya perlu menyertakan nama host ADS.

Contoh berikut menunjukkan beberapa cara agar Anda dapat menyesuaikan permintaan Anda:

Gabungkan parameter pemain dan parameter sesi untuk membuat parameter baru. Contoh:
```
https://my.ads.com?key1=[player_params.value1][session.id]
```
Gunakan parameter pemain sebagai bagian dari elemen jalur. Contoh:
```
https://my.ads.com/[player_params.path]?key=value
```
Gunakan parameter pemain untuk melewati elemen jalur dan kunci itu sendiri, bukan hanya nilai. Contoh:
```
https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1]
```

MediaTailor konfigurasi alias pemecahan masalah

AWS Elemental MediaTailor menyediakan panduan pemecahan masalah sistematis untuk masalah alias konfigurasi umum dan skenario kesalahan.

Kesalahan validasi alias konfigurasi

Ketika alias konfigurasi hilang atau tidak valid, MediaTailor mengembalikan respons kesalahan tertentu untuk membantu mengidentifikasi masalah.

Skenario kesalahan umum

Tabel berikut menjelaskan kesalahan alias konfigurasi umum dan langkah-langkah resolusinya:

Kesalahan	Penyebab	Resolusi
HTTP 400: Alias parameter pemain tidak valid	Nilai parameter pemain tidak ditemukan di ConfigurationAliases	Verifikasi bahwa nilai parameter pemain ada sebagai kunci dalam ConfigurationAliases pemetaan yang sesuai
HTTP 400: Alias konfigurasi yang diperlukan tidak ada	Variabel domain yang digunakan tanpa ConfigurationAliases entri yang sesuai	Tambahkan parameter pemain yang hilang ConfigurationAliases dengan semua pemetaan alias yang diperlukan
HTTP 400: Validasi konfigurasi gagal	ConfigurationAliases struktur cacat atau tidak lengkap	Validasi struktur JSON dan pastikan semua variabel domain memiliki alias yang sesuai
Penggantian string kosong di URLs	Alias variabel non-domain tidak ditemukan	Tambahkan pemetaan alias yang hilang atau berikan nilai default di ConfigurationAliases

Daftar periksa validasi

Gunakan daftar periksa berikut untuk memvalidasi pengaturan alias konfigurasi Anda:

Cakupan variabel domain: Pastikan semua variabel yang digunakan dalam bagian domain URLs memiliki ConfigurationAliases entri yang sesuai
Kelengkapan alias: Verifikasi bahwa semua nilai parameter pemain yang mungkin disertakan sebagai kunci dalam pemetaan alias
Struktur JSON: Validasi bahwa ConfigurationAliases JSON diformat dan bersarang dengan benar
Penamaan parameter: Konfirmasikan bahwa semua parameter pemain menggunakan player_params. awalan
Konsistensi nilai: Pastikan nilai alias valid untuk tujuan penggunaannya (URLs, nama profil, dll.)

Resolusi alias konfigurasi debugging

Ikuti pendekatan sistematis ini untuk men-debug masalah resolusi alias konfigurasi.

Step-by-step metodologi debugging

Gunakan langkah-langkah berikut untuk mengidentifikasi dan menyelesaikan masalah alias konfigurasi:

Prosedur debugging alias konfigurasi

Verifikasi struktur konfigurasi: Konfirmasikan bahwa konfigurasi pemutaran Anda termasuk diformat dengan benar ConfigurationAliases


{
    "ConfigurationAliases": {
        "player_params.example_param": {
            "alias1": "value1",
            "alias2": "value2"
        }
    }
}

Periksa format parameter pemain: Pastikan inisialisasi sesi mencakup parameter pemain yang diformat dengan benar
```
{
    "playerParams": {
        "example_param": "alias1"
    }
}
```
Validasi pemetaan alias: Konfirmasikan bahwa nilai parameter pemain (“alias1") ada sebagai kunci dalam pemetaan ConfigurationAliases
Uji dengan konfigurasi sederhana: Mulailah dengan konfigurasi minimal untuk mengisolasi masalah
Memantau tanggapan kesalahan: Periksa respons MediaTailor kesalahan untuk pesan validasi tertentu
Verifikasi diselesaikan URLs: Konfirmasikan bahwa penyelesaian URLs akhir valid dan dapat diakses

Praktik terbaik alias konfigurasi

Ikuti praktik terbaik ini untuk memastikan implementasi alias konfigurasi yang andal.

Pertimbangan keamanan

Terapkan langkah-langkah keamanan berikut saat Anda menggunakan alias konfigurasi:

Validasi input: Validasi semua nilai parameter pemain sebelum menggunakannya dalam resolusi alias
Sanitasi nilai alias: Pastikan nilai alias hanya berisi karakter dan format yang diharapkan
Pembatasan domain: Batasi alias domain ke domain terkontrol yang tepercaya
Kontrol akses: Batasi modifikasi konfigurasi hanya untuk personel yang berwenang

Optimalisasi kinerja

Optimalkan kinerja alias konfigurasi dengan rekomendasi ini:

Minimalkan jumlah alias: Gunakan hanya alias yang diperlukan untuk mengurangi overhead pemrosesan
Penamaan yang efisien: Gunakan konvensi penamaan yang jelas dan konsisten untuk alias dan parameter
Nilai default: Berikan alias default yang masuk akal untuk kasus penggunaan umum
Caching konfigurasi: MediaTailor Caching konfigurasi leverage untuk meningkatkan kinerja

Pemeliharaan dan pemantauan

Pertahankan operasi alias konfigurasi yang andal dengan praktik berikut:

Validasi reguler: Validasi secara berkala bahwa semua pemetaan alias saat ini dan fungsional
Pemantauan kesalahan: Memantau kesalahan HTTP 400 yang terkait dengan alias yang hilang atau tidak valid
Dokumentasi: Menjaga dokumentasi yang jelas dari semua pemetaan alias dan tujuannya
Prosedur pengujian: Menerapkan pengujian komprehensif untuk semua kombinasi alias

Untuk informasi selengkapnya tentang penggunaan variabel domain, sesi, dan pemain dinamis, pilih topik yang berlaku.

Topik

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Iklan terkondisi

MediaTailor pemecahan masalah parameter