Canlı yayınlar 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: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/json

Yol parametreleri

Form kodlu gövde parametreleri

İsteğe bağlı bir form kodlamalı hedefleme parametreleri grubu.

Yanıt JSON

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

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, 202 durum kodunu 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

• API referans belgeleri
• IMA SDK belgeleri
• DAI katmanı uygulama türlerinin karşılaştırması