Einführung in das IMA DAI SDK

Wählen Sie die gewünschte dynamische Anzeigenbereitstellungslösung aus.

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung

Mit IMA SDKs können Sie Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden.

IMA SDKs können Anzeigen von jedem VAST-kompatiblen Ad-Server anfordern und die Anzeigenwiedergabe in Ihren Apps verwalten.

Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Videocontent für VOD- oder Livecontent. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie nicht zwischen Anzeigen- und Inhaltsvideo in Ihrer App wechseln müssen.

In dieser Anleitung wird gezeigt, wie du einen DAI-Pod-Auslieferungsstream mit dem IMA DAI SDK für CAF abspielst.

Bevor du diesen Leitfaden verwendest, solltest du dich mit dem Web-Empfängerprotokoll des Chromecast Application Framework vertraut machen. In diesem Leitfaden werden grundlegende Kenntnisse der CAF-Empfängerkonzepte wie Nachrichten-Interceptor und mediaInformation vorausgesetzt. Außerdem solltest du mit der Verwendung des Cast Command and Control-Tools vertraut sein, um einen CAF-Sender zu emulieren.

Wenn Sie die Pod-Auslieferung mit dynamischer Anzeigenbereitstellung von IMA verwenden möchten, müssen Sie mit einem Pod-Auslieferungspartner zusammenarbeiten und ein Ad Manager 360 Advanced-Konto haben. Wenn Sie ein Ad Manager-Konto haben, wenden Sie sich an Ihren Account Manager, um weitere Informationen zu erhalten. Informationen zur Registrierung für Ad Manager finden Sie in der Ad Manager-Hilfe.

Informationen zur Einbindung in andere Plattformen oder zur Verwendung der clientseitigen IMA SDKs finden Sie unter Interactive Media Ads SDKs.

IMA DAI Pod Serving – Übersicht

Die Implementierung des Pod-Auslieferungssystems mit dem IMA CAF DAI SDK umfasst zwei Hauptkomponenten, die in diesem Leitfaden erläutert werden:

• StreamRequest: Ein Objekt, das eine Streamanfrage an die Werbeserver von Google definiert. Anfragen müssen einen Netzwerkcode, einen benutzerdefinierten Asset-Schlüssel und einen optionalen API-Schlüssel sowie andere optionale Parameter enthalten.
• StreamManager: Ein Objekt, das die Kommunikation zwischen dem Videostream und dem IMA DAI SDK verwaltet, z. B. das Auslösen von Tracking-Pings und das Weiterleiten von Stream-Ereignissen an den Publisher.

Vorbereitung

• Ein Cast Developer Console-Konto mit registrierten Testgeräten.
• Eine gehostete Webreceiver-App, die in der Cast Developer Console registriert ist und so geändert werden kann, dass der in diesem Leitfaden bereitgestellte Code gehostet wird.
• Eine Sender-App, die für die Verwendung deiner Web-Empfänger-App konfiguriert ist. Verwende für dieses Beispiel das Cast Command and Control-Tool als Sender.

MediaInfo-Objekte des Senders konfigurieren

Konfigurieren Sie zuerst das MediaInfo-Objekt Ihrer Absender-App so, dass die folgenden Felder enthalten sind:

Hier sind einige Codebeispiele für den Einstieg:

// 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); });

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

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;
}

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
}

{
  "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"
    }
  }
}

Diese benutzerdefinierte Ladeanfrage kann an den Empfänger gesendet werden, um die restlichen Schritte zu testen.

Einfachen CAF-Empfänger erstellen

Erstelle einen benutzerdefinierten Webreceiver, wie im Leitfaden für benutzerdefinierte Webreceiver des CAF SDK beschrieben.

Der Code deines Empfängers sollte so aussehen:

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

IMA DAI SDK importieren und Player Manager abrufen

Füge ein Script-Tag hinzu, um das IMA DAI SDK für CAF in deinen Webreceiver zu importieren, kurz nachdem das Script CAF geladen hat. Speichere den Empfängerkontext und den Player-Manager im Script-Tag als Konstanten, bevor du den Empfänger startest.

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

IMA Stream Manager initialisieren

Initialisiere den IMA Stream Manager.

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

Stream Manager Load Interceptor erstellen

Bevor deine Medienelemente an CAF übergeben werden, erstelle deine Streamanfrage in einem LOAD-Nachrichten-Interceptor.

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

Streamanfrage erstellen

Schließe die createStreamRequest-Funktion ab, um einen Pod-Auslieferungsstream basierend auf der CAF-Ladeanfrage zu erstellen.

    /**
     * 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;
    };

Zusammengeführtes Manifest aus deinem VTP abrufen

Wenn die Streamanfrage erfolgreich war, kannst du mit streamManager.getStreamId() die ID des Streams abrufen. Dein VTP oder benutzerdefinierter Manifest-Manipulator stellt eine Anleitung zum Abrufen einer Manifest-URL mit dieser Stream-ID bereit.

Nachdem Sie die Manifest-URL abgerufen haben, ersetzen Sie die vorhandene contentUrl durch die neue manifestUrl.

Bevor du das geänderte Stream-Manifest zurückgibst, musst du die Methode loadStreamMetadata auf deiner streamManager aufrufen, um das IMA SDK darüber zu informieren, dass es sicher Stream-Metadaten anfordern kann. Dieser Aufruf ist nur für VOD-Streams erforderlich.

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

Du kannst jetzt Streams mit Pod-Auslieferung mit dem Cast Application Framework und dem IMA DAI SDK für CAF anfordern und wiedergeben.