Konfigurowanie z DAI w trybie Full Service

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

• Przeczytaj naszą stronę ze zgodnymi urządzeniami, aby upewnić się, że Twój przypadek użycia jest obsługiwany.
• Pobierz przykładowy kod odtwarzacza na Roku.
• Wdróż przykładowy kod odtwarzacza na urządzeniu Roku, aby sprawdzić, czy konfiguracja programistyczna działa.

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
manifest

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

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
   Sdk.xml
   

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

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

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

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

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
   MainScene.xml
   

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
   MainScene.xml
   

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
   Sdk.xml
   

   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" />
   Sdk.xml
   

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
   Sdk.xml
   

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

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

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

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

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"
   }
   MainScene.xml
   

   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
MainScene.xml

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
MainScene.xml

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
Sdk.xml

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
Sdk.xml

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
Sdk.xml