Configurare l'SDK IMA per DAI

Seleziona la soluzione DAI che ti interessa

DAI con pubblicazione di pod

Gli SDK IMA semplificano l'integrazione di annunci multimediali nei tuoi siti web e nelle tue app.

Gli SDK IMA possono richiedere annunci da qualsiasi ad server compatibile con VAST e gestire la riproduzione degli annunci nelle tue app.

Con gli SDK IMA DAI, le app effettuano una richiesta di stream per l'annuncio e il video dei contenuti per i contenuti VOD o live. L'SDK restituisce quindi uno stream video combinato, in modo da non dover gestire il passaggio tra l'annuncio e il video di contenuti all'interno dell'app.

Questa guida mostra come riprodurre uno stream di pubblicazione di pod DAI utilizzando l'SDK IMA DAI per CAF.

Prima di utilizzare questa guida, acquisisci familiarità con il protocollo Web Receiver del framework dell'applicazione Chromecast. Questa guida presuppone una conoscenza di base dei concetti del ricevitore CAF, come gli intercettori di messaggi e gli oggetti mediaInformation, nonché familiarità con l'utilizzo dello strumento di controllo e comando di Cast, per emulare un mittente CAF.

Per utilizzare la pubblicazione di pod DAI di IMA, devi collaborare con un partner di pubblicazione di pod e disporre di un account Ad Manager 360 Advanced. Se hai un account Ad Manager, contatta il tuo account manager per maggiori dettagli. Per informazioni sulla registrazione ad Ad Manager, visita il Centro assistenza Ad Manager.

Per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK lato client IMA, consulta SDK Interactive Media Ads.

Panoramica della pubblicazione di pod DAI di IMA

L'implementazione della pubblicazione di pod utilizzando l'SDK IMA CAF DAI prevede due componenti principali, che vengono illustrati in questa guida:

  • StreamRequest: Un oggetto che definisce una richiesta di stream ai server pubblicitari di Google. Le richieste specificano un codice di rete, una chiave dell'asset personalizzato e una chiave API facoltativa, nonché altri parametri facoltativi.
  • StreamManager: Un oggetto che gestisce la comunicazione tra lo stream video e l'SDK IMA DAI, ad esempio l'invio di ping di monitoraggio e l'inoltro degli eventi di stream al publisher.

Prerequisiti

Configurare gli oggetti MediaInfo del mittente

Innanzitutto, configura l'oggetto MediaInfo dell'app mittente in modo che includa i seguenti campi:

Campo Sommario
contentId Un identificatore univoco per questo elemento multimediale.

CONTENT_ID
contentUrl (Facoltativo) URL dello stream di backup da riprodurre se lo stream DAI non viene caricato.

BACKUP_STREAM_URL

contentType (Facoltativo) Tipo MIME degli stream di backup dei contenuti. Necessario solo per gli stream DASH.

CONTENT_STREAM_MIMETYPE
streamType Il valore letterale stringa o la costante utilizzata per questo valore varia in base alla piattaforma del mittente.
customData Il campo customData contiene un archivio chiave-valore di altri campi obbligatori. In questo esempio, contiene i parametri dello stream DAI. In un'app di produzione potresti invece passare un identificatore che la tua app ricevitore Cast utilizzerebbe per recuperare questi parametri con una richiesta lato server.
Campo Sommario
daiStreamType Il tipo di stream DAI. Uno tra "LIVE" o "VOD"

DAI_STREAM_TYPE
networkCode Il codice di rete del tuo account Google Ad Manager 360.

NETWORK_CODE
customAssetKey Questo campo è necessario solo per i live streaming. La chiave asset personalizzata che identifica l'evento di pubblicazione di pod in Google Ad Manager 360.

CUSTOM_ASSET_KEY
apiKey Una chiave API facoltativa per recuperare un ID stream dall'SDK IMA DAI.

API_KEY

Ecco alcuni esempi di codice per aiutarti a iniziare:

Web

Per configurare questi valori in un mittente web Cast, crea prima un oggetto MediaInfo con i dati richiesti, quindi invia una richiesta di caricamento al web receiver.

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

Per configurare questi valori in un mittente web Cast, crea prima un oggetto MediaInfo con i dati richiesti, quindi effettua una richiesta di caricamento al ricevitore web.

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)

Per configurare questi valori in un mittente web Cast, crea prima un oggetto GCKMediaInformation con i dati richiesti, quindi invia una richiesta di caricamento al web receiver.

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)

Per configurare questi valori in un mittente web Cast, crea prima un oggetto GCKMediaInformation con i dati richiesti, quindi invia una richiesta di caricamento al web receiver.

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
}

Strumento CAC

Per configurare questi valori nello strumento di controllo e comando di trasmissione, fai clic sulla scheda Carica contenuti multimediali e imposta il tipo di richiesta di caricamento personalizzata su LOAD. Quindi, sostituisci i dati JSON nell'area di testo con questo 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"
    }
  }
}

Questa richiesta di caricamento personalizzata può essere inviata al destinatario per testare il resto dei passaggi.

Crea un ricevitore CAF di base

Crea un ricevitore web personalizzato, come descritto nella guida all'SDK CAF Custom Web Receiver.

Il codice del destinatario dovrebbe avere il seguente aspetto:

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

Importa l'SDK IMA DAI e ottieni Player Manager

Aggiungi un tag script per importare l'SDK IMA DAI per CAF nel ricevitore web, subito dopo il caricamento dello script CAF. Nel tag script, memorizza il contesto del ricevitore e il gestore del player come costanti prima di avviare il ricevitore.

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

Inizializzare IMA Stream Manager

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

Crea l'intercettatore di caricamento di Stream Manager

Prima che gli elementi multimediali vengano passati a CAF, crea la richiesta di flusso in un intercettore di messaggi 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();

Crea la richiesta di stream

Completa la funzione createStreamRequest per creare uno stream di pubblicazione di pod in base alla richiesta di caricamento del 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;
    };

Recupera il file manifest unito dal tuo VTP

Se la richiesta di stream va a buon fine, utilizza streamManager.getStreamId() per recuperare l'ID dello stream. Il tuo partner tecnico per i video (VTP) o il manipolatore di manifest personalizzati fornirà le istruzioni per recuperare un URL manifest utilizzando questo ID stream.

Una volta recuperato l'URL del file manifest, sostituisci contentUrl esistente con il nuovo manifestUrl.

Infine, prima di restituire il manifest dello stream modificato, chiama il metodo loadStreamMetadata sul tuo streamManager per comunicare all'SDK IMA che può richiedere in sicurezza i metadati dello stream. Questa chiamata è necessaria solo per gli stream 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;
          });
    };

Pulire gli asset IMA DAI

Una volta completata la richiesta e la visualizzazione degli annunci in uno stream di pubblicazione di pod con l'SDK IMA DAI, ti consigliamo di eliminare tutte le risorse al termine della sessione di pubblicazione di pod. Chiama StreamManager.destroy() per interrompere la riproduzione dello stream, interrompere il monitoraggio di tutti gli annunci e rilasciare tutti gli asset dello stream caricati.