Konfigurowanie pakietu IMA SDK na potrzeby DAI

Wybierz platformę: HTML5 Android iOS tvOS Cast Roku

Pakiety IMA SDK ułatwiają integrację reklam multimedialnych z witrynami i aplikacjami. Pakiety IMA SDK mogą wysyłać żądania reklam do dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w aplikacjach. Za pomocą pakietów IMA DAI SDK aplikacje wysyłają żądanie strumienia reklamy i treści wideo – VOD lub treści na żywo. Pakiet SDK zwraca wtedy połączony strumień wideo, dzięki czemu nie musisz zarządzać przełączaniem między reklamą a treściami wideo w aplikacji.

Wybierz interesujące Cię rozwiązanie DAI

Pełna obsługa Pod serving

Dynamiczne wstawianie reklam z pełną obsługą

Z tego przewodnika dowiesz się, jak zintegrować pakiet IMA DAI SDK z prostą aplikacją odtwarzacza wideo. Jeśli chcesz wyświetlić gotową przykładową integrację lub z niej skorzystać, pobierz podstawowy przykład z GitHub.

Uwaga: pakiet IMA DAI SDK na platformę Roku obsługuje strumienie HLS i DASH bez różnic w implementacji.

Aby korzystać z IMA DAI, musisz mieć konto Ad Managera 360 w wersji Advanced. Jeśli masz konto Ad Managera, skontaktuj się z menedżerem konta, aby uzyskać więcej informacji. Informacje o rejestracji w usłudze Ad Manager znajdziesz w Centrum pomocy Ad Managera.

Uwaga: informacje o integracji z innymi platformami lub o korzystaniu z pakietów IMA SDK po stronie klienta znajdziesz w artykule Pakiety Interactive Media Ads SDK.

Omówienie IMA DAI

Wdrożenie IMA DAI obejmuje 2 główne komponenty pakietu SDK, jak pokazano w tym przewodniku:

• StreamRequest: obiekt, który definiuje żądanie strumienia. Żądania strumieni mogą dotyczyć transmisji wideo na żądanie lub transmisji na żywo. Żądania transmisji na żywo określają klucz pliku, a żądania VOD – identyfikator CMS i identyfikator wideo. Oba typy żądań mogą opcjonalnie zawierać klucz API potrzebny do uzyskania dostępu do określonych strumieni oraz kod sieci Google Ad Managera, aby pakiet IMA SDK mógł obsługiwać identyfikatory 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 przesyła zdarzenia strumienia i reklamy do wydawcy.

Wymagania wstępne

• Zapoznaj się z informacjami na stronie dotyczącej zgodności, aby upewnić się, że Twój przypadek użycia jest obsługiwany.
• Pobierz nasz przykładowy kod odtwarzacza Roku
• Wdróż przykładowy kod odtwarzacza na urządzeniu Roku, aby sprawdzić, czy konfiguracja deweloperska działa.

Odtwarzanie filmu

Przykładowy odtwarzacz wideo odtwarza film z treściami od razu po uruchomieniu. Wdróż przykładowy odtwarzacz na urządzeniu Roku, aby upewnić się, że środowisko programistyczne jest prawidłowo skonfigurowane.

Przekształcanie odtwarzacza wideo w odtwarzacz strumieni IMA DAI

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

Tworzenie pliku Sdk.xml

Dodaj do projektu nowy plik obok pliku MainScene.xml o nazwie Sdk.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 edytować oba te pliki.

Załaduj platformę reklamową Roku

Pakiet IMA DAI SDK zależy od platformy reklamowej Roku. Aby załadować platformę, dodaj ten kod do plików manifest i Sdk.xml:

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 IMA została wczytana, 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 detektora 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 strumieniowego IMA

Aby utworzyć odtwarzacz strumieni IMA:

1. Utwórz setupVideoPlayer() podprogram, który:

   1. Aby utworzyć odtwarzacz strumienia, użyj metody createPlayer().

   2. Odtwarzacz strumienia powinien implementować 3 metody wywołania zwrotnego: loadUrl, adBreakStarted i adBreakEnded.

   3. Wyłącz przewijanie, gdy strumień jest załadowany, aby uniemożliwić użytkownikom pomijanie reklamy przed filmem w momencie rozpoczęcia strumienia, zanim zostanie uruchomione 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
   

   Dodaj seek metodę wywołania zwrotnego, aby obsługiwać reklamy możliwe do pominięcia. Więcej informacji znajdziesz w artykule Dodawanie obsługi reklam, które można pominąć.

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 strumień DAI:

1. Utwórz podprogram loadStream(), który będzie tworzyć strumień i wysyłać do niego żądania. Aby obsługiwać interfejs reklam, np. ikony wyboru reklam, musisz też przekazać w ramach żądania odwołanie do węzła zawierającego film z treścią:

   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 loadStream() podprogramie:

   <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. W tym przykładzie znajdują się 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. Zamiast tego możesz użyć transmisji na żywo, zmieniając zmienną selectedStream z obiektu m.testVodStream na obiekt m.testLiveStream.

Rozpocznij transmisję

Utwórz podprogram urlLoadRequested(), który będzie nasłuchiwać danych strumienia i wywoływać podprogram 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óra będzie działać podczas odtwarzania strumienia i wysyłać metadane strumienia do IMA za pomocą StreamManager.onMessage():

Ważne: aby zapewnić prawidłowe odtwarzanie reklam, musisz przekazywać wszystkie wiadomości do pakietu SDK.

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 reklamy. W razie potrzeby utwórz detektory zdarzeń reklam, aby reagować na zdarzenia reklam:

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, które można pominąć, musisz dodać seekmetodę do obiektu odtwarzacza pakietu IMA DAI SDK, która programowo wyszukuje wideo w określonej lokalizacji (w sekundach zmiennoprzecinkowych).

Aby obsługiwać reklamy, które można pominąć, 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