Préparer le client à la redirection de la diffusion de séries d'annonces

Ce guide explique comment développer une application cliente pour charger un flux en direct HLS ou DASH avec l'API de diffusion de séries d'annonces et votre outil de manipulation de fichier manifeste.

Prérequis

Avant de continuer, vous devez disposer des éléments suivants :

Envoyer une requête de flux

Lorsque l'utilisateur sélectionne un flux, procédez comme suit :

  1. Envoyez une requête POST à la méthode du service Livestream. Pour en savoir plus, consultez Méthode : stream.

  2. Transmettez les paramètres de ciblage des annonces aux formats application/x-www-form-urlencoded ou application/json. Cette requête enregistre une session de flux auprès de Google DAI.

    L'exemple suivant envoie une requête de flux :

    Encodage du formulaire

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
          `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
    
    const params = new URLSearchParams({
            cust_params: 'section=sports&page=golf,tennis'
    }).toString();
    
    const response = await fetch(url, {
            method: 'POST',
            headers: {
              'Content-Type': 'application/x-www-form-urlencoded'
            },
            body: params
    });
    
    console.log(await response.json());
    

    Encodage JSON

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
          `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;
    
    const response = await fetch(url, {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json'
            },
            body: JSON.stringify({
              cust_params: {
                section: 'sports',
                page: 'golf,tennis'
              }
            })
    });
    
    console.log(await response.json());
    

    Si l'opération réussit, un résultat semblable à celui-ci s'affiche :

    {
    "stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
    "media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
    "session_update_url": "https://dai.google.com/linear/.../session",
    "polling_frequency": 10
    }
    
  3. Dans la réponse JSON, recherchez l'ID de session du flux et stockez d'autres données pour les étapes suivantes.

Métadonnées des annonces de sondage

Pour interroger les métadonnées d'annonce, procédez comme suit :

  1. Lisez la valeur metadata_url à partir de la réponse d'enregistrement du flux.

  2. Envoyez une requête GET initiale au point de terminaison metadata_url.

    • Omettez le paramètre de requête delta_token. Ce processus permet au serveur de renvoyer les métadonnées complètes de la fenêtre de l'enregistreur vidéo numérique (DVR) du flux. La fenêtre DVR contient la période de la diffusion que le spectateur peut rembobiner et lire. La réponse inclut un champ next_delta_token.
  3. Pour optimiser la bande passante, stockez la valeur next_delta_token de la réponse la plus récente.

  4. Lors de votre prochaine requête, envoyez cette valeur en tant que paramètre de requête delta_token. Le serveur ne renvoie que les métadonnées qui ont changé depuis la génération de ce jeton. Envoyez toujours le dernier jeton que vous avez reçu. N'essayez pas d'analyser, de modifier ni de construire le jeton. Pour en savoir plus, consultez Méthode : metadata.

    L'exemple suivant récupère les métadonnées de l'annonce :

    // Initial request (returns full metadata and next_delta_token)
    let response = await fetch(metadata_url);
    let metadata = await response.json();
    let deltaToken = metadata.next_delta_token;
    
    // Subsequent request (returns only changes since deltaToken)
    if (deltaToken) {
      const url = new URL(metadata_url);
      url.searchParams.append('delta_token', deltaToken);
      response = await fetch(url.toString());
      const deltaMetadata = await response.json();
      // Merge deltaMetadata into your local cache
      mergeMetadata(metadata, deltaMetadata);
      deltaToken = deltaMetadata.next_delta_token;
    }
    

    Si l'opération réussit, vous recevez la réponse PodMetadata. Si vous fournissez le paramètre delta_token, la réponse ne contient que les annonces, les coupures publicitaires et les tags que le serveur a ajoutés ou mis à jour depuis qu'il a généré le jeton. La réponse contient également une nouvelle valeur next_delta_token. Si des coupures publicitaires sont obsolètes, la réponse inclut également une liste obsolete_ad_break_ids des coupures publicitaires à supprimer de votre cache.

    {
      "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
      "obsolete_ad_break_ids": ["0003069407"],
      "tags":{
        "google_1022389921":{
          "ad":"0003069408_ad1",
          "ad_break_id":"0003069408",
          "type":"start"
        },
        ...
      },
      "ads":{
        "0003069408_ad1":{
          "ad_break_id":"0003069408",
          "position":1,
          "duration":10.01,
          "title":"External - Pod Midroll 1",
          "clickthrough_url":"https://.../",
          ...
        },
        ...
      },
      "ad_breaks":{
        "0003069408":{
          "type":"mid",
          "duration":30,
          "ads":3
        },
        ...
      }
    }
    
  5. Enregistrez l'objet tags et fusionnez les mises à jour dans votre cache local. Si le paramètre obsolete_ad_break_ids est présent, supprimez ces coupures publicitaires ainsi que les annonces et les tags associés de votre cache.

  6. Définissez un minuteur à l'aide de la valeur polling_frequency pour demander régulièrement des métadonnées. Dans chaque interrogation, envoyez la valeur next_delta_token renvoyée dans la réponse de métadonnées la plus récente en tant que paramètre de requête delta_token.

Charger le flux dans votre lecteur vidéo

Une fois que vous avez obtenu l'ID de session à partir de la réponse d'enregistrement, transmettez-le à votre outil de manipulation de fichier manifeste ou créez une URL de fichier manifeste pour charger le flux dans un lecteur vidéo.

Pour transmettre l'ID de session, consultez la documentation de votre outil de manipulation de fichier manifeste. Si vous développez un outil de manipulation de fichier manifeste, consultez Outil de manipulation de fichier manifeste pour la diffusion en direct.

L'exemple suivant assemble une URL de fichier manifeste :

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

Lorsque votre lecteur est prêt, lancez la lecture.

Écouter les événements d'annonce

Vérifiez le format de conteneur de votre flux pour les métadonnées temporelles :

  • Les flux HLS avec des conteneurs Transport Stream (TS) utilisent des balises ID3 temporelles pour transporter des métadonnées temporelles. Pour en savoir plus, consultez À propos du format CMAF (Common Media Application Format) avec HTTP Live Streaming (HLS).

  • Les flux DASH utilisent des éléments EventStream pour spécifier des événements dans le fichier manifeste.

  • Les flux DASH utilisent des éléments InbandEventStream lorsque les segments contiennent des zones de message d'événement (emsg) pour les données de charge utile, y compris les tags ID3. Pour en savoir plus, consultez InbandEventStream.

  • Les flux CMAF, y compris DASH et HLS, utilisent des cases emsg contenant des tags ID3.

Pour récupérer les tags ID3 de votre flux, consultez le guide de votre lecteur vidéo. Pour en savoir plus, consultez le guide Gérer les métadonnées temporelles.

Pour récupérer l'ID d'événement d'annonce à partir des tags ID3, procédez comme suit :

  1. Filtrez les événements par scheme_id_uri avec urn:google:dai:2018 ou https://aomedia.org/emsg/ID3.
  2. Extrayez le tableau d'octets du champ message_data.

    L'exemple suivant décode les données emsg au format JSON :

    {
      "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
      "presentation_time": 27554,
      "timescale": 1000,
      "message_data": "ID3TXXXgoogle_1022389921",
      ...
    }
    
  3. Filtrez les tags ID3 au format TXXXgoogle_{ad_event_ID} :

    TXXXgoogle_1022389921
    

Afficher les données d'événement d'annonce

Pour trouver l'objet TagSegment, procédez comme suit :

  1. Récupérez l'objet de métadonnées d'annonce tags à partir de Interroger les métadonnées d'annonce. L'objet tags est un tableau d'objets TagSegment.

  2. Utilisez l'ID d'événement d'annonce complet pour trouver un objet TagSegment de type progress.

  3. Utilisez les 17 premiers caractères de l'ID d'événement d'annonce pour trouver un objet TagSegment d'autres types.

    Étant donné que votre application cliente interroge régulièrement les métadonnées d'annonce, un délai peut s'écouler entre le moment où votre lecteur vidéo rencontre un tag ID3 dans le flux et celui où les métadonnées associées sont disponibles. Si votre application cliente ne trouve pas de tag ID3 dans les tags stockés, conservez le tag dans une file d'attente et traitez-le à nouveau après l'interrogation suivante des métadonnées. Conservez la balise dans la file d'attente jusqu'à la fin du traitement.

  4. Une fois que vous disposez de TagSegment, utilisez la propriété ad_break_id comme clé pour trouver l'objet AdBreak dans l'objet ad_breaks des métadonnées de l'annonce.

    L'exemple suivant recherche un objet AdBreak :

    {
      "type":"mid",
      "duration":15,
      "ads":1
    }
    
  5. Utilisez les données TagSegment et AdBreak pour afficher des informations sur la position de l'annonce dans la coupure publicitaire. Par exemple, Ad 1 of 3.

Envoyer des pings de suivi publicitaire

Pour chaque événement d'annonce, à l'exception du type progress, envoyez un ping de suivi publicitaire. L'insertion dynamique d'annonce Google supprime les événements progress. L'envoi fréquent de ces événements peut avoir un impact sur les performances de votre application.

Pour générer l'URL complète de validation du média d'un événement d'annonce, procédez comme suit :

  1. À partir de la réponse du flux, ajoutez l'ID complet de l'événement d'annonce à la valeur media_verification_url.

  2. Envoyez une requête GET avec l'URL complète :

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
    const completeUrl = `${media_verification_url}google_1022389921`;
    
    const response = await fetch(completeUrl);
    

    Si l'opération réussit, vous recevez une réponse avec le code d'état 202. Sinon, vous recevrez un code d'erreur 404.

Vous pouvez utiliser le contrôle de l'activité des flux (SAM) pour inspecter un journal d'historique de tous les événements d'annonce. Pour en savoir plus, consultez Surveiller et dépanner une diffusion en direct.