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

JSON gövde parametreleri

Yanıt JSON'u

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

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

• IMA SDK dokümanları
• DAI oynatıcı uygulama türlerini karşılaştırma