Pierwsze kroki z pakietem IMA DAI SDK

Wybierz rozwiązanie DAI, które Cię interesuje

Blok reklamowy z dynamicznym wstawianiem reklam

Pakiety IMA SDK upraszczają integrację reklam multimedialnych z witrynami i aplikacjami.

Pakiety IMA SDK mogą żądać reklam z dowolnego serwera reklam zgodnego z VAST i zarządzać odtwarzaniem reklam w aplikacjach.

Dzięki pakietom SDK IMA DAI aplikacje wysyłają żądania strumieniowania reklam i treści wideo na potrzeby VOD lub treści na żywo. Pakiet SDK zwraca połączony strumień wideo, więc nie musisz już zarządzać przełączaniem się między reklamą a treścią wideo w aplikacji.

Ten przewodnik pokazuje, jak odtwarzać strumień wyświetlania podów z dynamicznym wstawianiem reklam na żywo za pomocą pakietu IMA DAI SDK do CAF.

Przed skorzystaniem z tego przewodnika zapoznaj się z protokołem Odbiornika internetowego Chromecasta. W tym przewodniku zakładamy, że masz podstawowe informacje o odbiornikach CAF, takich jak obiekty przechwytujące wiadomości i mediaInformation, oraz wiesz, jak używać narzędzia Cast and Control do emulowania nadawcy CAF.

Aby korzystać z wyświetlania podów z IMA DAI, musisz współpracować z partnerem, który wyświetla bloki reklamowe, i mieć konto Ad Manager 360 Advanced. Jeśli masz konto Ad Managera, skontaktuj się z menedżerem konta, aby uzyskać więcej informacji. Informacje o rejestrowaniu się w usłudze Ad Manager znajdziesz w Centrum pomocy tej usługi.

Informacje o integracji z innymi platformami lub o korzystaniu z pakietów SDK IMA po stronie klienta znajdziesz w artykule Pakiety SDK do interaktywnych reklam multimedialnych.

Omówienie wyświetlania podów z IMA DAI

Implementacja wyświetlania podów za pomocą pakietu SDK IMA CAF DAI obejmuje 2 główne komponenty, które przedstawiono w tym przewodniku:

  • StreamRequest: obiekt definiujący żądanie strumienia do serwerów reklamowych Google. Żądania określają kod sieci, niestandardowy klucz zasobu i opcjonalny klucz interfejsu API, a także inne parametry opcjonalne.
  • StreamManager: obiekt obsługujący komunikację między strumieniem wideo a pakietem IMA DAI SDK, np. uruchamianie pingów śledzących i przekazywanie zdarzeń strumienia do wydawcy.

Wymagania wstępne

Konfigurowanie obiektów MediaInfo nadawcy

Najpierw skonfiguruj obiekt MediaInfo aplikacji nadawcy, tak aby zawierał te pola:

Pole Spis treści
contentId Unikalny identyfikator tego elementu multimedialnego.

CONTENT_ID
contentUrl Opcjonalnie. Zapasowy adres URL strumienia, który będzie odtwarzany, gdy nie uda się wczytać strumienia z dynamicznym wstawianiem reklam.

BACKUP_STREAM_URL

contentType Opcjonalnie. Typ MIME strumieni zapasowych treści. Wymagane tylko w przypadku transmisji DASH.

CONTENT_STREAM_MIMETYPE
streamType Stały lub literał ciągu znaków używane dla tej wartości różnią się w zależności od platformy nadawcy.
customData Pole customData zawiera pary klucz-wartość z dodatkowymi polami wymaganymi.
Pole Spis treści
manifestUrl Adres URL strumienia wideo podany przez manipulator pliku manifestu lub partnera zewnętrznego. Przed wysłaniem żądania powinno być wymagane wstawienie identyfikatora strumienia dostarczonego przez pakiet IMA DAI SDK. W tym przykładzie adres URL manifestu zawiera obiekt zastępczy ([[STREAMID]]), który przed wysłaniem żądania jest zastępowany identyfikatorem strumienia.

MANIFEST_URL
networkCode Kod sieci powiązany z kontem Google Ad Managera 360.

NETWORK_CODE
customAssetKey Niestandardowy klucz pliku identyfikujący zdarzenie wyświetlania bloku reklamowego w usłudze Google Ad Manager 360. W niektórych przypadkach może on pochodzić z manipulatora pliku manifestu lub przez zewnętrznego partnera obsługującego pody.

CUSTOM_ASSET_KEY
apiKey Opcjonalny klucz interfejsu API do pobierania identyfikatora strumienia z pakietu IMA DAI SDK.

API_KEY

Oto kilka przykładów kodu, które ułatwią Ci rozpoczęcie pracy:

Internet

Aby skonfigurować te wartości w narzędziu Cast Web Sender, najpierw utwórz obiekt MediaInfo z wymaganymi danymi, a potem wyślij do odbiornika internetowego żądanie wczytania.

// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "CONTENT_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.LIVE;
mediaInfo.customData = {
manifestUrl: "MANIFEST_URL",
networkCode: "NETWORK-CODE",
customAssetKey: "CUSTOM_ASSET_KEY",
apiKey: "API_KEY"
};

// Make load request to cast web receiver
const castSession = cast.framework.CastContext.getInstance().getCurrentSession();
const request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
  () => { console.log('Load succeed'); },
  (errorCode) => { console.log('Error code: ' + errorCode); });

Android

Aby skonfigurować te wartości w nadawcy Cast w sieci, najpierw utwórz obiekt MediaInfo z wymaganymi danymi, a następnie wyślij żądanie ładowania do odbiornika internetowego.

JSONObject customData = new JSONObject()?
  .put("manifestUrl", "MANIFEST_URL")
  .put("networkCode", "NETWORK-CODE")
  .put("customAssetKey", "CUSTOM_ASSET_KEY")
  .put("apiKey", "API_KEY");
MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("CONTENT_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_LIVE)
  .setCustomData(customData)
  .build();

RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());

iOS (Obj-C)

Aby skonfigurować te wartości w narzędziu Cast Web Sender, najpierw utwórz obiekt GCKMediaInformation z wymaganymi danymi, a potem wyślij do odbiornika internetowego żądanie wczytania.

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"manifestUrl": @"MANIFEST_URL",
  @"networkCode": @"NETWORK-CODE",
  @"customAssetKey": @"CUSTOM_ASSET_KEY",
  @"apiKey": @"API_KEY"};
mediaInfoBuilder.customData = customData;

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeLive;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];

GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
  request.delegate = self;
}

iOS (Swift)

Aby skonfigurować te wartości w narzędziu Cast Web Sender, najpierw utwórz obiekt GCKMediaInformation z wymaganymi danymi, a potem wyślij do odbiornika internetowego żądanie wczytania.

let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
  print("invalid mediaURL")
  return
}

let customData = [
  "liveConfigID": "MANIFEST_URL",
  "networkCode": "NETWORK-CODE",
  "customAssetKey": "CUSTOM_ASSET_KEY",
  "region": "API_KEY"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = @"CONTENT_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.Live
mediaInfoBuilder.customData = customData
mediaInformation = mediaInfoBuilder.build()

guard let mediaInfo = mediaInformation else {
  print("invalid mediaInformation")
  return
}

if let request = sessionManager.currentSession?.remoteMediaClient?.loadMedia
(mediaInfo) {
  request.delegate = self
}

Narzędzie CAC

Aby skonfigurować te wartości w narzędziu Cast Command and Control, kliknij kartę Wczytaj multimedia i ustaw niestandardowy typ żądania wczytywania na WCZYTAJ. Następnie zastąp dane JSON w obszarze tekstowym tym kodem JSON:

{
  "media": {
    "contentId": "CONTENT_ID",
    "contentUrl": "BACKUP_STREAM_URL",
    "contentType": ""CONTENT_STREAM_MIMETYPE"",
    "streamType": "LIVE",
    "customData": {
      "liveConfigID": "MANIFEST_URL",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

To niestandardowe żądanie obciążenia może zostać wysłane do odbiorcy w celu przetestowania pozostałych kroków.

Tworzenie podstawowego odbiornika CAF

Utwórz niestandardowy odbiornik internetowy zgodnie z opisem w przewodniku po niestandardowym odbiorniku internetowym SDK CAF.

Kod Twojego odbiornika powinien wyglądać tak:

<html>
<head>
  <script
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js">
  </script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    // ...
  </script>
</body>
</html>

Zaimportuj pakiet IMA DAI SDK i pobierz Menedżera odtwarzaczy.

Dodaj tag skryptu, by zaimportować pakiet IMA DAI SDK dla CAF do odbiornika internetowego zaraz po wczytaniu skryptu. Zanim uruchomisz moduł odbierający, zapisz w tagu skryptu kontekst odbiorcy i menedżera odtwarzacza w postaci stałych.

<html>
<head>
  <script
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();

    castContext.start();
  </script>
</body>
</html>

Inicjowanie Menedżera strumieni IMA

Zainicjuj Menedżera strumieni IMA.

<html>
<head>
  <script type="text/javascript"
      src="//www.gstatic.com/cast/sdk/libs/caf_receiver/v3/cast_receiver_framework.js"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/cast_dai.js"></script>
</head>
<body>
  <cast-media-player></cast-media-player>
  <script>
    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    castContext.start();
  </script>
</body>
</html>

Tworzenie przechwytującego obciążenia w usłudze Stream Manager

Zanim elementy multimedialne zostaną przekazane do CAF, utwórz żądanie strumienia w elemencie przechwytującym komunikatu LOAD.

    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    /**
     * Creates a livestream request object for a pod serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => { /* ... */};

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');
            // ...
            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

    playerManager.setMessageInterceptor(
        cast.framework.messages.MessageType.LOAD, createDAICastRequest);

    castContext.start();

Utwórz żądanie strumienia

Wykonaj funkcję createStreamRequest, aby utworzyć pod obsługujący strumień na podstawie żądania obciążenia CAF.

    /**
     * Creates a livestream request object for a pod serving stream.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => {

      const streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
      const customData = castRequest.media.customData;

      streamRequest.customAssetKey = customData.customAssetKey;
      streamRequest.networkCode = customData.networkCode;
      streamRequest.apiKey = customData.apiKey;

      return streamRequest;
    };

Zastąp URL treści adresem URL pliku manifestu i identyfikatorem strumienia.

Jeśli żądanie strumienia zostało zrealizowane, użyj polecenia streamManager.getStreamId(), aby pobrać identyfikator strumienia i wstaw go w polu manifestUrl, zastępując [[STREAMID]]. Następnie zastąp dotychczasowy contentUrl nowym manifestUrl, aby CAF odtwarzał transmisję na żywo z połączonymi blokami reklamowymi.

    /**
     * Initates a DAI stream request for the final stream manifest.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {Promise<LoadRequestData>} a promise that resolves to an updated castRequest, containing the DAI stream manifest
     */
    const createDAICastRequest = (castRequest) => {
        return streamManager.requestStream(castRequest, createStreamRequest(castRequest))
          .then((castRequestWithPodStreamData) => {
            console.log('Successfully made DAI stream request.');
            const media = castRequestWithPodStreamData.media;
                const manifestUrl = media.customData.manifestUrl || "";
                if (manifestUrl) {
                    console.log('Replacing the contentURL with the manifest URL and stream ID');
                    const streamId = streamManager.getStreamId();
                    castRequestWithPodStreamData.media.contentUrl = manifestUrl.replace('[[STREAMID]]', streamId);

            return castRequestWithPodStreamData;
          })
          .catch((error) => {
            console.log('Failed to make DAI stream request.');
            // CAF will automatically fallback to the content URL
            // that it can read from the castRequest object.
            return castRequest;
          });
    };

Teraz możesz żądać strumieni udostępniających pody i je odtwarzać za pomocą platformy Cast Application Framework i pakietu IMA DAI SDK dla CAF.