Google DAI Kapsül Yayınlama API'si, kendi video birleştirme işlemlerinizi kontrol ederken Google Ads tarafından desteklenen sunucu tarafı reklam ekleme işlemi yapmanıza olanak tanır.
Bu kılavuzda, Kapsül Yayınlama API'si ile nasıl etkileşim kuracağınız ve IMA DAI SDK ile benzer işlevleri nasıl elde edeceğiniz gösterilmektedir. Desteklenen işlevlerle ilgili sorularınız için Google hesap yöneticinizle iletişime geçin.
Kapsül Yayınlama API'si, HLS veya MPEG-DASH akış protokollerinde kapsül yayınlama akışlarını destekler. Bu kılavuz, HLS akışlarına odaklanır ve HLS ile MPEG-DASH arasındaki temel farkları belirli adımlarda vurgular.
VOD akışları için Kapsül Yayınlama API'sini uygulamanıza entegre etmek üzere aşağıdaki adımları tamamlayın:
Ad Manager'a akış kaydı isteğinde bulunma
Akış kaydı uç noktasına POST isteği gönderin. Bunun ardından, manifest düzenleme sunucunuza ve ilişkili Kapsül Yayınlama API uç noktalarına gönderilecek akış kimliğini içeren bir JSON yanıtı alırsınız.
API uç noktası
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
Yol parametreleri
{network_code} |
Google Ad Manager 360 ağ kodunuz |
{custom_asset} |
Google AdManager'da bu etkinlikle ilişkili özel tanımlayıcı. |
Form kodlu gövde parametreleri
İsteğe bağlı bir form kodlamalı hedefleme parametreleri grubu.
Yanıt JSON
media_verification_url |
Oynatma izleme etkinliklerini pinglemek için temel URL. Bu temel URL'ye reklam etkinliği kimliği eklenerek eksiksiz bir medya doğrulama URL'si oluşturulur. |
metadata_url |
Reklam kapsülü meta verileri istenecek URL. |
stream_id |
Mevcut akış oturumunu tanımlamak için kullanılan dize. |
valid_for |
dhms (gün, saat, dakika, saniye) biçiminde, geçerli akış oturumunun dolmasına kalan süre. Örneğin, 2h0m0.000s , 2 saatlik bir süreyi temsil eder.
|
valid_until |
Geçerli akış oturumunun sona erdiği saat (yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm biçiminde ISO 8601 tarih ve saat dizesi olarak).
|
Örnek istek (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded"
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\""
https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
Örnek yanıt
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
Hata olması durumunda standart HTTP hata kodları JSON yanıt gövdesi olmadan döndürülür.
JSON yanıtını ayrıştırın ve ilgili değerleri depolayın.
Manifest düzenleyiciden akış manifestini isteme
Her manifest düzenleyicinin farklı bir istek ve yanıt biçimleri vardır. Özel gereksinimlerini anlamak için manipülatör sağlayıcınızla iletişime geçin. Kendi manifest düzenleyicinizi uyguluyorsanız bu bileşenin gereksinimlerini anlamak için manifest düzenleme aracı kılavuzunu okuyun.
Genel olarak, oturuma özgü manifestler derlemesi için yukarıdaki kayıt uç noktası tarafından döndürülen akış kimliğini manifest düzenleyicinize iletmeniz gerekir. Manifest düzenleyiciniz tarafından açıkça belirtilmediği sürece manifest isteğinize verilen yanıt, hem içerik hem de reklam içeren bir video akışıdır.
Örnek istek (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
Örnek yanıt (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
Akışı oynatın
Manifest işleme sunucusundan aldığınız manifesti bir video oynatıcıya yükleyin ve oynatmayı başlatın.
Ad Manager'dan reklam kapsülü meta verileri isteme
Birinci adımda aldığınız metadata_url
için GET
isteğinde bulunun. Bu adım, manifest düzenleyicinizden birleştirilmiş manifesti aldıktan sonra gerçekleşmelidir. Bunun karşılığında, aşağıdaki parametreleri içeren bir JSON nesnesi alırsınız:
tags |
Akışta görünen tüm reklam etkinliklerini içeren bir anahtar/değer çifti kümesi. Anahtarlar, akışın zamanlı meta verilerinde görünen bir reklam etkinliği kimliğinin ilk 17 karakteridir veya progress türündeki etkinlikler söz konusu olduğunda tam reklam etkinliği kimliğidir.
Her değer, aşağıdaki parametreleri içeren bir nesnedir:
|
||||||||||||||||||
ads |
Akışta görünen tüm reklamları açıklayan bir anahtar/değer çifti kümesi. Anahtarlar, yukarıda listelenen tags nesnesinde bulunan değerlerle eşleşen reklam kimlikleridir. Her değer, aşağıdaki parametreleri içeren bir nesnedir:
|
||||||||||||||||||
ad_breaks |
Akışta görünen tüm reklam aralarını açıklayan bir anahtar/değer çifti kümesi.
Anahtarlar, yukarıda listelenen tags ve ads nesnelerinde bulunan değerlerle eşleşen reklam arası kimlikleridir. Her değer, aşağıdaki parametreleri içeren bir nesnedir:
|
Bu değerleri, video akışınızdaki zamanlanmış meta veri etkinlikleriyle ilişkilendirmek için depolayın.
Örnek istek (cURL)
curl https://dai.google.com/.../metadata
Örnek yanıt
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
Reklam etkinliklerini dinleyin
Video oynatıcınızın ses/video akışındaki tetiklenen reklam etkinlikleri aracılığıyla zamanlanmış meta verileri dinleyin.
MPEG-TS akışları için meta veriler bant içi ID3 v2.3 etiketleri olarak görünür. Her bir meta veri etiketinde TXXX
kimliği bulunur. Değer, google_
dizesiyle başlar ve ardından bir dizi karakter gelir. Bu değer, reklam etkinliği kimliğidir.
TXXX
öğesindeki XXX
bir yer tutucu değil. TXXX
dizesi, "kullanıcı tanımlı metin" için ayrılmış ID3 etiket kimliğidir.
Örnek ID3 etiketi
TXXXgoogle_1234567890123456789
Bunlar MP4 yayınlarında ID3 v2.3 etiketlerini emüle eden bant içi mesaj etkinlikleri olarak gönderilir. İlgili her bir e-posta kutusunda, https://aomedia.org/emsg/ID3
veya https://developer.apple.com/streaming/emsg-id3
scheme_id_uri
değeri ve ID3TXXXgoogle_
ile başlayan message_data
değeri bulunur. Bu message_data
değeri, ID3TXXX
öneki olmadan reklam etkinliği kimliğidir.
Örnek e-posta kutusu
Veri yapısı, medya oynatıcı kitaplığınıza bağlı olarak değişiklik gösterebilir.
Reklam etkinliği kimliği google_1234567890123456789
ise yanıt şu şekilde görünür:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
Bazı medya oynatıcı kitaplıkları, ID3 etiketlerini yerel ID3 etiketleri olarak emüle eden emsg etkinliklerini otomatik olarak sunar. Bu durumda, MP4 akışları MPEG_TS ile aynı ID3 etiketlerini sunar.
İstemci video oynatıcı uygulamasının kullanıcı arayüzünü güncelleme
Her reklam etkinliği kimliği, 4. adımda yer alan tags
nesnesindeki bir anahtarla eşleştirilebilir.
Bu değerleri eşleştirmek iki adımlı bir işlemdir:
tags
nesnesinde tam reklam etkinliği kimliğiyle eşleşen bir anahtar olup olmadığını kontrol edin. Eşleşme bulunursa etkinlik türünü ve bununla ilişkiliad
vead_break
nesnelerini alın. Bu etkinliklerin türüprogress
olmalıdır.Tam reklam etkinliği kimliği için bir eşleşme bulunmazsa
tags
nesnesinde reklam etkinliği kimliğinin ilk 17 karakteriyle eşleşen bir anahtar olup olmadığını kontrol edin. Etkinlik türünü ve ilişkiliad
vead_break
nesnelerini alın. Bu,progress
dışındaki türlere sahip tüm etkinlikleri almalıdır.Alınan bu bilgileri, oynatıcınızın kullanıcı arayüzünü güncellemek için kullanın. Örneğin, bir
start
veya ilkprogress
etkinliği aldığınızda oynatıcınızın arama kontrollerini gizleyin ve geçerli reklamın reklam arasındaki konumunu açıklayan bir yer paylaşımı görüntüleyin (ör. "Reklam 1/3").
Örnek reklam etkinliği kimlikleri
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
Örnek etiketler nesnesi
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
Medya doğrulama ping'leri gönder
progress
dışında türde bir reklam etkinliği her alındığında Ad Manager'a bir medya doğrulama ping'i gönderilmelidir.
Bir reklam etkinliğinin tam medya doğrulama URL'sini oluşturmak için tam reklam etkinliği kimliğini akış kaydı yanıtından media_verification_url
değerine ekleyin.
Tam URL ile bir GET isteği oluşturun. Doğrulama isteği başarılı olursa durum koduyla birlikte bir HTTP yanıtı alırsınız: 202
.
Aksi takdirde 404
HTTP hata kodunu alırsınız.
Örnek istek (cURL)
curl https://{...}/media/google_5555555555123456789
Örnek başarılı yanıt
HTTP/1.1 202 Accepted