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

Google DAI Kapsül Yayınlama API'si, kontrol edebilirsiniz.

Bu kılavuzda, Kapsül Yayınlama API'si ile nasıl etkileşimde bulunacağınız ve IMA DAI SDK'sı ile benzer işlevlere sahiptir. Yeşil Ofis web sitesinde Google hesap yöneticinizle iletişime geçin.

Kapsül Yayınlama API'si, HLS veya MPEG-DASH'de kapsül sunma akışlarını destekler akış protokolleri. Bu kılavuzda, HLS akışlarına odaklanılmakta ve HLS ve MPEG-DASH arasındaki farklar.

Kapsül Yayınlama API'sini VOD akışlarına yönelik uygulamanıza entegre etmek için şu adımları uygulayın:

Ad Manager'a akış kaydı isteğinde bulunma

Akış kaydı uç noktasına bir POST isteği gönderin. Bunun karşılığında size Manifest işlemenize gönderilecek akış kimliğini içeren JSON yanıtı sunucusu ve ilişkili Kapsül Yayınlama API'si uç noktaları.

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ğini (cmsid), video kimliğini (vid) ve reklam hedefleme parametreleri ile ilgili daha fazla bilgi edinin. Zorunlu

Yanıt JSON

media_verification_url Oynatma izleme etkinliklerini pingleyen temel URL. Eksiksiz bir medya doğrulaması URL, bu temel URL'ye bir reklam etkinliği kimliği eklenerek oluşturulur.
metadata_url Reklam kapsülü meta verilerini istenecek URL.
stream_id Geçerli akış oturumunu tanımlamak için kullanılan dize.
valid_for Mevcut akış oturumunun süresinin dolmasına kalan süre (önceki değerde) dhms (gün, saat, dakika, saniye) biçimindedir. Örneğin, 2h0m0.000s, 2 saatlik bir süreyi temsil eder.
valid_until ISO 8601 uyarınca geçerli akış oturumunun sona erdiği zaman yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm konumundaki tarih ve saat dizesi biçimindedir.

Ö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ı olmadan döndürülür gövde.

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çimi vardır. İletişim manipülatör sağlayıcınızla paylaşın. Eğer manifesto oluşturucunuzu uygulamak için manifest düzenleyiciyi okuyun rehberimizi bu bileşene ait gereksinimleri karşılayın.

Genel olarak, oluşturmak için manifest manipülatörünüze yönlendiren bir kayıt uç noktası oluşturun. oturuma özgü manifest'ler oluşturun. Manifest'inizde açıkça belirtilmediği sürece manifesto isteğinize yanıt olarak aşağıdakileri içeren bir video akışı bulunur: hem içerik hem de reklamlar.

Ö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

Manifest manipülasyon sunucusundan aldığınız manifest dosyasını video oynatıcıya gidip oynatmayı başlatın.

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

Birinci adımda aldığınız metadata_url için bir GET isteğinde bulunun. Bu adımı, manifest dosyanızdan birleştirilmiş manifesti aldıktan sonra gerçekleştirilmelidir manipülasyon aracı olabilir. Karşılığında, aşağıdakileri içeren bir JSON nesnesi alırsınız: parametre:

tags Gösterilen tüm reklam etkinliklerini içeren anahtar/değer çiftleri kümesi akış şeklinde gösterilir. Anahtarlar bir reklam etkinliğinin ilk 17 karakteridir Akışın zamanlı meta verilerinde veya etkinlikler söz konusu olduğunda görünen kimlik progress türünde tam reklam etkinliği kimliği.

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 içindeki bir anahtarla eşleşen reklam arası kimliği nesnesini tanımlayın.
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 bir reklamın bildirildiğini bildirmek için reklam boyunca düzenli olarak tetiklenir mola çalıyor.
ads Akışta görünen tüm reklamları açıklayan bir anahtar/değer çiftleri kümesi. İlgili içeriği oluşturmak için kullanılan anahtarları, tags nesnesinde bulunan değerlerle eşleşen reklam kimlikleridir listelenenler gibi. Her değer, aşağıdaki parametreleri içeren bir nesnedir:
ad_break_id ad_breaks içindeki bir anahtarla eşleşen reklam arası kimliği nesnesini tanımlayın.
position Bu reklamın, reklamdaki reklam grubu içinde göründüğü konum değeri gösterilir.
duration Reklamın, kayan nokta (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 çiftleri grubu. Anahtarlar, tags içinde bulunan değerlerle eşleşen reklam arası kimlikleridir ve yukarıda ads nesne listelenir. Her değer bir nesnedir şunları içerir:
type Reklam arası türü. Reklam arası türleri şunlardır: pre (videodan önce gösterilen reklam), mid (videonun ortasında gösterilen reklam) ve post (videodan sonra gösterilen reklam).
duration Reklam arasının kayan nokta (saniye) cinsinden uzunluğu.
ads Bu reklam arasındaki reklamların sayısı.

Videonuzdaki zamanlanmış meta veri etkinlikleriyle ilişkilendirmek için bu değerleri depolayın. akış şeklinde gösterilir.

Ö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

Ses/video akışında tetiklenen reklam etkinlikleri aracılığıyla süreli meta verileri dinleme video oynatıcınızın resmidir.

MPEG-TS akışlarında meta veriler bant içi ID3 v2.3 etiketleri olarak görünür. Her biri meta veri etiketi TXXX kimliğine sahiptir 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 bir yer tutucu değil. TXXX dizesi, ID3 etiket kimliğidir "kullanıcı tanımlı metin" için ayrıldı.

Örnek ID3 etiketi

TXXXgoogle_1234567890123456789

MP4 akışlarında bunlar ID3 v2.3'ü emüle eden bant içi e-posta etkinlikleri olarak gönderilir. etiketleri arasında yer alır. Alakalı her e-posta kutusunda scheme_id_uri değeri vardır: https://aomedia.org/emsg/ID3 veya https://developer.apple.com/streaming/emsg-id3 ve bir message_data değeri ID3TXXXgoogle_ ile başlıyor. Bu message_data değeri, ID3TXXX öneki, 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 şöyle görünür: bu:

{
  "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'e öykünen e-posta etkinliklerini otomatik olarak sunar etiketleri yerel ID3 etiketleri olarak kabul eder. Bu durumda, MP4 akışları aynı ID3 etiketlerini sunar olarak desteklenmektedir.

İstemci video oynatıcı uygulamasının kullanıcı arayüzünü güncelleme

Her reklam etkinliği kimliği, 4. adımdaki tags nesnesindeki bir anahtarla eşleştirilebilir. Bu değerleri eşleştirmek iki adımlı bir işlemdir:

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

    Tam reklam etkinliği kimliği için eşleşme bulunamazsa tags özelliğini kontrol edin. reklam etkinliği kimliğinin ilk 17 karakteriyle eşleşen bir anahtarın nesnesidir. Etkinlik türünü ve ilişkili ad ile ad_break nesnelerini alın. Bu, progress dışındaki türlere sahip tüm etkinlikleri almalıdır.

  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ği aldığınızda oyuncunuzun konumunu gizleyin ve geçerli reklamın reklam arası, örneğin: "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

Her reklam etkinliğinde Ad Manager'a bir medya doğrulama ping'i gönderilmelidir progress dışında bir türe sahip URL'ler alındığında.

Bir reklam etkinliğinin tam medya doğrulama URL'sini oluşturmak için reklam etkinliği kimliğinin, akış kaydındaki media_verification_url değerine tıklayın.

Tam URL ile bir GET isteğinde bulunun. Doğrulama isteği başarılı olursa 202 durum kodunu içeren bir HTTP yanıtı alırsınız. Aksi takdirde HTTP hata kodunu 404 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