DAI için IMA SDK'sını ayarlama

Platform seçin: HTML5 Android iOS tvOS Cast Roku

IMA SDK'ları, multimedya reklamları web sitelerinize ve uygulamalarınıza entegre etmeyi kolaylaştırır. IMA SDK'ları, herhangi bir VAST uyumlu reklam sunucusundan reklam isteğinde bulunabilir ve uygulamalarınızda reklam oynatmayı yönetebilir. IMA DAI SDK'ları ile uygulamalar, reklam ve içerik videosu (VOD veya canlı içerik) için bir akış isteğinde bulunur. SDK daha sonra birleşik bir video akışı döndürür. Böylece uygulamanızda reklam ve içerik videosu arasında geçiş yapmayı yönetmeniz gerekmez.

İlgilendiğiniz DAI çözümünü seçin

Tam hizmet Pod yayını

Tam kapsamlı DAI

Bu kılavuzda, IMA DAI SDK'nın basit bir video oynatıcı uygulamasına nasıl entegre edileceği gösterilmektedir. Tamamlanmış bir örnek entegrasyonu görüntülemek veya takip etmek isterseniz GitHub'dan temel örneği indirin.

Not: Roku için IMA DAI SDK'sı, uygulama açısından herhangi bir fark olmaksızın hem HLS hem de DASH yayınlarını destekler.

IMA DAI'yi kullanmak için Ad Manager 360 Advanced hesabınız olmalıdır. Ad Manager hesabınız varsa daha fazla bilgi için hesap yöneticinizle iletişime geçin. Ad Manager'a kaydolma hakkında bilgi edinmek için Ad Manager Yardım Merkezi'ni ziyaret edin.

Not: Diğer platformlarla entegrasyon veya IMA istemci taraflı SDK'larını kullanma hakkında bilgi edinmek için Interactive Media Ads SDK'ları başlıklı makaleyi inceleyin.

IMA DAI'ye genel bakış

IMA DAI'nin uygulanması, bu kılavuzda gösterildiği gibi iki ana SDK bileşenini içerir:

• StreamRequest: Bir akış isteğini tanımlayan nesne. Akış istekleri, seç-izle videolar veya canlı yayınlar için olabilir. Canlı yayın isteklerinde öğe anahtarı belirtilirken VOD isteklerinde CMS kimliği ve video kimliği belirtilir. Her iki istek türü de isteğe bağlı olarak, belirtilen akışlara erişmek için gereken bir API anahtarı ve IMA SDK'nın reklam tanımlayıcılarını Google Ad Manager ayarlarında belirtildiği şekilde işlemesi için bir Google Ad Manager ağ kodu içerebilir.
• StreamManager: Dinamik reklam ekleme akışlarını ve DAI arka ucuyla etkileşimleri işleyen bir nesne. Yayın yöneticisi, izleme ping'lerini de işler ve yayın ile reklam etkinliklerini yayıncıya yönlendirir.

Ön koşullar

• Kullanım alanınızın desteklendiğinden emin olmak için uyumluluk sayfamızı inceleyin.
• Roku örnek oynatıcı kodumuzu indirin.
• Geliştirme kurulumunuzun çalıştığını doğrulamak için örnek oynatıcı kodunu bir Roku cihazına dağıtın.

Videonuzu oynatma

Sağlanan örnek video oynatıcı, kutudan çıkarıldığı gibi içerik videosu oynatır. Geliştirme ortamınızın düzgün şekilde kurulduğundan emin olmak için örnek oynatıcıyı Roku oynatıcınıza dağıtın.

Video oynatıcınızı IMA DAI akış oynatıcısına dönüştürme

Bir akış oynatıcı uygulamak için aşağıdaki adımları uygulayın.

Sdk.xml dosyasını oluşturma

Projenize MainScene.xml ile birlikte Sdk.xml adlı yeni bir dosya ekleyin ve aşağıdaki standart metni ekleyin:

Sdk.xml

<?xml version = "1.0" encoding = "utf-8" ?>

<component name = "imasdk" extends = "Task">
<interface>
</interface>
<script type = "text/brightscript">
<![CDATA[
  ' Your code goes here.
]]>
</script>
</component>

Bu kılavuzda her iki dosyayı da düzenlemeniz gerekir.

Roku Advertising Framework'ü yükleme

IMA DAI SDK, Roku Advertising Framework'e bağlıdır. Çerçeveyi yüklemek için manifest ve Sdk.xml dosyalarına aşağıdakileri ekleyin:

bs_libs_required=roku_ads_lib,googleima3
manifest

Library "Roku_Ads.brs"
Library "IMA3.brs"
Sdk.xml

IMA DAI SDK'sını yükleme

IMA DAI SDK'yı yüklemek için aşağıdakileri yapın:

1. IMA SDK'yı New_IMASDK() çağrısıyla başlatın:

   sub loadSdk()
     If m.sdk = invalid
       m.sdk = New_IMASDK()
     End If
     m.top.sdkLoaded = true
   End Sub
   Sdk.xml
   

2. sdkLoaded boole alanı oluşturarak IMA'nın yüklenip yüklenmediğini izleyin:

   <field id="sdkLoaded" type="Boolean" />
   Sdk.xml
   

3. Ana runThread() alt yordamından loadSdk() alt yordamını çağırın:

   if not m.top.sdkLoaded
     loadSdk()
   End If
   Sdk.xml
   

4. sdkTask nesnesini oluşturmak ve çalıştırmak için MainScene.xml içinde loadImaSdk() işlevini oluşturun:

   function loadImaSdk() as void
     m.sdkTask = createObject("roSGNode", "imasdk")
     m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
     m.sdkTask.observeField("errors", "onSdkLoadedError")
   
     ' Change to m.testLiveStream to demo live instead of VOD.
     selectedStream = m.testVodStream
     m.videoTitle = selectedStream.title
     m.sdkTask.streamData = selectedStream
   
     m.sdkTask.observeField("urlData", "urlLoadRequested")
     m.sdkTask.video = m.video
     ' Setting control to run starts the task thread.
     m.sdkTask.control = "RUN"
   end function
   MainScene.xml
   

5. init() işlevinden loadImaSdk() işlevini çağırın.

6. SDK yükleme etkinliklerine yanıt vermek için onSdkLoaded() ve onSdkLoadedError() işleyici alt rutinlerini oluşturun:

   Sub onSdkLoaded(message as Object)
     print "----- onSdkLoaded --- control ";message
   End Sub
   
   Sub onSdkLoadedError(message as Object)
     print "----- errors in the sdk loading process --- ";message
   End Sub
   MainScene.xml
   

IMA akış oynatıcı oluşturma

IMA akış oynatıcı oluşturmak için aşağıdakileri yapın:

1. Aşağıdakileri yapan bir setupVideoPlayer() alt yordam oluşturun:

   1. Akış oynatıcıyı oluşturmak için createPlayer() yöntemini kullanın.

   2. Yayın oynatıcının üç geri çağırma yöntemi (loadUrl, adBreakStarted ve adBreakEnded) uygulaması gerekir.

   3. Akış yüklendiğinde hızlı ileri/geri sarmayı devre dışı bırakarak kullanıcıların, reklam arası başladı etkinliği tetiklenmeden önce akış başladığı anda videodan önce gösterilen reklamı atlamasını önleyin.

   sub setupVideoPlayer()
     sdk = m.sdk
     m.player = sdk.createPlayer()
     m.player.top = m.top
     m.player.loadUrl = Function(urlData)
       ' This line prevents users from scanning during buffering
       ' or during the first second of the ad before we have a callback from roku.
       ' If there are no prerolls disabling trickplay isn't needed.
       m.top.video.enableTrickPlay = false
       m.top.urlData = urlData
     End Function
     m.player.adBreakStarted = Function(adBreakInfo as Object)
       print "---- Ad Break Started ---- "
       m.top.adPlaying = True
       m.top.video.enableTrickPlay = false
     End Function
     m.player.adBreakEnded = Function(adBreakInfo as Object)
       print "---- Ad Break Ended ---- "
       m.top.adPlaying = False
       m.top.video.enableTrickPlay = true
     End Function
     m.player.seek = Function(timeSeconds as Double)
       print "---- SDK requested seek to ----" ; timeSeconds
       m.top.video.seekMode = "accurate"
       m.top.video.seek = timeSeconds
     End Function
   End Sub
   Sdk.xml
   

   Atlanabilir reklamları desteklemek için seek geri çağırma yöntemi ekleyin. Daha fazla bilgi için Atlanabilir reklamlar için destek ekleme başlıklı makaleyi inceleyin.

2. setupVideoPlayer() alt rutininde kullanılan urlData, adPlaying ve video alanlarını ekleyin:

   <field id="urlData" type="assocarray" />
   <field id="adPlaying" type="Boolean" />
   <field id="video" type="Node" />
   Sdk.xml
   

Akış isteği oluşturma ve yürütme

DAI yayınınızı istemek için aşağıdakileri yapın:

1. Akış oluşturmak ve istemek için bir loadStream() alt programı oluşturun. Reklam Seçenekleri simgeleri gibi reklam kullanıcı arayüzünü desteklemek için isteğinizin bir parçası olarak içerik videonuzu içeren düğüme bir referans da iletmeniz gerekir:

   Sub loadStream()
     sdk = m.sdk
     sdk.initSdk()
     setupVideoPlayer()
   
     request = {}
     streamData = m.top.streamData
     if streamData.type = "live"
       request = sdk.CreateLiveStreamRequest(streamData.assetKey, streamData.apiKey, streamData.networkCode)
     else if streamData.type = "vod"
       request = sdk.CreateVodStreamRequest(streamData.contentSourceId, streamData.videoId, streamData.apiKey, streamData.networkCode)
     else
       request = sdk.CreateStreamRequest()
     end if
   
     request.player = m.player
     request.adUiNode = m.top.video
   
     requestResult = sdk.requestStream(request)
     If requestResult <> Invalid
       print "Error requesting stream ";requestResult
     Else
       m.streamManager = Invalid
       While m.streamManager = Invalid
         sleep(50)
         m.streamManager = sdk.getStreamManager()
       End While
       If m.streamManager = Invalid or m.streamManager["type"] <> Invalid or m.streamManager["type"] = "error"
         errors = CreateObject("roArray", 1, True)
         print "error ";m.streamManager["info"]
         errors.push(m.streamManager["info"])
         m.top.errors = errors
       Else
         m.top.streamManagerReady = True
         addCallbacks()
         m.streamManager.start()
       End If
     End If
   End Sub
   Sdk.xml
   

2. loadStream() alt rutininde kullanılan streamData ve streamManagerReady alanlarını ekleyin:

   <field id="streamManagerReady" type="Boolean" />
   <field id="streamData" type="assocarray" />
   Sdk.xml
   

3. Akış yöneticisi kullanılamıyorsa loadStream() alt rutininden runThread() alt rutinini çağırın:

   if not m.top.streamManagerReady
     loadStream()
   End If
   Sdk.xml
   

4. VOD veya canlı yayın arasında seçim yapın. Aşağıdaki örnekte, canlı yayın ve VOD akışı için akış parametreleri yer almaktadır:

   m.testLiveStream = {
     title: "Live Stream",
     assetKey: "c-rArva4ShKVIAkNfy6HUQ",
     networkCode: "21775744923",
     apiKey: "",
     type: "live"
   }
   m.testVodStream = {
     title: "VOD stream"
     contentSourceId: "2548831",
     videoId: "tears-of-steel",
     networkCode: "21775744923",
     apiKey: "",
     type: "vod"
   }
   MainScene.xml
   

   Bu kılavuz varsayılan olarak VOD akışını kullanır. selectedStream değişkenini m.testVodStream nesnesinden m.testLiveStream nesnesine değiştirerek bunun yerine canlı yayını kullanabilirsiniz.

Yayını başlatma

Akış verilerini dinlemek ve playStream() alt rutinini çağırmak için urlLoadRequested() alt rutinini oluşturun:

Sub urlLoadRequested(message as Object)
  print "Url Load Requested ";message
  data = message.getData()

  playStream(data.manifest, data.format)
End Sub
MainScene.xml

Akış oynatmayı başlatmak için playStream() oluşturun:

Sub playStream(url as String, format as String)
  vidContent = createObject("RoSGNode", "ContentNode")
  vidContent.url = url
  vidContent.title = m.videoTitle
  vidContent.streamformat = format
  m.video.content = vidContent
  m.video.setFocus(true)
  m.video.visible = true
  m.video.control = "play"
  m.video.EnableCookies()
End Sub
MainScene.xml

Akış meta verilerini dinleme

Akış oynatma sırasında çalışacak ve StreamManager.onMessage() kullanarak akış meta verilerini IMA'ya gönderecek bir while döngüsüyle runLoop() alt yordamı oluşturun:

Önemli nokta: Reklamların doğru şekilde oynatılması için tüm mesajları SDK'ya yönlendirmeniz gerekir.

Sub runLoop()
  ' Forward all timed metadata events.
  m.top.video.timedMetaDataSelectionKeys = ["*"]

  ' Cycle through all the fields and just listen to them all.
  m.port = CreateObject("roMessagePort")
  fields = m.top.video.getFields()
  for each field in fields
    m.top.video.observeField(field, m.port)
  end for

  while True
    msg = wait(1000, m.port)
    if m.top.video = invalid
      print "exiting"
      exit while
    end if

    m.streamManager.onMessage(msg)
    currentTime = m.top.video.position
    ' Only enable trickplay after a few seconds, in case we start with an ad,
    ' to prevent users from skipping through that ad.
    If currentTime > 3 And not m.top.adPlaying
       m.top.video.enableTrickPlay = true
    End If
  end while
End Sub
Sdk.xml

Reklam etkinliklerini dinleme

Artık akış meta verilerini IMA'ya ilettiğiniz için IMA, reklam araları sırasında reklam etkinlikleri yayınlayabilir. Reklam etkinliklerine yanıt vermek için gerektiğinde reklam etkinliği işleyicileri oluşturun:

Function addCallbacks() as Void
  m.streamManager.addEventListener(m.sdk.AdEvent.ERROR, errorCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.START, startCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.FIRST_QUARTILE, firstQuartileCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.MIDPOINT, midpointCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.THIRD_QUARTILE, thirdQuartileCallback)
  m.streamManager.addEventListener(m.sdk.AdEvent.COMPLETE, completeCallback)
End Function

Function startCallback(ad as Object) as Void
  print "Callback from SDK -- Start called - "
End Function

Function firstQuartileCallback(ad as Object) as Void
  print "Callback from SDK -- First quartile called - "
End Function

Function midpointCallback(ad as Object) as Void
  print "Callback from SDK -- Midpoint called - "
End Function

Function thirdQuartileCallback(ad as Object) as Void
  print "Callback from SDK -- Third quartile called - "
End Function

Function completeCallback(ad as Object) as Void
  print "Callback from SDK -- Complete called - "
End Function

Function errorCallback(error as Object) as Void
  print "Callback from SDK -- Error called - "; error
  ' errors are critical and should terminate the stream.
  m.errorState = True
End Function
Sdk.xml

Atlanabilir reklamlar için destek ekleme (isteğe bağlı)

Geçilebilir reklamları desteklemek için IMA DAI SDK'sının player nesnesine, videoyu belirtilen konuma (kayan noktalı saniye cinsinden) programatik olarak arayan bir seek yöntemi eklemeniz gerekir.

Atlanabilir reklamları desteklemek için isteğinizde adUiNode değerini de ayarladığınızdan emin olmanız gerekir.

m.player.seek = Function(timeSeconds as Double)
  print "---- SDK requested seek to ----" ; timeSeconds
  m.top.video.seekMode = "accurate"
  m.top.video.seek = timeSeconds
End Function
Sdk.xml