Premiers pas avec le SDK IMA DAI

Sélectionnez la solution de publicité display in-app qui vous intéresse.

Insertion dynamique de séries d'annonces

Les SDK IMA simplifient l'intégration d'annonces multimédias dans vos sites Web et applications.

Les SDK IMA peuvent demander des annonces à n'importe quel ad server conforme à la norme VAST et gérer la lecture des annonces dans vos applications.

Avec les SDK IMA DAI, les applications envoient une demande de flux pour les annonces et les vidéos de contenu, que ce soit pour du contenu en direct ou de la VOD. Le SDK renvoie ensuite un flux vidéo combiné, de sorte que vous n'ayez pas à gérer le basculement entre l'annonce et la vidéo du contenu dans votre application.

Ce guide explique comment lire un flux de diffusion de pod DAI à l'aide du SDK DAI IMA pour CAF.

Avant d'utiliser ce guide, familiarisez-vous avec le protocole Web Receiver du Chromecast Application Framework. Ce guide part du principe que vous maîtrisez les concepts de base des récepteurs CAF, tels que les intercepteurs de messages et les objets mediaInformation, et que vous savez utiliser l'outil de commande et de contrôle Cast pour émuler un émetteur CAF.

Pour utiliser l'insertion dynamique d'annonces IMA dans des séries d'annonces, vous devez travailler avec un partenaire de diffusion de séries d'annonces et disposer d'un compte Ad Manager 360 Advanced. Si vous possédez un compte Ad Manager, contactez votre responsable de compte pour en savoir plus. Pour savoir comment vous inscrire à Ad Manager, consultez le Centre d'aide Ad Manager.

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.

Présentation de l'insertion dynamique de séries d'annonces IMA

L'implémentation du service de diffusion de pods à l'aide du SDK DAI IMA CAF implique deux composants principaux, qui sont illustrés dans ce guide:

  • StreamRequest : objet qui définit une requête de flux vers les serveurs publicitaires de Google. Les requêtes spécifient un code réseau, une clé d'élément personnalisé et une clé API facultative, ainsi que d'autres paramètres facultatifs.
  • 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.

Prérequis

Configurer les objets MediaInfo de l'expéditeur

Commencez par configurer l'objet MediaInfo de votre application d'envoi afin d'inclure les champs suivants:

Champ Sommaire
contentId Identifiant unique de cet élément multimédia.

CONTENT_ID

contentUrl Facultatif. URL du flux de substitution à lire si le flux DAI ne parvient pas à se charger.

BACKUP_STREAM_URL

contentType Facultatif. Mimetype des flux de sauvegarde de contenu. Uniquement nécessaire pour les flux DASH.

CONTENT_STREAM_MIMETYPE

streamType Le littéral de chaîne ou la constante utilisée pour cette valeur varie selon la plate-forme d'envoi.
customData Le champ customData contient un magasin de clés-valeurs de champs obligatoires supplémentaires. Dans cet exemple, il contient vos paramètres de flux DAI. Dans une application de production, vous pouvez transmettre un identifiant que votre application de réception de diffusion utilisera pour récupérer ces paramètres avec une requête côté serveur.
Champ Sommaire
daiStreamType Type de votre flux DAI. "LIVE" ou "VOD"

DAI_STREAM_TYPE

networkCode Code de réseau de votre compte Google Ad Manager 360.

NETWORK_CODE

customAssetKey Ce champ n'est nécessaire que pour les diffusions en direct. Clé d'élément personnalisée qui identifie votre événement de diffusion de pod dans Google Ad Manager 360.

CUSTOM_ASSET_KEY

apiKey Clé API facultative pour récupérer un ID de flux à partir du SDK d'insertion dynamique d'annonce IMA.

API_KEY

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

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

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 = @{
  @"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)

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 = [
  "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
}

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é 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": ""CONTENT_STREAM_MIMETYPE"",
    "streamType": "LIVE",
    "customData": {
      "daiStreamType": "DAI_STREAM_TYPE",
      "networkCode": "NETWORK-CODE",
      "customAssetKey": "CUSTOM_ASSET_KEY",
      "oAuthToken": "API_KEY"
    }
  }
}

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

Créer un récepteur CAF de base

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>
    // ...
  </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. Dans la balise de script, stockez le contexte du récepteur et le gestionnaire de lecteur 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 messages 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();

Créer la requête de flux

Terminez la fonction createStreamRequest pour créer un flux de diffusion de pod basé sur la requête de chargement de 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;
    };

Récupérez le fichier manifeste assemblé à partir de votre VTP

Si votre requête de flux aboutit, utilisez streamManager.getStreamId() pour récupérer l'ID du flux. Votre partenaire technique vidéo (VTP) ou votre manipulateur de fichier manifeste personnalisé vous fournira des instructions pour récupérer une URL de fichier manifeste à l'aide de cet ID de flux.

Une fois que vous avez récupéré l'URL de votre fichier manifeste, remplacez l'contentUrl existante par la nouvelle manifestUrl.

Enfin, avant de renvoyer le fichier manifeste de flux modifié, appelez la méthode loadStreamMetadata sur votre streamManager pour informer le SDK IMA qu'il peut demander en toute sécurité les métadonnées du flux. Cet appel n'est nécessaire que pour les flux 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;
          });
    };

Nettoyer les composants d'insertion dynamique d'annonces IMA

Une fois que vous avez terminé de demander et d'afficher des annonces dans un flux de diffusion de séries avec le SDK DAI IMA, nous vous suggérons de nettoyer toutes les ressources une fois la session de diffusion de séries terminée. Appelez StreamManager.destroy() pour arrêter la lecture du flux, arrêter tout suivi des annonces et libérer tous les composants de flux chargés.