Başlayın

IMA SDK'ları, multimedya reklamlarını web sitelerinize ve uygulamalarınıza entegre etmenizi kolaylaştırır. IMA SDK'ları VAST ile uyumlu herhangi bir reklam sunucusundan reklam isteyebilir ve uygulamalarınızda reklam oynatmayı yönetebilir. Uygulamalar, IMA DAI SDK'larını kullanarak reklam ve içerik videosu için (VOD veya canlı içerik) akış isteğinde bulunur. SDK, daha sonra birleştirilmiş bir video akışı döndürür. Böylece uygulamanızda reklam ve içerik videosu arasında geçiş yapma işlemini yönetmenize gerek kalmaz.

Bu kılavuzda, IMA 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 bunu takip etmek istiyorsanız GitHub'daki temel örneği indirin.

IMA DAI'ya genel bakış

IMA DAI'yı uygulamak için bu kılavuzda gösterilen iki ana SDK bileşeni bulunur:

  • StreamRequest: Bir akış isteğini tanımlayan nesne. Akış istekleri, seç-izle video veya canlı yayınlar için olabilir. İstekler bir içerik kimliğinin yanı sıra bir API anahtarı veya kimlik doğrulama jetonu ve diğer parametreleri belirtir.
  • StreamManager: Dinamik reklam ekleme akışlarını ve DAI arka ucuyla etkileşimleri işleyen bir nesne. Akış yöneticisi, izleme ping'lerini de gerçekleştirir ve akış ile reklam etkinliklerini yayıncıya yönlendirir.

Ön koşullar

Başlamadan önce:

  • Amaçladığınız kullanım alanının desteklendiğinden emin olmak için uyumluluk sayfamızı okuyun.
  • Roku örnek oynatıcı kodumuzu indirin.
  • Geliştirme kurulumunuzun çalıştığını doğrulamak için yukarıdaki örnek oynatıcı kodunu bir Roku cihaza dağıtın.

Videonuzu oynatma

Sağlanan örnek video oynatıcı, kutudan çıktığı yerde bir içerik videosu oynatır. Geliştirme ortamınızın uygun şekilde ayarlandığından emin olmak için örnek oynatıcıyı Roku oynatıcınıza dağıtın.

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

Sdk.xml oluşturun

Projenize MainScene.xml adlı yeni Sdk.xml adlı dosyayı ve aşağıdaki ortak 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ılavuzdaki her iki dosyayı da düzenlemeniz gerekir. Her kod snippet'inin üstündeki başlık, ilgili snippet'i hangi dosyada eklemeniz gerektiğini gösterir.

Roku Reklam Çerçevesi'ni yükleme

IMA SDK, Roku Reklamcılık Çerçevesi'ne bağlıdır. Çerçeveyi yüklemek için manifest ve Sdk.xml birlikte aşağıdaki öğeleri ekleyin:

manifest
bs_libs_required=roku_ads_lib,googleima3
Sdk.xml
Library "Roku_Ads.brs"
Library "IMA3.brs"

IMA SDK'yı yükleyin

IMA Dinamik Reklam Ekleme akışınızı yüklemenin ilk adımı IMA SDK'yı yüklemek ve başlatmaktır. Aşağıda, IMA SDK komut dosyası yüklenir.

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

sub init()
  m.top.functionName = "runThread"
End Sub

sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
End Sub

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

Şimdi MainScene.xml içinde bu göreve başlayın ve içerik akışını yüklemek için aramayı kaldırın.

MainScene.xml
function init()
  m.video = m.top.findNode("myVideo")
  m.video.notificationinterval = 1
  loadImaSdk()
end function

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  m.sdkTask.control = "RUN"
end function

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

IMA akış oynatıcı oluşturma

Ardından, bir IMA akış oynatıcı oluşturmak için mevcut roVideoScreen öğenizi kullanmanız gerekir. Bu akış oynatıcısı üç geri çağırma yöntemi uygular: loadUrl, adBreakStarted ve adBreakEnded. Ayrıca, akış yüklendiğinde hile oynatmayı da devre dışı bırakın. Bu, kullanıcıların reklam arası başlatılmış etkinliği tetiklenmeden hemen önce, bir videodan önce gösterilen reklamı atlamasını önler.

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

...
sub setupVideoPlayer()
  sdk = m.sdk
  m.player = sdk.createPlayer()
  m.player.top = m.top
  m.player.loadUrl = Function(urlData)
    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 Float)
    print "---- SDK requested seek to ----" ; timeSeconds
    m.top.video.seekMode = "accurate"
    m.top.video.seek = timeSeconds
  End Function
End Sub

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

Artık bir akış oynatıcınız olduğuna göre akış isteği oluşturup yürütebilirsiniz. Bu örnekte canlı yayın ve VOD akışıyla ilgili veriler bulunmaktadır. Şu anda VOD akışı kullanılıyor. VOD yerine canlı yayın kullanmak için selectedStream olan değeri m.testVodStream yerine m.testLiveStream olarak değiştirin.

AdUI simgelerini destekleyebilmek için, isteğinizin bir parçası olarak içerik videonuzu içeren düğüme referans vermeniz gerekir.

MainScene.xml
function init()
  m.video = m.top.findNode("myVideo")
  m.video.notificationinterval = 1
  m.testLiveStream = {
    title: "Live Stream",
    assetKey: "sN_IYUG8STe1ZzhIIE_ksA",
    apiKey: "",
    type: "live"
  }
  m.testVodStream = {
    title: "VOD stream"
    contentSourceId: "2528370",
    videoId: "tears-of-steel",
    apiKey: "",
    type: "vod"
  }
  loadImaSdk()
end function

function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  selectedStream = m.testVodStream
  m.videoTitle = selectedStream.title
  m.sdkTask.streamData = selectedStream

  m.sdkTask.video = m.video
  m.sdkTask.control = "RUN"
end function
Sdk.xml
<interface>
  <field id="sdkLoaded" type="Boolean" />
  <field id="errors" type="stringarray" />
  <field id="urlData" type="assocarray" />
  <field id="adPlaying" type="Boolean" />
  <field id="video" type="Node" />
  <field id="streamData" type="assocarray" />
  <field id="streamManagerReady" type="Boolean" />
</interface>

sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
  if not m.top.streamManagerReady
    loadStream()
  End If
End Sub

Sub loadStream()
  sdk = m.sdk
  sdk.initSdk()
  setupVideoPlayer()

  request = {}
  if m.top.streamData.type = "live"
    request = sdk.CreateLiveStreamRequest(m.top.streamData.assetKey, m.top.streamData.apiKey)
  else if m.top.streamData.type = "vod"
    request = sdk.CreateVodStreamRequest(m.top.streamData.contentSourceId, m.top.streamData.videoId, m.top.streamData.apiKey)
  else
    request = sdk.CreateStreamRequest()
  end if

  request.player = m.player
  request.adUiNode = m.top.video
  request.videoObject = 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

Etkinlik işleyicileri ekleme ve akışı başlatma

Yayınınızı istedikten sonra yapmanız gereken birkaç şey daha vardır: reklam ilerlemesini izlemek, yayınınızı başlatmak ve Roku mesajlarını SDK'ya yönlendirmek için etkinlik dinleyicileri ekleyin. Reklamın doğru oynatılabilmesi için tüm mesajları SDK'ya yönlendirmeniz son derece önemlidir.

MainScene.xml
function loadImaSdk() as void
  m.sdkTask = createObject("roSGNode", "imasdk")
  m.sdkTask.observeField("sdkLoaded", "onSdkLoaded")
  m.sdkTask.observeField("errors", "onSdkLoadedError")

  selectedStream = m.testVodStream
  m.videoTitle = selectedStream.title
  m.sdkTask.streamData = selectedStream

  m.sdkTask.observeField("urlData", "urlLoadRequested")
  m.sdkTask.video = m.video
  m.sdkTask.control = "RUN"
end function

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

  playStream(data.manifest)
End Sub

Sub playStream(url as Object)
  vidContent = createObject("RoSGNode", "ContentNode")
  vidContent.url = url
  vidContent.title = m.videoTitle
  vidContent.streamformat = "hls"
  m.video.content = vidContent
  m.video.setFocus(true)
  m.video.visible = true
  m.video.control = "play"
  m.video.EnableCookies()
End Sub
Sdk.xml
sub runThread()
  if not m.top.sdkLoaded
    loadSdk()
  End If
  if not m.top.streamManagerReady
    loadStream()
  End If
  If m.top.streamManagerReady
    runLoop()
  End If
End Sub

Sub runLoop()
  m.top.video.timedMetaDataSelectionKeys = ["*"]

  m.port = CreateObject("roMessagePort")

  ' Listen to all fields.

  ' IMPORTANT: Failure to listen to the position and timedmetadata fields
  ' could result in ad impressions not being reported.
  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
    If currentTime > 3 And not m.top.adPlaying
       m.top.video.enableTrickPlay = true
    End If
  end while
End Sub

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
  m.errorState = True
End Function