DAI canlı yayınlarını yönetme

Google DAI API, IMA SDK'nın uygulanmasının desteklenmediği ortamlarda Google DAI özellikli yayınları uygulamanıza olanak tanır. IMA SDK'nın desteklendiği platformlarda IMA'yı kullanmaya devam etmenizi öneririz.

DAI API'yi aşağıdaki platformlarda kullanmanızı öneririz:

  • Samsung Smart TV (Tizen)
  • LG TV
  • HbbTV
  • Xbox (JavaScript uygulamaları)
  • KaiOS

API, IMA DAI SDK'nın sağladığı temel özellikleri destekler. Uyumluluk veya desteklenen özelliklerle ilgili sorularınız için Google hesap yöneticinizle iletişime geçin.

CANLI yayınlar için DAI API'yi uygulama

DAI API, hem HLS hem de DASH protokollerini kullanan doğrusal (CANLI) akışları destekler. Bu kılavuzda açıklanan adımlar her iki protokol için de geçerlidir.

API'yi CANLI yayınlar için uygulamanıza entegre etmek üzere aşağıdaki adımları tamamlayın:

1. Yayın isteğinde bulunma

DAI API'den canlı yayın isteğinde bulunmak için akış uç noktasına bir POST çağrısı yapın. JSON yanıtı, akış manifestinin yanı sıra ilişkili DAI API uç noktalarını ve değerlerini içerir.

Örnek istek gövdesi

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Örnek yanıt gövdesi

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Hata yanıtı

Hata 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 aşağıdaki değerleri saklayın:

stream_id
Bu değer, döndürülen akışı tanımlamak için kullanılabilir.
stream_manifest
Bu URL, yayın oynatma için medya oynatıcınıza iletilir.
media_verification_url
Bu URL, oynatma etkinliklerini izlemek için kullanılan temel uç noktadır.
metadata_url
Bu URL, yaklaşan yayın etkinlikleriyle ilgili düzenli olarak bilgi almak için kullanılır.
session_update_url
Bu URL, ilk akış isteği sırasında gönderilen akış isteği parametrelerini güncellemek için kullanılır. Bu isteğin parametrelerinin, önceki akış için ayarlanan tüm parametrelerin yerini aldığını unutmayın.
polling_frequency
DAI API'den güncellenmiş AdBreak meta verileri istenirken kullanılan sıklık (saniye cinsinden).

2. Yeni reklam arası meta verileri için yoklama

Meta veri URL'sini kullanarak anket sıklığında yeni reklam arası meta verileri için anket yapacak bir zamanlayıcı ayarlayın. Akış yanıtında belirtilmemişse varsayılan önerilen aralık 10 saniyedir.

Bant genişliğini optimize etmek için aşağıdakileri yapın:

  1. metadata_url uç noktasına ilk GET isteği gönderin.
    • delta_token sorgu parametresini atlayın. Bu işlem, sunucunun akışın dijital video kaydedici (DVR) penceresi için tam meta verileri döndürmesine olanak tanır. DVR aralığı, izleyicinin geri sarıp oynatabileceği yayın zaman aralığını içerir. Yanıt, next_delta_token nesne alanını içerir.
  2. Meta verileri istemci tarafında saklayın.
  3. En son yanıtın döndürdüğü next_delta_token değerini kullanarak sonraki aramaları yapın. Her yanıtta bir next_delta_token değeri bulunur. Her zaman aldığınız en son değeri gönderin.
  4. Değişiklikleri birleştirmek ve eski reklam aralarını kaldırmak için depolanan meta verileri güncelleyin.

Delta jetonunu ayrıştırmaya, oluşturmaya veya değiştirmeye çalışmayın. Jetonun biçimi değişebilir. Jetonu alındığı şekilde saklayın ve sonraki istekte jetonu değiştirmeden geri iletin.

Örnek ilk istek

İlk istek sorgu parametresi almaz ve tam meta verileri döndürür:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Örnek sonraki istek

Sonraki her istek, önceki yanıttaki next_delta_token değerini delta_token parametresi olarak iletir. Yanıtta aşağıdakiler yer alıyor:

  • Reklamlar
  • Reklam araları
  • Sunucu jetonu yayınlandıktan sonra sunucunun eklediği veya güncellediği etiketler.
  • Depolanmış meta verilerinizden kaldırılacak obsolete_ad_break_ids reklam arası listesi

Sunucu, değişmeyen reklam aralarını atlar. Aşağıdaki örnekte, yalnızca bu son değişiklikleri getirmek için delta jetonunun kullanıldığı sonraki bir yoklama gösterilmektedir:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

İşlem başarılı olursa aşağıdakine benzer bir çıkış görürsünüz:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. ID3 etkinliklerini dinleme ve oynatma etkinliklerini izleme

Bir video akışında belirli etkinliklerin gerçekleştiğini doğrulamak için ID3 etkinliklerini işlemek üzere aşağıdaki adımları uygulayın:

  1. Medya etkinliklerini bir kuyrukta depolayın. Her medya kimliğini, zaman damgasıyla birlikte (oynatıcı tarafından gösteriliyorsa) kaydedin.
  2. Oynatıcıdan gelen her zaman güncellemesinde veya belirli bir sıklıkta (500 ms önerilir), etkinlik zaman damgalarını video yer imleciyle karşılaştırarak medya etkinlikleri sırasında son oynatılan etkinlikleri kontrol edin.
  3. Oynatıldığını onayladığınız medya etkinlikleri için, depolanan reklam arası etiketlerinde medya kimliğini arayarak türü kontrol edin. Depolanan etiketlerin yalnızca medya kimliğinin bir ön ekini içerdiğini, bu nedenle tam eşleşmenin mümkün olmadığını unutmayın.
  4. Video oynatıcı uygulamanız meta veri URL'sini düzenli olarak yokladığı için video oynatıcınız akışta bir ID3 etiketiyle karşılaştığında ve ilişkili meta veriler kullanıma sunulduğunda bir gecikme yaşanabilir. Saklanan etiketlerde bir ID3 etiketi bulunamazsa etiketi bir kuyrukta tutun ve sonraki meta veri yoklamasından sonra etiketi yeniden işleyin. İşleme tamamlanana kadar etkinliği sıraya alın.
  5. Etiketi meta verilerde bulduktan sonra etiketin type alanını aşağıdaki bölümde listelenen reklam etkinliği türleriyle karşılaştırın. Video oynatıcının reklam arası oynatıp oynatmadığını takip etmek için type alanındaki progress değerine sahip etkinlikleri kullanın. Bu etkinlikleri medya doğrulama uç noktasına göndermeyin. Diğer tüm etkinlik türleri için medya kimliğini medya doğrulama uç noktasına ekleyin ve oynatmayı izlemek için GET isteğinde bulunun.
  6. Medya etkinliğini sıradan kaldırın.

Reklam etkinliği türleri

Meta veri tags nesnesindeki her etiket aşağıdaki etkinlik türlerinden birine sahiptir:

Etkinlik türü Açıklama
start Reklamın başında yayınlanır.
firstquartile Reklamın ilk çeyreğinin sonunda yayınlanır.
midpoint Reklamın ortasında yayınlanır.
thirdquartile Reklamın üçüncü çeyreğinin sonunda yayınlanır.
complete Reklamın sonunda yayınlanır.
progress Reklam arası oynatıldığını belirtmek için reklam arası sırasında düzenli olarak çalışır. Bu etkinlikleri medya doğrulama uç noktasına göndermeyin.

Örnek istek

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Örnek yanıtlar

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

İzleme etkinliklerini Akış Etkinliği İzleyicisi'nde doğrulayabilirsiniz.

4. Canlı yayın oturumu parametrelerini güncelleme

Bir yayın oluşturulduktan sonra oturum parametrelerinizi ayarlamak isteyebilirsiniz. Bunun için oturum güncelleme URL'sine istek gönderin.

Örnek istek gövdesi

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Örnek yanıt gövdesi

Successful response would be to look for - HTTP/1.1 200

Sınırlamalar

API, web görünümlerinde kullanılıyorsa hedefleme açısından aşağıdaki sınırlamalar geçerlidir:

  • UserAgent: Kullanıcı aracısı parametresi, temel alınan platform yerine tarayıcıya özel değer olarak iletilir.
  • rdid, idtype, is_lat: Cihaz kimliği düzgün şekilde iletilmediği için aşağıdaki özelliklerin kullanımı sınırlandırılıyor:
    • Sıklık sınırı
    • Sıralı reklam rotasyonu
    • Kitle segmentasyonu ve hedefleme

En iyi uygulamalar

Canlı yayın indekslerinin meta veri uç noktasının, ilgili ID3 etiketinin önekine dayandığını unutmayın. Bu, tüm doğrulama düğümlerine hemen ping göndermek için meta veri uç noktasının kullanılmasını önlemek amacıyla tasarlanmıştır.

Ek kaynaklar