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 fichiers manifestes.

Prérequis

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

Envoyer une requête de flux

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

  1. Envoyez une requête POST à la méthode du service de diffusion en direct. Pour en savoir plus, consultez Méthode : flux.

  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 effectue 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, vous obtenez un résultat semblable à celui-ci :

    {
"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 des annonces :

  1. Lisez la valeur metadata_url dans 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 pour la fenêtre de l'enregistreur vidéo numérique (DVR) du flux. La fenêtre DVR contient la période de diffusion pendant laquelle un spectateur peut revenir en arrière et lire la diffusion. 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. Dans 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 été modifiées 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 des annonces :

    // 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 pauses 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 pauses 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 requête, 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 le streaming 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 publicitaires

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

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

  • Les flux DASH utilisent des éléments EventStream pour spécifier les é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 boîtes 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 sur la gestion des 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 avec le 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 des annonces, 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 la prochaine interrogation des métadonnées. Conservez le tag dans la file d'attente jusqu'à la fin du traitement.

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

    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 validation des éléments multimédias

Pour chaque événement d'annonce, à l'exception du type progress, envoyez un ping de validation du média. Google DAI ignore les événements progress. L'envoi fréquent de ces événements peut avoir un impact sur les performances de l'application.

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

  1. Dans 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 aboutit, vous recevez un code d'état 202 en réponse. Sinon, vous recevrez un code d'erreur 404.

Vous pouvez utiliser l'outil de contrôle de l'activité des flux pour inspecter l'historique de tous les événements publicitaires. Pour en savoir plus, consultez Surveiller et résoudre les problèmes liés à une diffusion en direct.