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

Google DAI Kapsül Yayınlama API'si, kendi video birleştirme işleminizin kontrolünü elinde tutarken Google Ads tarafından desteklenen sunucu tarafı reklam ekleme işlemi gerçekleştirmenize olanak tanır.

Bu kılavuzda, Kapsül Yayınlama API'si ile nasıl etkileşim kuracağınız ve IMA DAI SDK'sı ile benzer işlevlere nasıl ulaşacağınız 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ılavuzda HLS akışlarına odaklanılır ve HLS ile MPEG-DASH arasındaki temel farklar belirli adımlarda vurgulanır.

Seç-izle yayınları için Kapsül Yayınlama API'sini uygulamanıza entegre etmek üzere aşağıdaki adımları uygulayın:

Ad Manager'a yayın kaydı isteği gönderme

Akış kaydı uç noktasına bir POST isteği gönderin. Sırasıyla, manifest değiştirme 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 Reklam hedefleme parametrelerini içeren bir JSON nesnesi. Zorunlu

Yanıt JSON'u

media_verification_url Oynatma izleme etkinliklerine ping göndermek için kullanılan temel URL. Bu temel URL'ye bir reklam etkinliği kimliği eklenerek tam bir medya doğrulama URL'si oluşturulur.
metadata_url Reklam kapsülü meta verilerini isteyecek URL.
stream_id Mevcut yayın oturumunu tanımlamak için kullanılan dize.
valid_for Mevcut yayın oturumunun süresinin dolmasına kalan süre, dhms (gün, saat, dakika, saniye) biçiminde. Örneğin, 2h0m0.000s, 2 saatlik bir süreyi temsil eder.
valid_until Mevcut yayın oturumunun süresinin dolan zamanı, 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":{"url":"http://example.com"}}' \
     -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, JSON yanıt gövdesi olmadan standart HTTP hata kodları döndürülür.

JSON yanıtını ayrıştırın ve ilgili değerleri saklayın.

Yayın manifestini manifest düzenleyiciden isteme

Her manifest düzenleyicinin farklı istek ve yanıt biçimleri vardır. Belirli gereksinimlerini anlamak için manipülatör sağlayıcınızla iletişime geçin. Kendi manifest düzenleyicinizi uyguluyorsanız bu bileşenle ilgili şartları anlamak için manifest düzenleyici kılavuzunu okuyun.

Genel olarak, oturuma özgü manifestler oluşturması 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ışları oynatma

Manifest değiştirme sunucusundan aldığınız manifest dosyasını bir video oynatıcıya yükleyin ve oynatmayı başlatın.

Ad Manager'dan reklam kapsülü meta verilerini isteme

Birinci adımda aldığınız metadata_url için GET isteği gönderin. Bu adım, manifest düzenleyicinizden birleştirilmiş manifest'i aldıktan sonra gerçekleşmelidir. Bunun karşılığında aşağıdaki parametreleri içeren bir JSON nesnesi alırsınız:

tags Yayında görünen tüm reklam etkinliklerini içeren bir anahtar/değer çifti grubu. Anahtarlar, bir reklam etkinliği kimliğinin akıştaki zamanlanmış meta verilerinde görünen ilk 17 karakteri veya progress türündeki etkinliklerde tam reklam etkinliği kimliğidir.

Her değer, aşağıdaki parametreleri içeren bir nesnedir:

ad ads nesnesinde bir anahtarla eşleşen reklamın kimliği.
ad_break_id ad_breaks nesnesinde 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 tetiklenir.
midpoint Reklamın orta noktasında tetiklenir.
thirdquartile Üçüncü çeyreğin sonunda tetiklenir.
complete Reklamın sonunda tetiklenir.
progress Uygulamaya reklam arası 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 grubu. 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 nesnesinde bir anahtarla eşleşen reklam arasının kimliği.
position Bu reklamın, reklam arasındaki reklam grubunda göründüğü konum (kayan noktalı saniye cinsinden).
duration Reklamın kayan noktalı saniye cinsinden uzunluğu.
clickthrough_url Kullanıcı bu reklamla etkileşime geçtiğinde açılması gereken URL (destekleniyorsa).
ad_breaks Akışta görünen tüm reklam aralarını açıklayan bir anahtar/değer çifti grubu. 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), mid (videonun ortasında) ve post (videodan sonra) şeklindedir.
duration Reklam arasının kayan noktalı saniye cinsinden uzunluğu.
ads Bu reklam arasındaki reklam sayısı.

Video akışınızdaki zamanlanmış meta veri etkinlikleriyle ilişkilendirmek için bu değerleri saklayı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 dinleme

Video oynatıcınızın ses/video akışındaki tetiklenen reklam etkinlikleri aracılığıyla zamanlanmış meta verileri dinleyin.

MPEG-TS akışlarında meta veriler bant içi ID3 v2.3 etiketleri olarak görünür. Her meta veri etiketinin kimliği TXXX'tür ve değer, google_ dizesiyle başlar ve ardından bir dizi karakter gelir. Bu değer, reklam etkinliği kimliğidir.

TXXX içindeki XXX yer tutucusu değildir. TXXX dizesi, "kullanıcı tanımlı metin" için ayrılmış ID3 etiketi kimliğidir.

Örnek ID3 etiketi

TXXXgoogle_1234567890123456789

MP4 akışlarında bunlar, ID3 v2.3 etiketlerini taklit eden bant içi emsg etkinlikleri olarak gönderilir. Alakalı her emsg kutusunda https://aomedia.org/emsg/ID3 veya https://developer.apple.com/streaming/emsg-id3 değerine sahip bir scheme_id_uri ve ID3TXXXgoogle_ ile başlayan bir message_data değeri bulunur. ID3TXXX ön ekiyle birlikte olmayan bu message_data değeri, reklam etkinliği kimliğidir.

Örnek e-posta mesajı 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 taklit 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ımdaki tags nesnesinde bir anahtarla eşleştirilebilir. Bu değerlerin eşleştirilmesi iki aşamalı bir işlemdir:

  1. Tam reklam etkinliği kimliğiyle eşleşen bir anahtar için tags nesnesini kontrol edin. Eşleşme bulunursa etkinlik türünü ve ilişkili ad ve ad_break nesnelerini alın. Bu etkinliklerin türü progress olmalıdır.

    Reklam etkinliği kimliğinin tamamı için eşleşme bulunamazsa reklam etkinliği kimliğinin ilk 17 karakteriyle eşleşen bir anahtar için tags nesnesi kontrol edilir. Etkinlik türünü ve ilişkili ad ve ad_break nesnelerini alın. Bu işlem, progress dışındaki türlere sahip tüm etkinlikleri getirir.

  2. Oynatıcınızın kullanıcı arayüzünü güncellemek için alınan bu bilgileri kullanın. Örneğin, bir start veya ilk progress etkinliğini aldığınızda oynatıcının arama kontrollerini gizleyin ve mevcut reklamın reklam arasındaki konumunu açıklayan bir yer paylaşımı gösterin (ör. "3 reklamdan 1. reklam").

Ö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önderme

progress dışında bir türde 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ındaki media_verification_url değerine ekleyin.

Tam URL ile bir GET isteği gönderin. Doğrulama isteği başarılı olursa 202 durum kodu içeren bir HTTP yanıtı alırsınız. 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