VOD akışları için istemci video oynatıcı uygulaması

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: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Yol parametreleri

{network_code} Google Ad Manager 360 ağ kodunuz

JSON gövde parametreleri

targeting_parameters İçerik kaynağı kimliği (cmsid), video kimliğini (vid) ve reklam hedefleme parametrelerini içeren bir JSON nesnesi. Zorunlu

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 \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

Ö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:

ad ads nesnesindeki bir anahtarla eşleşen bir reklamın kimliği.
ad_break_id ad_breaks nesnesindeki bir anahtarla eşleşen reklam arasının kimliği.
type Reklam etkinliğinin türü. Reklam etkinliği türleri şunlardır:
start Reklamın başında tetiklenir.
firstquartile İlk çeyreğin sonunda tetiklendi.
midpoint Reklamın orta noktasında tetiklenir.
thirdquartile Üçüncü çeyreğin sonunda tetiklendi.
complete Reklamın sonunda tetiklenir.
progress Uygulamaya, bir reklam arasının oynatıldığını bildirmek için reklam boyunca düzenli aralıklarla tetiklenir.
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_break_id ad_breaks nesnesindeki bir anahtarla eşleşen reklam arasının kimliği.
position Bu reklamın, reklam arasındaki reklam grubu içinde göründüğü konum (saniye cinsinden kayan nokta).
duration Reklamın kayan nokta cinsinden saniye cinsinden uzunluğu.
clickthrough_url Destekleniyorsa, bir kullanıcı bu reklamla etkileşimde bulunduğunda açılması gereken URL.
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:
type Reklam arasının türü. Reklam arası türleri pre (videodan önce gösterilen reklam), mid (videonun ortasında gösterilen reklam) ve post'dir (videodan sonra gösterilen reklam).
duration Kayan nokta saniye cinsinden reklam arası uzunluğu.
ads Bu reklam arasındaki reklamların sayısı.

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:

  1. 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şkili ad ve ad_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şkili ad ve ad_break nesnelerini alın. Bu, progress dışındaki türlere sahip tüm etkinlikleri almalıdır.

  2. 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 ilk progress 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

Ek kaynaklar