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 de 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": "8d2b2292-6356-4c0e-94be-cece01d2df2e: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.

Interroger les métadonnées des annonces

Pour interroger les métadonnées des annonces, procédez comme suit :

  1. Lisez la valeur metadata_url dans la réponse d'enregistrement du flux.

  2. Envoyez une requête GET au point de terminaison. Pour en savoir plus, consultez Méthode : métadonnées.

    L'exemple suivant récupère les métadonnées des annonces :

    const response = await fetch(metadata_url);
console.log(await response.json());

    Si l'opération réussit, vous recevez la réponse PodMetadata pour les pauses publicitaires actuelles et à venir :

    {
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

  3. Enregistrez l'objet tags pour les étapes ultérieures.

  4. Définissez un minuteur à l'aide de la valeur polling_frequency pour demander régulièrement les métadonnées de toutes les pauses publicitaires successives.

Chargez 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 du fichier manifeste, consultez Outil de manipulation du 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 utiles, 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 publicitaire à 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_1234567890123456789",
  ...
}

  3. Filtrez les tags ID3 avec le format TXXXgoogle_{ad_event_ID} :

    TXXXgoogle_1234567890123456789

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 publicitaire complet pour trouver un objet TagSegment avec le type progress.

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

  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 publicitaire, à 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 votre application.

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

  1. Dans la réponse du flux, ajoutez l'ID complet de l'événement publicitaire à 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_5555555555123456789`;

const response = await fetch(completeUrl);

    Si l'opération aboutit, vous recevez un code d'état 202. 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.