Premiers pas avec la SGAI

L'insertion d'annonces guidée par le serveur (SGAI) fournit un fichier manifeste de série d'annonces prêt à être assemblé sur les appareils clients. Si vous avez activé la diffusion d'annonces in-stream par pod dans votre réseau Google Ad Manager, vous pouvez utiliser la diffusion d'annonces in-stream par pod. Si la diffusion d'annonces in-stream dans des séries n'est pas activée, contactez votre responsable de compte.

Avec SGAI, vous utilisez les points de terminaison de l'API de diffusion de pod pour créer un flux qui récupère les métadonnées des annonces et les fichiers manifestes des séries d'annonces.

Si vous disposez d'un serveur de manipulation de fichiers manifestes, vous pouvez générer les URL de fichier manifeste de la série d'annonces et insérer des repères d'annonces qui contiennent les informations du fichier manifeste de la série d'annonces dans votre flux de contenu, selon vos spécifications préférées.

Vous pouvez également planifier une coupure publicitaire à l'aide d'un mécanisme autre que les repères publicitaires dans le fichier manifeste de flux. Dans ce cas, votre application peut écouter d'autres événements, par exemple l'interaction de l'utilisateur avec le flux, l'application elle-même ou une notification push. Après ces événements, l'application peut générer les URL du fichier manifeste du pod d'annonces et demander au lecteur de commencer à charger le fichier manifeste du pod d'annonces.

Prérequis

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

Suivre les recommandations

Avant de générer l'URL du fichier manifeste de la série d'annonces, nous vous recommandons d'appeler l'API EABN (Early Ad Break Notification) pour spécifier la durée prévue, les informations de ciblage et d'autres paramètres de chaque coupure publicitaire.

Pour les flux de production et de test, appelez l'API EABN, en particulier si votre réseau publicitaire comporte des campagnes programmatiques. Pour en savoir plus, consultez la section Fonctionnalités et consignes concernant le programmatique direct.

Envoyer une requête d'enregistrement de flux

Lorsqu'un utilisateur lance un flux de contenu dans votre application de lecteur vidéo, vous envoyez une demande d'enregistrement de flux avec des paramètres de ciblage pour créer une session de streaming dans Ad Manager. Pour savoir comment envoyer une requête d'enregistrement de flux, consultez la section Méthode:stream. Vous recevez ensuite des données de réponse de la requête.

Les exemples suivants envoient une requête d'enregistrement de flux:

HTTP en texte brut Coquille Rose JavaScript
  • Requête :
authority: dai.google.com
method: POST
path: /ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream
scheme: https
content-type: application/x-www-form-urlencoded

cust_params=customID%253D1543216789%2526anotherKey%253Dvalue1%252Cvalue2
  • Response:
{
    "manifest_format": "hls",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "polling_frequency": 10,
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL"
}
  • Ligne de commande :
curl \
-H "Host: dai.google.com" \
-H "content-type: application/x-www-form-urlencoded" \
  --data-binary "cust_params=channelID%253D1543216789%2526anotherKey%253Dvalue1%252Cvalue2" \
  --compressed "https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream"
  • Sortie :
{
    "manifest_format": "hls",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "pod_manifest_url": "https://dai.google.com/linear/pods/v1/hls/event/TFyZF0IoSpqvCLtLv8JdCw/pod/$pod-id$.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db%3ATUL",
    "polling_frequency": 10,
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL"
}
  • Utiliser l'API Fetch:
const response = await fetch("https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/hls-podserving-manifest/stream", {
  "headers": {
    "content-type": "application/x-www-form-urlencoded",
  },
  "body": "cust_params=channelID%3D1543216789%26anotherKey%3Dvalue1%2Cvalue2",
  "method": "POST",
});

  const stream = await response.json();
  console.log(stream);
  • Journal de la console:
{
    "stream_id": "24fd4e7c-95a0-42be-8874-00625139b9db:TUL",
    "media_verification_url": "https://dai.google.com/view/p/service/linear/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/loc/TUL/network/51636543/event/TFyZF0IoSpqvCLtLv8JdCw/media/",
    "metadata_url": "https://dai.google.com/linear/pods/hls/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/metadata",
    "session_update_url": "https://dai.google.com/linear/v1/pa/event/TFyZF0IoSpqvCLtLv8JdCw/stream/24fd4e7c-95a0-42be-8874-00625139b9db:TUL/session",
    "polling_frequency": 10,
    "pod_manifest_url": "https://dai.google.com/linear/pods/v1/hls/event/TFyZF0IoSpqvCLtLv8JdCw/pod/$pod-id$.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db%3ATUL",
    "manifest_format": "hls"
}

Interroger les métadonnées des coupures publicitaires

Après avoir envoyé une demande d'enregistrement de flux, interrogez les métadonnées des annonces. Pour effectuer une requête, vous devez définir un minuteur à l'aide de polling_frequence dans la réponse du flux à l'étape d'enregistrement pour appeler les metadata de l'annonce. Pour chaque sondage, vous pouvez recevoir une liste partielle des annonces avec des métadonnées à mesure qu'elles deviennent disponibles.

Générer l'URL du fichier manifeste du pod d'annonces

Créez une URL pour la ressource de série d'annonces de l'API d'insertion dynamique de séries d'annonces. Ensuite, transmettez l'URL à un lecteur vidéo pour commencer à charger la série d'annonces.

L'exemple suivant illustre la structure de l'URL du fichier manifeste du pod d'annonces:

https://dai.google.com/linear/pods/v1/hls/network/51636543/custom_asset/pod_serving_hls_manifest_mp4/ad_break_id/ab101.m3u8?stream_id=24fd4e7c-95a0-42be-8874-00625139b9db:TUL&pd=120000

Vous pouvez calculer les paramètres d'URL du fichier manifeste de la série d'annonces en fonction des informations sur la coupure publicitaire récupérées à partir du lecteur vidéo ou d'une notification du serveur. Pour connaître les exigences de ces paramètres, consultez la section Méthode: fichier manifeste du pod.

Lire le fichier manifeste du pod d'annonces

Dans l'application de lecteur vidéo client, lancez la lecture du flux de contenu avec un lecteur vidéo principal et suivez la documentation de votre lecteur vidéo pour observer la lecture et la programmation des annonces, le cas échéant.

Si vous générez les URL du fichier manifeste de la série d'annonces et les insérez dans le fichier manifeste côté serveur, observez les événements de coupure publicitaire à venir du lecteur vidéo et veillez à vous abonner aux événements id3 lors de chaque lecture de coupure publicitaire. Si vous planifiez les événements de coupure publicitaire côté client, abonnez-vous aux événements id3 lors de leur création.

Générer des rapports sur les impressions et les événements d'annonces

Lorsqu'un lecteur vidéo lit le pod d'annonces et rencontre des métadonnées temporelles ID3, écoutez les événements d'annonce que le lecteur vidéo déclenche et traitez-les pour envoyer des pings de validation des médias.