Iniziare a utilizzare l'SDK IMA DAI

Seleziona la soluzione DAI che ti interessa

Servizio completo Pubblicazione di pod

Pubblicazione di pod DAI

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

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

Con gli SDK DAI IMA, le app inviano una richiesta di streaming per gli annunci e i video di contenuti per contenuti VOD o dal vivo. L'SDK restituisce quindi uno stream video combinato, in modo che non debba gestire il passaggio dall'annuncio al video di contenuti all'interno della tua app.

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

Nota: l'SDK IMA DAI per CAF supporta sia gli stream HLS che quelli DASH, senza differenze di implementazione.

Prima di utilizzare questa guida, acquisisci familiarità con il protocollo del Web Receiver di Chromecast Application Framework. Questa guida presuppone una conoscenza di base dei concetti relativi ai ricevitori CAF, come gli intercettatori di messaggi e gli oggetti mediaInformation, nonché la familiarità con l'utilizzo dello strumento di controllo e comando di trasmissione per emulare un mittente CAF.

Per utilizzare la pubblicazione di pod DAI IMA, devi collaborare con un partner per la pubblicazione di pod e avere un account Ad Manager 360 Advanced. Se hai un account Ad Manager, contatta il tuo account manager per maggiori dettagli. Per informazioni su come registrarti 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 IMA

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

• StreamRequest: un oggetto che definisce una richiesta di stream ai server pubblicitari di Google. Le richieste specificano un codice rete, una chiave asset personalizzata 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 di eventi stream al publisher.

Prerequisiti

• Un account Cast Developer Console con dispositivi di test registrati.
• Un'app di ricezione web ospitata registrata nella tua Cast Developer Console e che può essere modificata per ospitare il codice fornito da questa guida.
• Un'app di invio configurata per utilizzare l'app di ricezione web. Ai fini di questo esempio, utilizza lo strumento di controllo e comando di trasmissione come mittente.

Configura gli oggetti MediaInfo del mittente

Innanzitutto, configura l'oggetto MediaInfo della tua app mittente in modo da includere 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 riesce a caricarsi. BACKUP_STREAM_URL
contentType	Facoltativo. Tipo MIME degli stream di backup dei contenuti. Obbligatorio solo per gli streaming DASH. CONTENT_STREAM_MIMETYPE
streamType	La stringa letterale o la costante utilizzata per questo valore varia in base alla piattaforma di invio.
customData	Il campo customData contiene un archivio chiave-valore di campi obbligatori aggiuntivi. In questo esempio, contiene i parametri dello stream DAI. In un'app di produzione, puoi invece passare un identificatore che verrà utilizzato dall'app di ricezione del cast per recuperare questi parametri con una richiesta lato server. Campo Sommario daiStreamType Il tipo di stream DAI. Uno dei seguenti valori: "LIVE" o "VOD" DAI_STREAM_TYPE networkCode Il codice di rete per il tuo account Google Ad Manager 360. NETWORK_CODE customAssetKey Questo campo è necessario solo per i live streaming. La chiave dell'asset personalizzato che identifica l'evento di pubblicazione del pod in Google Ad Manager 360. CUSTOM_ASSET_KEY apiKey Una chiave API facoltativa per recuperare un ID stream dall'SDK DAI IMA. API_KEY

Ecco alcuni esempi di codice per aiutarti a iniziare:

Web

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

// 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 di trasmissione, crea innanzitutto un oggetto MediaInfo con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.MediaInfo

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 di trasmissione, crea innanzitutto un oggetto GCKMediaInformation con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.

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 di trasmissione, crea innanzitutto un oggetto GCKMediaInformation con i dati richiesti, quindi invia una richiesta di caricamento al ricevitore web.

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 comandi di trasmissione, fai clic sulla scheda Carica contenuti multimediali e imposta il tipo di richiesta di caricamento personalizzato 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 personalizzato può essere inviata al destinatario per testare il resto dei passaggi.

Creare un ricevitore CAF di base

Crea un ricevitore web personalizzato, come descritto nella guida sul ricevitore web personalizzato dell'SDK CAF.

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 DAI IMA e ottieni il gestore dei player

Aggiungi un tag script per importare l'SDK IMA DAI per CAF nel tuo ricevitore web, subito dopo il caricamento del CAF da parte dello script. 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>

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

Creare l'intercettatore del carico di Stream Manager

Prima che gli elementi multimediali vengano trasmessi a CAF, crea la richiesta di streaming in un intercettatore 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 manifest unito dal VTP

Se la richiesta di stream va a buon fine, utilizza streamManager.getStreamId() per recuperare l'ID dello stream. Il tuo Video Technical Partner (VTP) o il tuo manipolatore di manifest personalizzato ti fornirà le istruzioni per recuperare un URL manifest utilizzando questo ID stream.

Dopo aver recuperato l'URL del file manifest, sostituisci il valore contentUrl esistente con il nuovo manifestUrl.

Infine, prima di restituire il manifest dello stream modificato, chiama il metodo loadStreamMetadata sul tuo streamManager per informare l'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;
          });
    };

Ripulire gli asset DAI IMA

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