Konfigurowanie z DAI w trybie Full Service

Wybierz platformę: HTML5 Android iOS tvOS Cast Roku

Ten przewodnik pokazuje, jak zintegrować pakiet IMA DAI SDK z aplikacją odtwarzacza wideo. Jeśli chcesz zobaczyć lub prześledzić gotową przykładową integrację, pobierz podstawowy przykład z GitHuba.

Omówienie IMA DAI

Wdrożenie pakietu IMA DAI obejmuje 2 główne komponenty pakietu SDK, które zostały opisane w tym przewodniku:

  • StreamRequest: obiekt, który definiuje żądanie strumienia. Żądania strumieni mogą dotyczyć filmów na żądanie lub transmisji na żywo. Żądania transmisji na żywo określają klucz zasobu, a żądania VOD – identyfikator CMS i identyfikator filmu. Oba typy żądań mogą opcjonalnie zawierać klucz interfejsu API potrzebny do uzyskania dostępu do określonych strumieni oraz kod sieci Google Ad Managera, który umożliwia pakietowi IMA SDK obsługę identyfikatorów reklam zgodnie z ustawieniami Google Ad Managera.
  • StreamManager: obiekt, który obsługuje strumienie dynamicznego wstawiania reklam i interakcje z backendem DAI. Menedżer strumienia obsługuje też pingi śledzące i przekazuje wydawcy zdarzenia strumienia i reklamy.

Wymagania wstępne

Odtwarzanie filmu

Przykładowy odtwarzacz wideo odtwarza film od razu po uruchomieniu. Wdróż przykładowy odtwarzacz na urządzeniu Roku, aby sprawdzić, czy środowisko programistyczne jest prawidłowo skonfigurowane.

Przekształcanie odtwarzacza wideo w odtwarzacz strumieniowy IMA DAI

Aby wdrożyć odtwarzacz strumieniowy, wykonaj te czynności.

Utwórz plik Sdk.xml

Dodaj do projektu nowy plik o nazwie Sdk.xml obok pliku MainScene.xml i dodaj ten kod:

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>

W tym przewodniku musisz zmodyfikować oba te pliki.

Wczytywanie Roku Advertising Framework

Pakiet IMA DAI SDK zależy od Roku Advertising Framework. Aby wczytać platformę, dodaj do manifest i Sdk.xml te elementy:

bs_libs_required=roku_ads_lib,googleima3

Library "Roku_Ads.brs"
Library "IMA3.brs"

Wczytywanie pakietu IMA DAI SDK

Aby wczytać pakiet IMA DAI SDK, wykonaj te czynności:

  1. Zainicjuj pakiet IMA SDK za pomocą wywołania New_IMASDK():

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

  2. Sprawdź, czy pakiet IMA został wczytany, tworząc pole logiczne sdkLoaded:

    <field id="sdkLoaded" type="Boolean" />

  3. Wywołaj podprogram loadSdk() z głównego podprogramu runThread():

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

  4. Utwórz funkcję loadImaSdk() w MainScene.xml, aby utworzyć i uruchomić obiekt sdkTask:

    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

  5. Wywołaj funkcję loadImaSdk() z funkcji init().

  6. Utwórz podprogramy detektorów onSdkLoaded() i onSdkLoadedError(), aby reagować na zdarzenia wczytywania pakietu SDK:

    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

Tworzenie odtwarzacza strumieni IMA

Aby utworzyć odtwarzacz strumieni IMA:

  1. Utwórz podprogram setupVideoPlayer(), który wykonuje te czynności:

    1. Użyj metody createPlayer(), aby utworzyć odtwarzacz strumienia.

    2. Zaimplementuj w tym odtwarzaczu 3 metody wywołania zwrotnego: loadUrl, adBreakStarted i adBreakEnded.

    3. Wyłącz tryb trick play po wczytaniu strumienia, aby uniemożliwić użytkownikom pominięcie reklamy przed filmem w momencie rozpoczęcia strumienia, zanim zostanie wywołane zdarzenie rozpoczęcia przerwy na reklamę.

    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

    Aby obsługiwać reklamy możliwe do pominięcia, dodaj metodę wywołania zwrotnego seek. Więcej informacji znajdziesz w artykule Dodawanie obsługi reklam możliwych do pominięcia.

  2. Dodaj pola urlData, adPlaying i video używane w podprogramie setupVideoPlayer():

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

Tworzenie i wykonywanie żądania strumienia

Aby poprosić o transmisję DAI:

  1. Utwórz podprogram loadStream(), aby utworzyć strumień i wysłać żądanie. Aby obsługiwać interfejs reklamy, np. ikony Informacja, w żądaniu musisz też przekazać odwołanie do węzła zawierającego film:

    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

  2. Dodaj pola streamData i streamManagerReady używane w podprogramie loadStream():

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

  3. Jeśli menedżer strumienia jest niedostępny, wywołaj podprogram loadStream() z podprogramu runThread():

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

  4. Wybierz VOD lub transmisję na żywo. Poniższy przykład zawiera parametry strumienia dla transmisji na żywo i strumienia VOD:

    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"
}

    Domyślnie w tym przewodniku używany jest strumień VOD. Możesz zamiast tego użyć transmisji na żywo, zmieniając zmienną selectedStream z obiektu m.testVodStream na obiekt m.testLiveStream.

Rozpoczynanie transmisji

Utwórz podprocedurę urlLoadRequested(), która będzie nasłuchiwać danych strumienia i wywoływać podprocedurę playStream():

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

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

Utwórz playStream(), aby rozpocząć odtwarzanie strumienia:

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

Nasłuchiwanie metadanych strumienia

Utwórz podprogram runLoop() z pętlą while, który będzie działać podczas odtwarzania strumienia i wysyłać metadane strumienia do IMA za pomocą StreamManager.onMessage():

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

Nasłuchiwanie zdarzeń reklamowych

Teraz, gdy przekazujesz metadane strumienia do IMA, IMA może emitować zdarzenia reklamowe podczas przerw na reklamę. W razie potrzeby utwórz detektory zdarzeń reklamowych, aby reagować na zdarzenia reklamowe:

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

Dodawanie obsługi reklam możliwych do pominięcia (opcjonalnie)

Aby obsługiwać reklamy możliwe do pominięcia, musisz dodać metodę seek do obiektu odtwarzacza pakietu IMA DAI SDK, która automatycznie przewija film do określonego miejsca (w sekundach w reprezentacji zmiennoprzecinkowej).

Aby obsługiwać reklamy możliwe do pominięcia, musisz też ustawić w żądaniu parametr adUiNode.

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