Pod Serve API menyediakan akses ke pod iklan video dengan kecepatan bit adaptif yang disiapkan sedemikian rupa sehingga dapat digabungkan langsung ke dalam playlist media HLS atau MPEG-DASH yang dilihat pengguna.
Panduan ini berfokus pada penerapan server manipulasi manifes Penayangan Pod dasar untuk streaming VOD.
Menerima permintaan manifes streaming
Manipulator manifes Anda harus menyediakan endpoint API untuk memproses permintaan manifes dari aplikasi klien pemutar video. Setidaknya, endpoint ini harus mengumpulkan ID streaming dari aplikasi pemutar klien. ID streaming ini digunakan untuk mengidentifikasi sesi streaming ke Ad Manager di permintaan pod iklan Anda.
Anda juga perlu mengumpulkan beberapa informasi lain untuk mengidentifikasi streaming konten yang sesuai, misalnya, ID konten.
Contoh endpoint permintaan manifes
GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Parameter jalur | |||||
---|---|---|---|---|---|
stream_id |
ID streaming Ad Manager dari aplikasi pemutar video klien. | ||||
content_id |
ID hipotetis yang sesuai dengan video konten di sistem Anda. | ||||
format |
Parameter hipotetis yang sesuai dengan format streaming. Salah satu dari:
|
Mengambil streaming konten
Gunakan ID konten yang dikumpulkan dari permintaan manifes untuk memilih aliran konten yang akan digabungkan dengan iklan.
Meminta manifes pod iklan
Untuk meminta iklan dari Ad Manager, server Anda harus membuat permintaan POST ke endpoint pod iklan, dengan meneruskan profil encoding, tag iklan, dan parameter penargetan yang diminta. Permintaan ini juga menyertakan ID aliran data yang Anda kumpulkan pada Langkah 1.
Sebagai hasilnya, Anda akan menerima daftar objek pod iklan yang berisi file manifes untuk pod iklan yang diminta oleh tag iklan penayang, serta informasi tentang waktu dan tempatnya disisipkan ke dalam konten Anda.
POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Parameter jalur | |
---|---|
network_code |
Kode jaringan Ad Manager 360 penayang. |
stream_id |
ID streaming dari aplikasi pemutar video klien. |
Isi JSON
Parameter isi | ||
---|---|---|
encoding_profiles |
Required |
Daftar representasi JSON dari profil encoding yang ingin Anda terima
untuk setiap jeda iklan. Lihat detail di bawah
Agar pemutaran berjalan selancar mungkin, setelan ini harus sesuai dengan kumpulan profil encoding yang digunakan dalam streaming konten Anda. |
ad_tag |
Required |
Tag iklan untuk meminta iklan VMAP. |
cuepoints |
Optional |
Daftar titik tanda dalam streaming konten tempat jeda iklan mid-roll akan disisipkan. Titik tanda diukur dalam detik floating point.
Hanya diperlukan untuk respons VMAP yang berisi mid-roll menggunakan offset waktu posisional. Hal ini jarang terjadi. |
content_duration_seconds |
Optional |
Durasi konten dalam hitungan detik.
Hanya diperlukan untuk respons VMAP yang berisi mid-roll menggunakan offset waktu percentage. Hal ini jarang terjadi. |
manifest_type |
Optional |
Format streaming iklan yang diminta, baik hls atau
dash . Nilai defaultnya adalah hls .
|
dai_options |
Optional |
Opsi tambahan yang mengontrol aspek terkait cara manifes dirender. Lihat detail di bawah |
Profil encoding | ||
profile_name |
Required |
ID untuk Profil Encoding ini. Nilai ini dapat berupa string apa pun yang Anda pilih, tetapi Anda tidak boleh memiliki beberapa profil encoding dengan nama yang sama di stream yang sama. |
type |
Required |
Jenis encoding streaming yang dijelaskan oleh profil encoding ini. Jenis
konten adalah: media , iframe , subtitles .
|
container_type |
Required |
Format penampung yang digunakan oleh profil encoding ini. Format penampung adalah:
mpeg2ts , fmp4cmaf , hls_packed_audio
|
video_settings |
Optional |
Wajib jika jenis profil encoding adalah iframe. Jika tidak, hanya izinkan jika jenis media berisi video. Lihat detailnya di bawah |
audio_settings |
Optional |
Wajib jika profil encoding berisi audio. Hanya diizinkan jika jenisnya adalah media. Lihat detail di bawah |
subtitle_settings |
Optional |
Wajib jika profil encoding berisi subtitel. Lihat detail di bawah |
Setelan video | ||
codec |
Required |
String codec RFC6381.
Contoh: |
bitrate |
Required |
Bilangan bulat yang menunjukkan kecepatan bit video maksimum profil ini dalam byte per detik. |
frames_per_second |
Required |
FPS floating point video. |
resolution |
Required |
Nilai yang dienkode JSON yang berisi `width` dan `height` video dalam piksel.
Contoh: |
Setelan audio | ||
codec |
Required |
String codec RFC6381.
Contoh: |
bitrate |
Required |
Bilangan bulat yang mewakili kecepatan bit audio maksimum profil ini dalam byte per
detik.
Contoh: |
channels |
Required |
Bilangan bulat yang mewakili jumlah saluran audio, termasuk saluran frekuensi rendah. |
sample_rate |
Required |
Bilangan bulat yang mewakili frekuensi sampling audio dalam hertz.
Contoh: |
Setelan subtitel | ||
format |
Required |
Format file yang digunakan oleh subtitel dalam band. Nilai yang didukung adalah
webvtt atau ttml .
|
language |
Optional |
Bahasa subtitel sebagai string bahasa RFC5646. Jika diberikan, nilai ini hanya digunakan untuk rendering DASH.
Contoh: |
Opsi DAI | ||
dash_profile |
Optional |
Profil MPEG-DASH untuk diterapkan ke manifes pod iklan. Setelan ini hanya digunakan untuk
manifes DASH. Nilai yang diizinkan adalah live atau
on-demand . Nilai defaultnya adalah on-demand .
Nilai
Nilai |
ad_pod_timeout |
Optional |
Waktu maksimum yang dihabiskan untuk memilih iklan dan membuat pod iklan, dalam detik floating point. Setelah waktu ini berlalu, Ad Manager akan menampilkan
iklan yang sudah dipilih di respons ad_pods dan berhenti
memproses.
|
sam_id |
Optional |
Menentukan kunci debug alternatif yang dapat digunakan untuk mencari sesi di pemantauan aktivitas streaming. |
Respons
Parameter respons | |
---|---|
valid_for |
Durasi yang valid untuk playlist pod iklan dalam format dhms
(hari, jam, menit, detik).
|
valid_until |
Tanggal dan waktu hingga playlist pod iklan ini valid sebagai string tanggal & waktu ISO8601, dalam format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
ad_pods |
Daftar pod iklan yang dipilih untuk streaming ini. |
Pod iklan | |
manifest_uris |
Hanya untuk streaming HLS. Peta encoding ID profil ke URI manifes HLS. |
mpd_uri |
Hanya untuk streaming DASH. URI DASH MPD. |
type |
Jenis pod iklan. Jenis pod iklan adalah: pre , mid , atau
post .
|
start |
Khusus untuk pod iklan mid-roll. Posisi dalam aliran data tempat pod iklan ini harus disisipkan, dalam detik floating point. |
duration |
Durasi pod iklan ini dalam detik floating point. |
midroll_index |
Khusus untuk pod iklan mid-roll. Indeks pod iklan mid-roll saat ini. Pengindeksan
dimulai dengan 1 .
|
Contoh permintaan (cURL)
curl -X POST \
-d '@request-body.json' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/streams/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/adpods
Contoh isi permintaan
Ini adalah konten request_body.json
yang dirujuk dalam panggilan cURL di atas.
{
"encoding_profiles": [
{
"profile_name": "1080p",
"type": "media",
"container_type": "mpeg2ts",
"video_settings": {
"codec": "avc1.4d000c",
"bitrate": 5000000,
"frames_per_second": 30.0,
"resolution": {
"width": 1920,
"height": 1080
}
},
"audio_settings": {
"codec": "mp4a.40.5",
"bitrate": 300000,
"channels": 2,
"sample_rate": 48000
}
},
{
"profile_name": "360p",
"type": "media",
"container_type": "mpeg2ts",
"video_settings": {
"codec": "avc1.4d000d",
"bitrate": 1000000,
"frames_per_second": 30.0,
"resolution": {
"width": 640,
"height": 360
}
},
"audio_settings": {
"codec": "mp4a.40.5",
"bitrate": 64000,
"channels": 2,
"sample_rate": 48000
}
},
{
"profile_name": "subtitles-webvtt",
"type": "subtitles",
"subtitle_settings": {
"format": "webvtt"
}
}
],
"ad_tag": "https://pubads.g.doubleclick.net/gampad/ads?...",
"manifest_type": "hls"
}
Contoh respons
{
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00",
"ad_pods": [
{
"manifest_urls":{
"1080p": "https://{...}/pod/0/profile/1080p.m3u8",
"360p": "https://{...}/pod/0/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt"
},
"type": "pre",
"duration": 10.0
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/1/profile/1080p.m3u8",
"360p": "https://{...}/pod/1/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/1/profile/subtitles-en.vtt"
},
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
},
{
"manifest_urls":{
]"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
"360p": "https://{...}/pod/2/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt""
},
"type": "post",
"duration": 10.0
}
]
}
Menggabungkan pod iklan ke dalam konten
Proses menggabungkan pod iklan ke dalam streaming konten bervariasi bergantung pada penerapan Anda, format streaming, dan fitur apa yang Anda pilih untuk diterapkan dari spesifikasi format. Alur kerja berikut adalah saran tentang cara menangani proses ini. Detail penerapan yang tepat dapat bervariasi, bergantung pada kebutuhan bisnis dan aliran konten Anda.
Streaming HLS
Jika Anda menggabungkan streaming dalam format HLS, streaming konten akan menjadi playlist multivarian yang berisi link ke manifes streaming terpisah, satu untuk setiap profil encoding. Pod iklan Anda harus disisipkan ke dalam setiap manifes varian ini. Salah satu cara untuk melakukannya adalah dengan menyiapkan semua manifes varian dan meneruskannya ke Jaringan Pengiriman Konten (CDN) untuk hosting. Playlist multi-varian terakhir adalah kumpulan link ke manifes yang dihosting oleh CDN ini.
Melakukan iterasi melalui profil encoding
Untuk setiap profil encoding, kumpulkan semua manifes pod iklan terkait dari
respons Ad Manager, beserta waktu mulai yang terkait. Untuk pod iklan pre-roll, tetapkan waktu mulai ke 0
. Untuk post-roll, gunakan durasi konten sebagai waktu mulai pod iklan. Identifikasi streaming varian di playlist multi-varian
yang cocok dengan setelan audio dan video setiap profil encoding.
Contoh array pod iklan
"ad_pods": [
{
"manifest_urls":{
"1080p": "https://{...}/pod/0/profile/1080p.m3u8",
"360p": "https://{...}/pod/0/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/0/profile/subitles-en.vtt"
},
"type": "pre",
"duration": 10.0
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/1/profile/1080p.m3u8",
"360p": "https://{...}/pod/1/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/1/profile/subitles-en.vtt"
},
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
"360p": "https://{...}/pod/2/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/2/profile/subitles-en.vtt"
},
"type": "post",
"duration": 10.0
}
]
Contoh playlist konten multi-varian
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://{...}/subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://{...}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://{...}/360p.m3u8
Contoh data varian yang dikumpulkan
Encoding profile: "1080p"
Profile settings: {...}
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
0 -> https://{...}/pod/0/profile/1080p.m3u8
15 -> https://{...}/pod/1/profile/1080p.m3u8
600 -> https://{...}/pod/2/profile/1080p.m3u8
Menyisipkan iklan ke setiap manifes varian
Untuk setiap streaming varian, periksa segmen manifes konten, dengan mempertahankan
total waktu konten yang telah berlalu. Saat Anda sampai di posisi awal
pod iklan, ekstrak daftar segmen dari manifes pod iklan, gabungkan
daftar segmen dalam dua tag #EXT-X-DISCONTINUITY
, dan sisipkan daftar di
lokasi saat ini dalam manifes konten. Lanjutkan proses ini hingga semua pod
iklan dan streaming varian telah diproses.
Manifes yang dihasilkan harus sesuai dengan standar HLS. Oleh karena itu, bergantung pada fitur spesifikasi mana yang disertakan dalam manifes konten, Anda mungkin perlu melakukan penerusan akhir pada manifes gabungan untuk memperbaiki nomor urutan media, durasi konten, nomor urut penghentian, dan tag lain yang perlu diupdate untuk mempertimbangkan segmen iklan baru. Setelah perbedaan apa pun dengan standar diperbaiki, kirim setiap manifes varian khusus pengguna ke CDN Anda untuk hosting.
Jika manifes konten dienkripsi, Anda perlu menyimpan kunci enkripsi terakhir
yang ditemukan sebelum awal pod iklan saat ini di tag #EXT-X-KEY
. Kemudian,
Anda perlu menambahkan tag #EXT-X-KEY:METHOD=NONE
untuk menghapus enkripsi sebelum
segmen pertama setiap pod iklan. Terakhir, Anda harus menambahkan salinan tag
#EXT-X-KEY
yang tersimpan sebelum segmen pertama konten setelah setiap pod iklan, untuk
memulihkan enkripsi konten.
Contoh data varian yang dikumpulkan
Encoding profile: "1080p"
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
0 -> https://dai.google.com/{...}pod/0/profile/1080p.m3u8
15 -> https://dai.google.com/{...}pod/1/profile/1080p.m3u8
600 -> https://dai.google.com/{...}pod/2/profile/1080p.m3u8
Contoh manifes konten
Ini adalah konten manifes https://{...}/1080p.m3u8
yang tercantum dalam
data varian yang dikumpulkan.
#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
Contoh manifes pod iklan
Ini adalah konten manifes https://dai.google.com/{...}/pod/1/profile/1080p.m3u8
yang tercantum dalam data varian yang dikumpulkan.
#EXTM3U
{...}
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
Contoh manifes varian yang digabungkan
Ini akan menjadi manifes varian gabungan yang dihasilkan, yang diteruskan ke CDN dan dihosting di https://cdn.{...}/{userid}/1080p.m3u8
.
#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
Membuat playlist multi-varian
Kumpulkan alamat CDN untuk setiap manifes varian yang telah selesai, beserta detail profil encoding yang cocok, dan susun hasilnya ke dalam manifes multivarian baru. Manifes khusus pengguna ini ditampilkan sebagai respons terhadap permintaan manifes yang Anda terima di Langkah 1.
Contoh playlist multi-varian akhir
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://cdn.{...}-subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://cdn.{...}/{userid}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://cdn.{...}/{userid}/360p.m3u8
Streaming DASH MPEG
Jika menggabungkan streaming dalam format MPEG DASH, Anda hanya perlu menghasilkan satu file. Hal ini dapat membuat streaming DASH lebih mudah digabungkan daripada HLS.
File deskripsi presentasi media (MPD) MPEG DASH yang disiapkan dengan baik harus terdiri dari beberapa titik, masing-masing berisi beberapa representasi. Setiap representasi harus cocok dengan salah satu profil encoding Anda. Setiap pod iklan yang ditampilkan dari Ad Manager juga merupakan file MPD yang berisi urutan periode dengan representasi yang cocok.
Untuk menggabungkan file MPD ini, mulailah dengan mencatat waktu mulai untuk setiap pod iklan. Untuk pre-roll, masukkan periode pod iklan pre-roll sebelum periode konten apa pun. Untuk post-roll, masukkan periode pod iklan post-roll setelah semua periode konten. Lakukan iterasi selama periode dalam MPD konten, sehingga melacak waktu putar yang berlalu untuk semua periode konten yang diproses. Saat Anda mencapai batas antara periode yang sesuai dengan waktu mulai pod iklan, masukkan periode dari file MPD pod iklan mid-roll yang cocok pada batas tersebut.
File MPD akhir yang digabungkan harus sepenuhnya sesuai dengan spesifikasi MPEG_DASH, sehingga Anda mungkin perlu melakukan iterasi pada file akhir sekali lagi untuk mengoreksi waktu mulai periode, memperbaiki durasi presentasi media untuk memperhitungkan periode iklan yang baru disisipkan, dan menyelesaikan konflik lain yang mungkin muncul dari proses penggabungan.
Contoh MPD konten
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M00.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Example Stream</Title>
</ProgramInformation>
<Period duration="PT0H0M15.000S" id="content-period-1">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-2">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-3">
...
</Period>
...
</MPD>
Contoh JSON pod iklan
[{
"mpd_uri": "https://{...}pod/1.mpd",
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
}]
Contoh MPD pod iklan
Ini adalah konten mpd_uri
dari JSON pod iklan di atas.
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H0M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Ad Pod 1</Title>
</ProgramInformation>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
...
</Period>
...
</MPD>
Contoh MPD yang digabungkan
Sajikan ini sebagai respons Anda terhadap permintaan manifes streaming awal.
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Example Stream</Title>
</ProgramInformation>
<Period duration="PT0H0M15.000S" id="content-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-2">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-3">
...
</Period>
...
</MPD>
Referensi lainnya
- Pod yang menayangkan pemutaran dengan IMA SDK:
- Pemutaran penayangan pod dengan DAI API