Utiliser le SDK IMA DAI sur Chromecast

Lire des flux VOD enregistrés avec l'API Google Cloud Video Stitcher

Ce guide explique comment utiliser le SDK IMA DAI pour les récepteurs Web CAF afin de demander et de lire une session de streaming VOD Google Cloud.

Ce guide complète l'exemple de base de la publicité in-stream avec service complet en ajoutant la prise en charge des flux enregistrés avec l'API Google Cloud Video Stitcher.

Avant de continuer, assurez-vous que votre format de streaming est compatible avec les récepteurs Web CAF.

Pour en savoir plus sur l'intégration à d'autres plates-formes ou sur l'utilisation des SDK côté client IMA, consultez la page SDK Interactive Media Ads.

Contexte

Avant d'utiliser ce guide, familiarisez-vous avec le protocole Web Receiver du Chromecast Application Framework.

Ce guide suppose que vous connaissez les concepts de base des récepteurs CAF, tels que les intercepteurs de messages, les objets MediaInformation et l'utilisation de l'outil de commande et de contrôle Cast pour émuler un émetteur CAF.

Composants et architecture de l'application

L'implémentation de la lecture de flux VOD avec l'API Google Cloud Video Stitcher avec le SDK IMA CAF DAI implique deux composants principaux, comme indiqué dans ce guide:

  • VideoStitcherVodStreamRequest : objet qui définit une requête de flux vers les serveurs de Google.
  • StreamManager : objet qui gère la communication entre le flux vidéo et le SDK IMA DAI, par exemple en déclenchant des pings de suivi et en transmettant des événements de flux à l'éditeur.

Configurer un projet Google Cloud

Saisissez les variables suivantes à utiliser dans le SDK IMA:

Configurer un récepteur de cast personnalisé

Pour développer un récepteur de diffusion personnalisé, vous avez besoin des éléments suivants:

Préparer un expéditeur à transmettre des données de flux au destinataire

Commencez par configurer votre application d'envoi pour qu'elle envoie une requête de chargement à votre récepteur Web, contenant les champs suivants dans l'objet MediaInformation de votre plate-forme.

Champ Sommaire
contentId Identifiant unique de cet élément multimédia, tel que défini dans la documentation de référence sur Cast. Cet ID ne doit pas être réutilisé pour plusieurs éléments de la même file d'attente multimédia.

CONTENT_ID
contentUrl URL facultative du flux de sauvegarde à lire si le flux DAI ne parvient pas à se charger.

BACKUP_STREAM_URL
contentType Mimetype facultatif de l'URL du flux de secours à lire si le flux DAI ne parvient pas à se charger.

BACKUP_STREAM_MIMETYPE
streamType Le littéral de chaîne ou la constante utilisée pour cette valeur varie selon la plate-forme d'envoi.

VOD
customData

Le champ customData contient un magasin de clés-valeurs de champs obligatoires supplémentaires. Dans ce cas, customData contient les données de flux DAI que vous avez collectées.

Champ Sommaire
region LOCATION
projectNumber PROJECT_NUMBER
oAuthToken OAUTH_TOKEN
networkCode NETWORK_CODE
vodConfigId VOD_CONFIG_ID

Voici quelques exemples de code pour vous aider à vous lancer:

Web

Pour configurer ces valeurs dans un émetteur Web Cast, créez d'abord un objet MediaInfo avec les données requises, puis envoyez une requête de chargement au récepteur Web.

// Create mediaInfo object
const mediaInfo = new chrome.cast.media.MediaInfo("CONTENT_ID");
mediaInfo.contentUrl = "BACKUP_STREAM_URL";
mediaInfo.contentType = "BACKUP_STREAM_MIMETYPE";
mediaInfo.streamType = chrome.cast.media.StreamType.VOD;
mediaInfo.customData = {
  region: "LOCATION",
  projectNumber: "PROJECT_NUMBER",
  oAuthToken: "OAUTH_TOKEN",
  networkCode: "NETWORK_CODE",
  vodConfigId: "VOD_CONFIG_ID"
};

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

Pour configurer ces valeurs dans un émetteur Web Cast, créez d'abord un objet MediaInfo avec les données requises, puis envoyez une requête de chargement au récepteur Web.

JSONObject customData = new JSONObject()
  .put("region", "LOCATION")
  .put("projectNumber", "PROJECT_NUMBER")
  .put("oAuthToken", "OAUTH_TOKEN")
  .put("networkCode", "NETWORK_CODE")
  .put("vodConfigId", "VOD_CONFIG_ID");

MediaInfo mediaInfo = MediaInfo.Builder("CONTENT_ID")
  .setContentUrl("BACKUP_STREAM_URL")
  .setContentType("BACKUP_STREAM_MIMETYPE")
  .setStreamType(MediaInfo.STREAM_TYPE_VOD)
  .setCustomData(customData)
  .build();

RemoteMediaClient remoteMediaClient = mCastSession.getRemoteMediaClient();
remoteMediaClient.load(new MediaLoadRequestData.Builder().setMediaInfo(mediaInfo).build());

iOS (Obj-C)

Pour configurer ces valeurs dans un émetteur Web Cast, créez d'abord un objet GCKMediaInformation avec les données requises, puis envoyez une requête de chargement au récepteur Web.

NSURL url = [NSURL URLWithString:@"BACKUP_STREAM_URL"];
NSDictionary *customData = @{
  @"region": @"LOCATION",
  @"projectNumber": @"PROJECT_NUMBER",
  @"oAuthToken": @"OAUTH_TOKEN",
  @"networkCode": @"NETWORK_CODE",
  @"vodConfigId": @"VOD_CONFIG_ID"
};

GCKMediaInformationBuilder *mediaInfoBuilder =
  [[GCKMediaInformationBuilder alloc] initWithContentID: @"CONTENT_ID"];
mediaInfoBuilder.contentURL = url;
mediaInfoBuilder.contentType = @"BACKUP_STREAM_MIMETYPE";
mediaInfoBuilder.streamType = GCKMediaStreamTypeNone;
mediaInfoBuilder.customData = customData;
self.mediaInformation = [mediaInfoBuilder build];

GCKRequest *request = [self.sessionManager.currentSession.remoteMediaClient loadMedia:self.mediaInformation];
if (request != nil) {
  request.delegate = self;
}

iOS (Swift)

Pour configurer ces valeurs dans un émetteur Web Cast, créez d'abord un objet GCKMediaInformation avec les données requises, puis envoyez une requête de chargement au récepteur Web.

let url = URL.init(string: "BACKUP_STREAM_URL")
guard let mediaURL = url else {
  print("invalid mediaURL")
  return
}

let customData = [
  "region": "LOCATION",
  "projectNumber": "PROJECT_NUMBER",
  "oAuthToken": "OAUTH_TOKEN",
  "networkCode": "NETWORK_CODE",
  "vodConfigId": "VOD_CONFIG_ID"
]

let mediaInfoBuilder = GCKMediaInformationBuilder.init(contentId: "CONTENT_ID")
mediaInfoBuilder.contentURL = mediaUrl
mediaInfoBuilder.contentType = "BACKUP_STREAM_MIMETYPE"
mediaInfoBuilder.streamType = GCKMediaStreamType.none
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
}

Outil CAC

Pour configurer ces valeurs dans l'outil de commande et de contrôle de la diffusion, cliquez sur l'onglet "Charger des contenus multimédias", puis définissez le type de requête de chargement personnalisée sur LOAD. Remplacez ensuite les données JSON dans la zone de texte par ce code JSON:

{
  "media": {
    "contentId": "CONTENT_ID",
    "contentUrl": "BACKUP_STREAM_URL",
    "contentType": "BACKUP_STREAM_MIMETYPE",
    "streamType": "VOD",
    "customData": {
      "region": "LOCATION",
      "projectNumber": "PROJECT_NUMBER",
      "oAuthToken": "OAUTH_TOKEN",
      "networkCode": "NETWORK_CODE",
      "vodConfigId": "VOD_CONFIG_ID"
    }
  }
}

Cette requête de charge personnalisée peut être envoyée au destinataire pour tester le reste des étapes.

Créer un récepteur Web CAF personnalisé

Créez un récepteur Web personnalisé, comme indiqué dans le Guide du récepteur Web personnalisé du SDK CAF.

Le code du destinataire doit se présenter comme suit:

<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>
    const castContext = cast.framework.CastReceiverContext.getInstance()
    castContext.start();
  </script>
</body>
</html>

Importer le SDK IMA DAI et obtenir le Player Manager

Ajoutez une balise de script pour importer le SDK IMA DAI pour CAF dans votre récepteur Web, juste après le chargement du script CAF. Ensuite, dans la balise de script qui suit, stockez le contexte du récepteur et le gestionnaire de lecteurs en tant que constantes avant de démarrer le récepteur.

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

Initialiser le gestionnaire de flux IMA

Initialisez le gestionnaire de flux 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>

Créer l'intercepteur de charge du gestionnaire de flux

Avant que vos éléments multimédias ne soient transmis à CAF, créez votre requête de flux dans un intercepteur de message LOAD.

    const castContext = cast.framework.CastReceiverContext.getInstance();
    const playerManager = castContext.getPlayerManager();
    const streamManager = new google.ima.cast.dai.api.StreamManager();

    /**
     * Creates a VOD stream request object for the Video Stitcher API.
     * @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((castRequestWithStreamData) => {
            console.log('Successfully made DAI stream request.');
            return castRequestWithStreamData;
          })
          .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();

Créer la requête de flux

Terminez la fonction createStreamRequest pour créer une requête de flux VOD de l'API Video Stitcher, basée sur la requête de chargement CAF.

    /**
     * Creates a VOD stream request object for the Video Stitcher API.
     * @param {!LoadRequestData} castRequest The request object from the cast sender
     * @return {StreamRequest} an IMA stream request
     */
    const createStreamRequest = (castRequest) => {
      const streamRequest = new google.ima.cast.dai.api.VideoStitcherVodStreamRequest();
      const customData = castRequest.media.customData;

      streamRequest.region = customData.region;
      streamRequest.projectNumber = customData.projectNumber;
      streamRequest.oAuthToken = customData.oAuthToken;
      streamRequest.networkCode = customData.networkCode;
      streamRequest.vodConfigId = customData.vodConfigId;
      streamRequest.videoStitcherSessionOptions = {};

      return streamRequest;
    };

(Facultatif) Ajouter des options de session de streaming

Personnalisez votre requête de flux en ajoutant des options de session pour remplacer la configuration par défaut de l'API Cloud Video Stitcher à l'aide de VideoStitcherVodStreamRequest.videoStitcherSessionOptions. Si vous fournissez une option non reconnue, l'API Cloud Video Stitcher répondra par une erreur HTTP 400. Pour obtenir de l'aide, consultez le guide de dépannage.

Par exemple, vous pouvez remplacer les options de fichier manifeste avec l'extrait de code suivant, qui demande deux fichiers manifestes de flux avec des rendus triés du débit le plus bas au plus élevé.

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);
Précédent
Android
Suivant
HTML5