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 des contenus en direct ou de 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'asset personnalisée 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

• Un compte Console développeur Cast avec des appareils de test enregistrés.
• Une application de récepteur Web hébergée enregistrée dans votre console développeur Cast et pouvant être modifiée pour héberger le code fourni dans ce guide.
• Une application d'envoi configurée pour utiliser votre application de récepteur Web. Pour les besoins de cet exemple, utilisez l'outil de commande et de contrôle Cast comme expéditeur.

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:

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

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

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

Vous pouvez désormais demander et lire des flux de diffusion de séries d'annonces avec le Cast Application Framework et le SDK IMA DAI pour CAF.