Pod Serving API memberikan akses ke pod iklan video dengan kecepatan bit adaptif yang disiapkan sedemikian rupa sehingga dapat digabungkan langsung menjadi HLS atau Playlist media MPEG-DASH.
Panduan ini berfokus pada penerapan manipulasi manifes Penyajian Pod dasar server untuk streaming VOD.
Menerima permintaan manifes streaming
Manipulator manifes Anda harus menyediakan endpoint API untuk memproses manifes yang diminta dari aplikasi klien pemutar video. Minimal, endpoint ini harus mengumpulkan ID streaming dari aplikasi pemutar klien. ID aliran data ini digunakan untuk identifikasi sesi streaming ke Ad Manager dalam permintaan pod iklan Anda.
Anda juga harus mengumpulkan beberapa informasi lain untuk mengidentifikasi streaming konten, misalnya, Content ID.
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 fiktif yang sesuai dengan video konten di sistem Anda. | ||||
format |
Parameter hipotesis yang sesuai dengan format streaming. Salah satu dari:
|
Mengambil streaming konten
Gunakan ID konten yang dikumpulkan dari permintaan manifes untuk memilih konten streaming untuk digabungkan dengan iklan.
Meminta manifes pod iklan
Untuk meminta iklan dari Ad Manager, server Anda harus membuat permintaan POST ke iklan endpoint pod, meneruskan profil encoding, tag iklan, dan penargetan yang diminta parameter. Permintaan ini juga menyertakan ID aliran data yang Anda kumpulkan di Langkah Akun Layanan 1.
Sebagai hasilnya, Anda akan menerima daftar objek pod iklan yang berisi file manifes untuk pod iklan yang diminta oleh tag iklan penayang dan informasi tentang waktu dan di mana posisi tersebut harus 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
Untuk membuat pemutaran yang selancar mungkin, parameter ini harus cocok dengan 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
akan disisipkan. Titik tanda diukur dalam detik floating point.
Hanya diperlukan untuk respons VMAP yang berisi mid-roll menggunakan offset waktu positional. Hal ini jarang terjadi. |
content_duration_seconds |
Optional |
Durasi konten dalam detik.
Hanya diperlukan untuk respons VMAP yang berisi mid-roll menggunakan selisih waktu persentase. Hal ini jarang terjadi. |
manifest_type |
Optional |
Format streaming iklan yang diminta, hls atau
dash . Nilai defaultnya adalah hls .
|
dai_options |
Optional |
Opsi tambahan yang mengontrol aspek cara manifes dirender. Lihat detail di bawah |
Profil encoding | ||
profile_name |
Required |
ID untuk Profil Encoding ini. Nilai ini dapat berupa string pilih, tetapi Anda tidak dapat memiliki beberapa profil pengkodean dengan nama yang sama pada {i>stream<i} yang sama. |
type |
Required |
Jenis encoding streaming yang dijelaskan oleh profil encoding ini. Isi
jenisnya 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 diisi jika jenis profil encoding adalah iframe. Jika tidak, hanya diizinkan jika jenis medianya berisi video. Lihat lihat detailnya di bawah |
audio_settings |
Optional |
Wajib ada jika profil encoding berisi audio. Hanya diizinkan jika jenisnya lainnya. Lihat detail di bawah |
subtitle_settings |
Optional |
Wajib ada jika profil encoding berisi subtitel. Lihat detail di bawah |
Setelan Video | ||
codec |
Required |
String codec RFC6381.
Contoh: |
bitrate |
Required |
Bilangan bulat yang mewakili kecepatan bit video maksimum profil ini dalam byte per kedua. |
frames_per_second |
Required |
FPS floating point video. |
resolution |
Required |
Nilai berenkode 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
kedua.
Contoh: |
channels |
Required |
Bilangan bulat yang mewakili jumlah saluran audio termasuk frekuensi rendah saluran TV Anda. |
sample_rate |
Required |
Bilangan bulat yang menunjukkan frekuensi sampling audio dalam hertz.
Contoh: |
Setelan subtitel | ||
format |
Required |
Format file yang digunakan oleh subtitel in-band. Nilai yang didukung adalah
webvtt atau ttml .
|
language |
Optional |
Bahasa subtitel sebagai string bahasa RFC5646. Jika disediakan, nilai ini
hanya digunakan untuk rendering DASH.
Contoh: |
opsi DAI | ||
dash_profile |
Optional |
Profil MPEG-DASH untuk diterapkan ke manifes pod iklan. Setelan ini digunakan untuk
Hanya manifes DASH. Nilai yang diizinkan adalah live atau
on-demand . Nilai defaultnya adalah on-demand .
Nilai
Nilai |
ad_pod_timeout |
Optional |
Waktu maksimum yang diperlukan untuk memilih iklan dan membuat pod iklan, dalam mode mengambang
poin detik. Setelah waktu ini berlalu, Ad Manager akan menampilkan
iklan yang sudah dipilih dalam respons ad_pods dan berhenti
diproses.
|
sam_id |
Optional |
Menentukan kunci debug alternatif yang dapat digunakan untuk mencari sesi dalam aktivitas streaming memantau. |
Respons
Parameter respons | |
---|---|
valid_for |
Durasi validnya playlist pod iklan ini dalam dhms
format (hari, jam, menit, detik).
|
valid_until |
Tanggal dan waktu sampai playlist pod iklan ini valid sebagai ISO8601
string penanggalan, dalam yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm
format font.
|
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 tempat pod iklan ini harus dimasukkan, 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. {i>Pengindeksan<i}
diawali 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 streaming konten bervariasi, bergantung pada tentang implementasi Anda, format streaming, dan fitur yang Anda pilih terapkan dari spesifikasi format. Alur kerja berikut adalah saran tentang cara menangani proses ini. Detail presisi dari mungkin berbeda, berdasarkan kebutuhan bisnis dan konten Anda feed.
Streaming HLS
Jika Anda menggabungkan streaming dalam format HLS, streaming konten akan menjadi multivarian playlist ke manifes aliran data terpisah, satu untuk setiap profil encoding. Iklan Anda pod harus dimasukkan ke dalam setiap manifes varian ini. Salah satu cara untuk Anda harus menyiapkan semua manifes varian dan meneruskannya ke Content Jaringan Penayangan (CDN) untuk web. Playlist multi-varian akhir adalah kumpulan link ke playlist yang dihosting CDN manifes.
Melakukan iterasi melalui profil encoding
Untuk setiap profil encoding, kumpulkan semua manifes pod iklan yang terkait dari
respons Ad Manager, beserta waktu mulai terkait. Untuk iklan pre-roll
pod, setel waktu mulai ke 0
. Untuk post-roll, gunakan durasi konten sebagai
waktu mulai pod iklan. Mengidentifikasi aliran varian dalam 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 dalam setiap manifes varian
Untuk setiap aliran varian, masuk ke segmen manifes konten, dengan tetap
total waktu konten yang berlalu. Ketika Anda sampai di posisi awal,
pod iklan, ekstrak daftar segmen dari manifes pod iklan, menggabungkan
daftar segmen dalam dua tag #EXT-X-DISCONTINUITY
, lalu sisipkan daftar di bagian
lokasi saat ini dalam manifes konten. Lanjutkan proses ini hingga semua iklan
pod dan aliran varian telah diproses.
Manifes yang dihasilkan harus sesuai dengan standar HLS. Oleh karena itu, bergantung di mana fitur spesifikasi yang tergabung manifes konten Anda, Anda mungkin perlu melakukan penerusan akhir pada manifes gabungan untuk memperbaiki masalah nomor urut, durasi konten, nomor urut diskontinuitas, dan setiap tag lain yang perlu diperbarui untuk memperhitungkan segmen iklan baru. Setelah perbedaan dengan standar diperbaiki, kirim setiap manifes varian khusus pengguna ke CDN untuk hosting.
Jika manifes konten Anda dienkripsi, Anda perlu menyimpan enkripsi terakhir
yang ditemukan sebelum pod iklan saat ini dimulai dalam tag #EXT-X-KEY
. Lalu:
Anda perlu menambahkan tag #EXT-X-KEY:METHOD=NONE
untuk menghapus enkripsi sebelum
segmen pertama pada setiap pod iklan. Terakhir, Anda harus menambahkan
salinan yang disimpan
#EXT-X-KEY
sebelum segmen konten pertama setelah masing-masing 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 isi dari
Manifes https://dai.google.com/{...}/pod/1/profile/1080p.m3u8
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
yang 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 diselesaikan, bersama dengan mencocokkan detail profil pengkodean, dan menyusun hasilnya ke dalam manifes multi-varian. Manifes khusus pengguna ini ditampilkan sebagai respons ke permintaan manifes yang Anda terima pada Langkah 1.
Contoh playlist multi-varian final
#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 DASH MPEG, Anda hanya perlu menghasilkan dalam satu file. Hal ini dapat membuat aliran DASH lebih mudah digabungkan daripada HLS.
File deskripsi presentasi media (MPD) MPEG DASH yang disiapkan dengan benar harus terdiri dari beberapa periode, masing-masing berisi beberapa representasi. Masing-masing harus cocok dengan salah satu profil encoding Anda. Setiap pod iklan yang ditampilkan dari Ad Manager juga dalam bentuk file MPD yang berisi urutan titik dengan pencocokan.
Untuk merangkai {i>file<i} MPD ini bersama-sama, mulailah dengan mencatat waktu mulai setiap pod iklan. Untuk pre-roll, sisipkan periode pod iklan pre-roll sebelum konten apa pun titik. Untuk post-roll, sisipkan periode pod iklan post-roll setelah semua konten periode. Lakukan iterasi selama periode dalam MPD konten, dengan melacak waktu putar yang berlalu untuk semua periode konten yang diproses. Saat Anda mencapai batas di antara periode yang sesuai dengan waktu mulai pod iklan, masukkan titik dari file MPD pod iklan mid-roll yang cocok pada batas tersebut.
File MPD akhir yang digabungkan harus sepenuhnya sesuai dengan spesifikasi MPEG_DASH, jadi Anda mungkin perlu mengulangi file akhir sekali lagi untuk memperbaiki waktu mulai periode, memperbaiki durasi presentasi media untuk memperhitungkan periode iklan yang baru dimasukkan, dan menyelesaikan konflik lain yang dapat menimbulkan timbul 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
Berfungsi 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:
- Pod yang menayangkan pemutaran dengan DAI API