Konfigurowanie pakietu IMA SDK na potrzeby DAI

Wybierz platformę: HTML5 Android iOS tvOS Cast Roku

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

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

Pakiety IMA SDK ułatwiają integrowanie 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 w przypadku treści 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ścią wideo w aplikacji.

Z tego przewodnika dowiesz się, jak odtwarzać strumień wyświetlany przez DAI Pod Serving przy użyciu pakietu IMA DAI SDK na platformie CAF.

Zanim zaczniesz korzystać z tego przewodnika, zapoznaj się z protokołem Web Receiver w ramach aplikacji Chromecast. W tym przewodniku zakłada się podstawową znajomość pojęć związanych z odbiornikiem CAF, takich jak interfejsy przechwytujące wiadomości i obiekty mediaInformation, oraz umiejętność korzystania z narzędzia Cast Command and Control do emulowania nadawcy CAF.

Aby korzystać z wyświetlania bloków reklamowych w ramach IMA DAI, musisz współpracować z partnerem w zakresie wyświetlania bloków reklamowych i 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.

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

Omówienie wyświetlania bloków reklamowych w ramach dynamicznego wstawiania reklam w pakiecie IMA DAI

Wdrożenie wyświetlania bloków reklamowych za pomocą pakietu IMA CAF DAI SDK obejmuje 2 główne komponenty, które zostały przedstawione w tym przewodniku:

  • StreamRequest: Obiekt, który definiuje żądanie strumienia wysyłane do serwerów reklamowych Google. Żądania określają kod sieci, niestandardowy klucz zasobu i opcjonalny klucz interfejsu API, a także inne opcjonalne parametry.
  • StreamManager: obiekt, który obsługuje komunikację między strumieniem wideo a pakietem IMA DAI SDK, np. wysyła pingi śledzące i przekazuje zdarzenia strumienia do wydawcy.

Wymagania wstępne

Konfigurowanie obiektów MediaInfo nadawcy

Najpierw skonfiguruj obiekt MediaInfo aplikacji wysyłającej, aby zawierał te pola:

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

CONTENT_ID
contentUrl Opcjonalnie: Zapasowy adres URL transmisji, który ma być odtwarzany, jeśli nie uda się wczytać transmisji DAI.

BACKUP_STREAM_URL

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

CONTENT_STREAM_MIMETYPE
streamType Ciąg znaków lub stała używane w przypadku tej wartości różnią się w zależności od platformy nadawcy.
customData Pole customData zawiera magazyn klucz-wartość z dodatkowymi wymaganymi polami. W tym przykładzie zawiera on parametry strumienia DAI. W aplikacji produkcyjnej możesz zamiast tego przekazać identyfikator, którego aplikacja odbiornika Cast użyje do pobrania tych parametrów za pomocą żądania po stronie serwera.
Pole Spis treści
daiStreamType Typ strumienia DAI. Może to być "LIVE" lub "VOD"

DAI_STREAM_TYPE
networkCode Kod sieci na potrzeby konta Google Ad Managera 360.

NETWORK_CODE
customAssetKey To pole jest wymagane tylko w przypadku transmisji na żywo. Niestandardowy klucz pliku, który identyfikuje zdarzenie wyświetlania zasobów 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ładowych fragmentów kodu, które pomogą Ci zacząć:

Sieć

Aby skonfigurować te wartości w nadawcy internetowym Cast, najpierw utwórz obiekt MediaInfo zawierający wymagane dane, 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 = {
  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 nadawcy internetowym Cast, najpierw utwórz obiekt MediaInfo z wymaganymi danymi, a następnie wyś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 (Obj-C)

Aby skonfigurować te wartości w nadawcy internetowym Cast, najpierw utwórz obiekt GCKMediaInformation zawierający wymagane dane, a potem wyślij do odbiornika internetowego żądanie wczytania.

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 nadawcy internetowym Cast, najpierw utwórz obiekt GCKMediaInformation zawierający wymagane dane, 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 = [
  "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ę Wczytaj media i ustaw typ niestandardowego żądania wczytania na LOAD. 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": {
      "daiStreamType": "DAI_STREAM_TYPE",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

To niestandardowe żądanie wczytania 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 po niestandardowym odbiorniku internetowym w pakiecie 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 odtwarzacza

Dodaj tag skryptu, aby zaimportować IMA DAI SDK dla CAF do odbiornika internetowego, tuż po załadowaniu skryptu CAF. W tagu skryptu zapisz kontekst odbiornika i menedżera odtwarzacza jako stałe wartości 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 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 interfejsu Stream Manager Load Interceptor

Zanim elementy multimedialne zostaną przekazane do CAF, utwórz żądanie strumienia w przechwytywaczu wiadomości 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();

Tworzenie żądania strumienia

Uzupełnij funkcję createStreamRequest, aby utworzyć strumień wyświetlania bloków reklamowych na podstawie żądania wczytania 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;
    };

Pobierz połączony plik manifestu z platformy VTP.

Jeśli prośba o strumień zostanie rozpatrzona pozytywnie, użyj streamManager.getStreamId(), aby pobrać identyfikator strumienia. Twój partner techniczny ds. wideo (VTP) lub manipulator niestandardowego pliku manifestu poda instrukcje pobierania adresu URL pliku manifestu za pomocą tego identyfikatora strumienia.

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

Na koniec, przed zwróceniem zmodyfikowanego manifestu strumienia, wywołaj metodę loadStreamMetadata w obiekcie streamManager , aby poinformować pakiet IMA SDK, że może bezpiecznie wysłać żądanie metadanych strumienia. To wywołanie jest konieczne 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;
          });
    };

Zwalnianie miejsca na potrzeby komponentów IMA DAI

Gdy skończysz wysyłać żądania reklam i wyświetlać je w strumieniu Pod Serving za pomocą pakietu IMA DAI SDK, zalecamy zwolnienie miejsca po zakończeniu sesji Pod Serving. Wywołaj funkcję StreamManager.destroy(), aby zatrzymać odtwarzanie strumienia, śledzenie reklam i zwolnić wszystkie załadowane komponenty strumienia.