Pierwsze kroki z pakietem IMA DAI SDK

Wybierz interesujące Cię rozwiązanie DAI

Pełna usługa Pod serving

Wyświetlanie bloków reklamowych w ramach dynamicznego wstawiania reklam

Pakiety IMA SDK ułatwiają 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 aplikacji.

Dzięki pakietom IMA DAI SDK aplikacje wysyłają żądanie strumienia reklamy i treści wideo na potrzeby VOD lub transmisji na żywo. Pakiet SDK zwraca następnie połączony strumień wideo, dzięki czemu nie musisz przełączać się między reklamą a treścią wideo w aplikacji.

Ten przewodnik pokazuje, jak odtwarzać strumień z dynamiczną usługą wyświetlania reklam, korzystając z pakietu IMA DAI SDK dla CAF.

Uwaga: pakiet IMA DAI SDK for CAF obsługuje strumienie HLS i DASH bez żadnych różnic w implementacji.

Zanim skorzystasz z tego przewodnika, zapoznaj się z protokołem Web Receiver w ramach Chromecast Application Framework. Ten przewodnik zakłada, że znasz podstawowe pojęcia związane z odbiornikami CAF, takie jak przechwytywacze wiadomości i obiekty mediaInformation, oraz że potrafisz używać narzędzia do sterowania i kontroli Cast, aby emulować nadawcę CAF.

Aby korzystać z wyświetlania bloków reklamowych w ramach IMA DAI, musisz współpracować z partnerem ds. wyświetlania bloków reklamowych i mieć konto Ad Managera 360 Advanced. Jeśli masz konto w usłudze Ad Manager, aby uzyskać więcej informacji, skontaktuj się ze swoim opiekunem klienta. Informacje o rejestracji w usłudze Ad Manager znajdziesz w Centrum pomocy Ad Managera.

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

Omówienie wyświetlania bloków reklamowych w ramach IMA DAI

Wdrożenie wyświetlania bloków reklamowych za pomocą pakietu IMA CAF DAI SDK wymaga 2 głównych komponentów, które są opisane w tym przewodniku:

• StreamRequest: obiekt definiujący żądanie strumienia do serwerów reklamowych Google. Żądania zawierają kod sieci, klucz zasobu niestandardowego i opcjonalnie 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. wysyłanie pingów śledzenia i przekazywanie zdarzeń strumienia do wydawcy.

Wymagania wstępne

• Konto w Konsoli programisty Cast z zarejestrowanymi urządzeniami testowymi.
• hostowana aplikacja internetowa odbiornika, która jest zarejestrowana w Konsoli programisty Google Cast i może zostać zmodyfikowana, aby hostować kod podany w tym przewodniku.
• Aplikacja wysyłająca skonfigurowana do korzystania z aplikacji internetowej odbiornika. W tym przykładzie użyj narzędzia do sterowania i kontroli Cast jako nadawcy.

Konfigurowanie obiektów MediaInfo nadawcy

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

Pole	Spis treści
contentId	Unikalny identyfikator tego elementu multimedialnego. CONTENT_ID
contentUrl	Opcjonalnie: Adres URL strumienia zapasowego do odtworzenia, jeśli nie uda się załadować strumienia DAI. BACKUP_STREAM_URL
contentType	Opcjonalnie: Typ MIME strumieni kopii zapasowych treści. Wymagane tylko w przypadku strumieni danych typu DASH. CONTENT_STREAM_MIMETYPE
streamType	Literał ciągu znaków lub stała używana w przypadku tej wartości różni się w zależności od platformy nadawcy.
customData	Pole customData zawiera klucz-wartość dodatkowych wymaganych pól. W tym przykładzie zawiera on parametry strumienia DAI. W wersji produkcyjnej aplikacji możesz zamiast tego przekazać identyfikator, którego Twoja aplikacja odbiornika strumieniowego użyje do pobrania tych parametrów za pomocą żądania po stronie serwera. Pole Spis treści daiStreamType Typ strumienia DAI: "LIVE" lub "VOD" DAI_STREAM_TYPE networkCode Kod sieci na koncie Google Ad Managera 360. NETWORK_CODE customAssetKey To pole jest wymagane tylko w przypadku transmisji na żywo. Niestandardowy klucz zasobu, który identyfikuje zdarzenie wyświetlania w grupie w usłudze Google Ad Manager 360. 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:

Sieć

Aby skonfigurować te wartości w nadajniku internetowym Google Cast, najpierw utwórz obiekt MediaInfo z wymaganymi danymi, a potem prześlij żądanie wczytania do odbiornika internetowego.

// 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 = {
  daiStreamType: "DAI_STREAM_TYPE",
  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 nadajniku internetowym Google Cast, najpierw utwórz obiekt MediaInfo z wymaganymi danymi, a potem prześlij żądanie wczytania do odbiornika internetowego.

JSONObject customData = new JSONObject()?
  .put("daiStreamType", "DAI_STREAM_TYPE")
  .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 (język Obj-C)

Aby skonfigurować te wartości w nadajniku internetowym Google Cast, najpierw utwórz obiekt GCKMediaInformation z wymaganymi danymi, a potem prześlij żądanie wczytania do odbiornika internetowego.

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"daiStreamType": @"DAI_STREAM_TYPE",
  @"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 nadajniku internetowym Google Cast, najpierw utwórz obiekt GCKMediaInformation z wymaganymi danymi, a potem prześlij żądanie wczytania do odbiornika internetowego.

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

let customData = [
  "daiStreamType": "DAI_STREAM_TYPE",
  "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ę Ładuj media i ustaw typ żądania niestandardowego ładowania na LOAD. Następnie w obszarze tekstowym zastąp dane JSON tym kodem:

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

Prośbę o niestandardowe wczytywanie można wysłać do odbiorcy, aby przetestować pozostałe kroki.

Tworzenie podstawowego odbiornika CAF

Utwórz niestandardowy odbiornik internetowy, zgodnie z opisem w przewodniku dotyczącym pakietu CAF SDK.

Kod odbiorcy 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, aby zaimportować pakiet IMA DAI SDK for CAF do odbiornika internetowego, tuż po załadowaniu skryptu CAF. W tagu skryptu przechowuj kontekst odbiornika i menedżera odtwarzania jako stałe przed uruchomieniem odbiornika.

<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 strumienia IMA

Inicjowanie Menedżera strumienia 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 przekierowującego obciążenie menedżera strumienia

Zanim elementy multimediów zostaną przekazane do CAF, utwórz żądanie strumienia w interceptorze LOAD message.

    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();

Tworzenie żądania strumienia

Utwórz funkcję createStreamRequest, aby utworzyć strumień podający dane na podstawie żądania załadowania 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 customData = castRequest.media.customData;
      let streamRequest;
      if (customData.daiStreamType == "LIVE") {
        streamRequest = new google.ima.cast.dai.api.PodStreamRequest();
        streamRequest.customAssetKey = customData.customAssetKey;
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      } else if (customData.daiStreamType == "VOD") {
        streamRequest = new google.ima.cast.dai.api.PodVodStreamRequest();
        streamRequest.networkCode = customData.networkCode;
        streamRequest.apiKey = customData.apiKey;
      }
      return streamRequest;
    };

Pobieranie zszytego pliku manifestu z VTP

Jeśli żądanie transmisji zostanie zrealizowane, użyj streamManager.getStreamId(), aby pobrać identyfikator transmisji. Twój techniczny partner ds. wideo lub niestandardowy manipulator pliku manifestu poda Ci instrukcje pobierania adresu URL pliku manifestu za pomocą tego identyfikatora strumienia.

Po pobraniu adresu URL pliku manifestu zastąp dotychczasowy adres contentUrl nowym adresem manifestUrl.

Na koniec, zanim zwrócisz zmodyfikowany plik manifestu strumienia, wywołaj metodę loadStreamMetadata w streamManager, aby poinformować pakiet IMA SDK, że może bezpiecznie żądać metadanych strumienia. Ten krok jest konieczny tylko w przypadku strumieni VOD.

    /**
     * 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.');

            // This is a sample VTP integration. Consult your VTP documentation
            // for how to retrieve an ad-stitched stream manifest URL.
            const manifestTemplate = "https://.../manifest.m3u8?gam_stream_id=[[STREAMID]]";
            const streamId = streamManager.getStreamId();
            const manifestUrl = manifestTemplate.replace('[[STREAMID]]', streamId)
            // Assign your manifestUrl to the request's content URL.
            castRequestWithPodStreamData.media.contentUrl = manifestUrl;

            // After generating the manifest URL, VOD streams must notify the
            // IMA SDK that it is safe to request ad pod metadata.
            // This is only necessary for VOD streams. It is a no-op for
            // livestreams, so no conditional is needed.
            streamManager.loadStreamMetadata();

            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 wysyłać żądania strumieni z wyświetlaniem bloków reklamowych i odtwarzać je za pomocą interfejsu Cast Application Framework i pakietu IMA DAI SDK dla CAF.