Konfigurowanie pakietu IMA SDK na potrzeby DAI

Wybierz interesujące Cię rozwiązanie DAI

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ą wysyłać żądania reklam do dowolnego serwera reklam zgodnego ze standardem 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 się między reklamą a treścią wideo w aplikacji.

Ten przewodnik pokazuje, jak odtwarzać strumień z wyświetlaniem bloków reklamowych z dynamicznym wstawianiem reklam za pomocą pakietu IMA DAI SDK dla CAF.

Zanim zaczniesz korzystać z tego przewodnika, zapoznaj się z protokołem Web Receiver w ramach aplikacji Chromecasta. Ten przewodnik zakłada 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 Manager 360 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.

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

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

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

  • StreamRequest: obiekt, który definiuje żądanie strumienia 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 MediaInfoobiekt aplikacji nadawcy, aby zawierał te pola:

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

CONTENT_ID
contentUrl Opcjonalnie. Zapasowy URL transmisji, która ma być odtwarzana, jeśli nie uda się załadować 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żywana w przypadku tej wartości różni się w zależności od platformy nadawcy.
customData Pole customData zawiera magazyn par klucz-wartość z dodatkowymi wymaganymi polami. W tym przykładzie zawiera 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 koncie 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 następnie 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 nadajniku 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 następnie 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 następnie 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ę Load Media (Wczytaj media) i ustaw typ niestandardowego żądania wczytania na LOAD. Następnie zastąp dane JSON w obszarze tekstowym tymi danymi:

{
  "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, jak pokazano 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ć do odbiornika internetowego pakiet IMA DAI SDK dla CAF, tuż po załadowaniu skryptu CAF. W tagu skryptu zapisz kontekst odbiorcy i menedżera odtwarzacza jako stałe przed uruchomieniem odbiorcy.

<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 narzędzia Stream Manager Load Interceptor

Zanim elementy multimedialne zostaną przekazane do CAF, utwórz żądanie transmisji w interceptorze 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 poda 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 lub niestandardowy manipulator pliku manifestu przekaże instrukcje pobierania adresu URL pliku manifestu za pomocą tego identyfikatora strumienia.

Po uzyskaniu adresu URL pliku manifestu zastąp istniejący ciąg contentUrl nowym ciągiem 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 wysyłać żądania 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;
          });
    };

Czyszczenie zasobów IMA DAI

Gdy skończysz wysyłać żądania reklam i wyświetlać je w strumieniu z wyświetlaniem bloków reklamowych za pomocą pakietu IMA DAI SDK, zalecamy usunięcie wszystkich zasobów po zakończeniu sesji wyświetlania bloków reklamowych. Wywołaj funkcję StreamManager.destroy(), aby zatrzymać odtwarzanie strumienia, śledzenie reklam i zwolnić wszystkie wczytane komponenty strumienia.