L'API Pod Serving permet d'accéder à des séries d'annonces vidéo à débit adaptatif préparées de manière à pouvoir être assemblées directement dans une playlist de contenus multimédias HLS ou MPEG-DASH visible par l'utilisateur.
Ce guide est axé sur la mise en œuvre d'un serveur de manipulation de fichier manifeste de diffusion de séries d'annonces de base pour les flux de vidéo à la demande.
Recevoir des demandes de fichier manifeste de flux
Votre outil de manipulation du fichier manifeste doit fournir un point de terminaison d'API permettant d'écouter les requêtes de fichier manifeste provenant de l'application cliente du lecteur vidéo. Au minimum, ce point de terminaison doit collecter un ID de flux à partir de l'application du lecteur client. Cet ID de flux permet d'identifier la session de streaming auprès d'Ad Manager dans vos demandes de séries d'annonces.
Vous devez également collecter d'autres informations (par exemple, un ID de contenu) pour identifier le flux de contenu approprié.
Exemple de point de terminaison de requête de fichier manifeste
GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Paramètres du chemin d'accès | |||||
---|---|---|---|---|---|
stream_id |
ID de flux Ad Manager de l'application de lecteur vidéo cliente. | ||||
content_id |
Un identifiant fictif correspondant à la vidéo du contenu dans votre système. | ||||
format |
Paramètre hypothétique correspondant au format du flux. L'une des options suivantes:
|
Récupérer le flux de contenu
Utilisez l'ID de contenu collecté à partir de la requête de fichier manifeste pour sélectionner le flux de contenu à assembler avec les annonces.
Demander des fichiers manifestes de séries d'annonces
Pour demander des annonces à Ad Manager, votre serveur doit envoyer une requête POST au point de terminaison des pods d'annonces, en transmettant les profils d'encodage, le tag d'emplacement publicitaire et les paramètres de ciblage demandés. Cette requête inclut également l'ID de flux que vous avez collecté à l'étape 1.
En retour, vous recevez une liste d'objets de séries d'annonces contenant des fichiers manifestes pour les séries d'annonces demandées par le tag d'emplacement publicitaire de l'éditeur, ainsi que des informations sur le moment et l'endroit où elles doivent être insérées dans votre contenu.
POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Paramètres du chemin d'accès | |
---|---|
network_code |
Code de réseau Ad Manager 360 de l'éditeur. |
stream_id |
ID de flux de l'application de lecteur vidéo cliente. |
Corps JSON
Paramètres du corps | ||
---|---|---|
encoding_profiles |
Required |
Liste des représentations JSON des profils d'encodage que vous souhaitez recevoir pour chaque coupure publicitaire. Plus d'informations ci-dessous :
Pour que la lecture soit aussi fluide que possible, elle doit correspondre à l'ensemble des profils d'encodage utilisés dans votre flux de contenu. |
ad_tag |
Required |
Un tag d'emplacement publicitaire permettant de demander des annonces VMAP. |
cuepoints |
Optional |
Liste de points de repère dans le flux de contenu où les coupures publicitaires mid-roll seront insérées. Les points de repère sont mesurés en secondes à virgule flottante.
Requis uniquement pour les réponses VMAP contenant des annonces vidéo mid-roll utilisant des décalages temporels positionnels. C'est peu courant. |
content_duration_seconds |
Optional |
Durée du contenu en secondes.
Obligatoire uniquement pour les réponses VMAP qui contiennent des annonces vidéo mid-roll en utilisant des décalages temporels de pourcentage. C'est peu courant. |
manifest_type |
Optional |
Format des flux d'annonces demandés (hls ou dash ). La valeur par défaut est hls .
|
dai_options |
Optional |
Options supplémentaires contrôlant certains aspects du rendu des fichiers manifestes Plus d'informations ci-dessous : |
Profil d'encodage | ||
profile_name |
Required |
Identifiant de ce profil d'encodage. Cette valeur peut être n'importe quelle chaîne de votre choix, mais vous ne pouvez pas avoir plusieurs profils d'encodage portant le même nom sur le même flux. |
type |
Required |
Type d'encodage du flux décrit par ce profil d'encodage. Les types de contenus sont les suivants: media , iframe , subtitles .
|
container_type |
Required |
Format de conteneur utilisé par ce profil d'encodage. Les formats de conteneurs sont les suivants : mpeg2ts , fmp4cmaf et hls_packed_audio .
|
video_settings |
Optional |
Obligatoire si le profil d'encodage est de type iframe. Sinon, n'est autorisé que si le type de support contient vidéo. Voir les détails ci-dessous |
audio_settings |
Optional |
Obligatoire si le profil d'encodage contient de l'audio. Uniquement autorisé s'il s'agit d'un média. Plus d'informations ci-dessous : |
subtitle_settings |
Optional |
Obligatoire si le profil d'encodage comporte des sous-titres. Plus d'informations ci-dessous : |
Paramètres vidéo | ||
codec |
Required |
Chaîne de codec RFC6381.
Exemple : |
bitrate |
Required |
Entier représentant le débit vidéo maximal de ce profil en octets par seconde. |
frames_per_second |
Required |
FPS à virgule flottante de la vidéo. |
resolution |
Required |
Valeur encodée au format JSON contenant les valeurs "width" et "height" de la vidéo en pixels.
Exemple : |
Paramètres audio | ||
codec |
Required |
Chaîne de codec RFC6381.
Exemple : |
bitrate |
Required |
Entier représentant le débit audio maximal de ce profil en octets par seconde.
Exemple : |
channels |
Required |
Entier représentant le nombre de canaux audio, y compris les canaux basse fréquence. |
sample_rate |
Required |
Entier représentant le taux d'échantillonnage audio en hertz.
Exemple : |
Paramètres des sous-titres | ||
format |
Required |
Format de fichier utilisé par les sous-titres intégrés au groupe. Les valeurs acceptées sont webvtt ou ttml .
|
language |
Optional |
Langue des sous-titres en tant que chaîne de langue RFC5646. Si elle est fournie, cette valeur n'est utilisée que pour l'affichage DASH.
Exemple : |
Options d'insertion dynamique d'annonces | ||
dash_profile |
Optional |
Profil MPEG-DASH à appliquer aux fichiers manifestes de séries d'annonces. Ce paramètre n'est utilisé que pour les fichiers manifestes DASH. Les valeurs autorisées sont live ou on-demand . La valeur par défaut est on-demand .
La valeur
La valeur |
ad_pod_timeout |
Optional |
Temps maximal consacré à la sélection des annonces et à la création de séries d'annonces, en secondes à virgule flottante. Une fois ce délai écoulé, Ad Manager renvoie toutes les annonces déjà sélectionnées dans la réponse ad_pods et arrête le traitement.
|
sam_id |
Optional |
Spécifie une autre clé de débogage pouvant être utilisée pour rechercher des sessions dans l'outil de contrôle de l'activité des flux. |
Réponse
Paramètres de réponse | |
---|---|
valid_for |
Durée de validité de ces playlists de séries d'annonces, au format dhms (jours, heures, minutes, secondes).
|
valid_until |
Date et heure jusqu'à laquelle ces playlists de séries d'annonces sont valides en tant que chaîne de date et d'heure ISO 8601, au format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
ad_pods |
Liste des séries d'annonces sélectionnées pour ce flux. |
Série d'annonces | |
manifest_uris |
Pour les flux HLS uniquement. Mappage des ID de profil d'encodage avec les URI de fichier manifeste HLS. |
mpd_uri |
Pour les flux DASH uniquement. URI de la description de la présentation du média DASH. |
type |
Type de série d'annonces. Les types de séries d'annonces sont les suivants: pre , mid ou post .
|
start |
Pour les séries d'annonces mid-roll uniquement. Position dans le flux où cette série d'annonces doit être insérée, en secondes à virgule flottante. |
duration |
Durée de cette série d'annonces, en secondes à virgule flottante. |
midroll_index |
Pour les séries d'annonces mid-roll uniquement. Index de la série d'annonces mid-roll actuelle. L'indexation commence par 1 .
|
Exemple de requête (cURL)
curl -X POST \
-d '@request-body.json' \
-H 'Content-Type: application/json' \
https://dai.google.com/ondemand/pods/api/v1/network/21775744923/streams/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/adpods
Exemple de corps de requête
Il s'agit du contenu de request-body.json
référencé dans l'appel cURL ci-dessus.
{
"encoding_profiles": [
{
"profile_name": "1080p",
"type": "media",
"container_type": "mpeg2ts",
"video_settings": {
"codec": "avc1.4d000c",
"bitrate": 5000000,
"frames_per_second": 30.0,
"resolution": {
"width": 1920,
"height": 1080
}
},
"audio_settings": {
"codec": "mp4a.40.5",
"bitrate": 300000,
"channels": 2,
"sample_rate": 48000
}
},
{
"profile_name": "360p",
"type": "media",
"container_type": "mpeg2ts",
"video_settings": {
"codec": "avc1.4d000d",
"bitrate": 1000000,
"frames_per_second": 30.0,
"resolution": {
"width": 640,
"height": 360
}
},
"audio_settings": {
"codec": "mp4a.40.5",
"bitrate": 64000,
"channels": 2,
"sample_rate": 48000
}
},
{
"profile_name": "subtitles-webvtt",
"type": "subtitles",
"subtitle_settings": {
"format": "webvtt"
}
}
],
"ad_tag": "https://pubads.g.doubleclick.net/gampad/ads?...",
"manifest_type": "hls"
}
Exemple de réponse
{
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00",
"ad_pods": [
{
"manifest_urls":{
"1080p": "https://{...}/pod/0/profile/1080p.m3u8",
"360p": "https://{...}/pod/0/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt"
},
"type": "pre",
"duration": 10.0
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/1/profile/1080p.m3u8",
"360p": "https://{...}/pod/1/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/1/profile/subtitles-en.vtt"
},
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
},
{
"manifest_urls":{
]"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
"360p": "https://{...}/pod/2/profile.m3u8",
"subtitles-webvtt": "https://{...}/pod/0/profile/subtitles-en.vtt""
},
"type": "post",
"duration": 10.0
}
]
}
Assembler les séries d'annonces dans le contenu
Le processus d'intégration des séries d'annonces dans vos flux de contenu varie en fonction de votre implémentation, du format de flux et des fonctionnalités que vous choisissez d'implémenter parmi les spécifications du format. Les workflows suivants sont des suggestions pour gérer ce processus. Les détails précis de votre implémentation peuvent varier en fonction des besoins de votre entreprise et de vos flux de contenu.
Flux HLS
Si vous assemblez un flux au format HLS, votre flux de contenu sera une playlist multivariante de liens vers des fichiers manifestes de flux distincts, un pour chaque profil d'encodage. Vous devez insérer vos séries d'annonces dans chacun de ces fichiers manifestes de variantes. Pour ce faire, vous pouvez préparer tous les fichiers manifestes de variantes et les transmettre à un réseau de diffusion de contenu (CDN) pour l'hébergement. La playlist de multivariantes finale est un ensemble de liens vers ces fichiers manifestes hébergés sur CDN.
Itérer des profils d'encodage
Pour chaque profil d'encodage, rassemblez tous les fichiers manifestes de séries d'annonces associés à partir de la réponse d'Ad Manager, ainsi que les heures de début associées. Pour les séries d'annonces pré-roll, définissez l'heure de début sur 0
. Pour les annonces vidéo post-roll, utilisez la durée du contenu comme heure de début de la série d'annonces. Dans la playlist de multivariantes, identifiez le flux de variantes qui correspond aux paramètres audio et vidéo de chaque profil d'encodage.
Tableau des exemples de séries d'annonces
"ad_pods": [
{
"manifest_urls":{
"1080p": "https://{...}/pod/0/profile/1080p.m3u8",
"360p": "https://{...}/pod/0/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/0/profile/subitles-en.vtt"
},
"type": "pre",
"duration": 10.0
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/1/profile/1080p.m3u8",
"360p": "https://{...}/pod/1/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/1/profile/subitles-en.vtt"
},
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
},
{
"manifest_urls":{
"1080p": "https://{...}/pod/2/profile/1080p.m3u8",
"360p": "https://{...}/pod/2/profile/360p.m3u8",
"subtitles-en": "https://{...}/pod/2/profile/subitles-en.vtt"
},
"type": "post",
"duration": 10.0
}
]
Exemple de playlist de contenus multivariantes
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://{...}/subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://{...}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://{...}/360p.m3u8
Exemples de données de variantes collectées
Encoding profile: "1080p"
Profile settings: {...}
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
0 -> https://{...}/pod/0/profile/1080p.m3u8
15 -> https://{...}/pod/1/profile/1080p.m3u8
600 -> https://{...}/pod/2/profile/1080p.m3u8
Insérer des annonces dans chaque fichier manifeste de variante
Pour chaque flux de variantes, parcourez les segments du fichier manifeste de contenu, en conservant le total cumulé de la durée écoulée pour le contenu. Lorsque vous atteignez la position de départ d'une série d'annonces, extrayez la liste des segments à partir du fichier manifeste de la série d'annonces, encapsulez la liste des segments dans deux tags #EXT-X-DISCONTINUITY
, puis insérez la liste à l'emplacement actuel dans le fichier manifeste du contenu. Continuez jusqu'à ce que toutes les séries d'annonces et tous les flux de variantes aient été traités.
Les fichiers manifestes générés doivent être conformes à la norme HLS. Par conséquent, en fonction des fonctionnalités de la spécification qui sont intégrées dans votre fichier manifeste de contenu, vous devrez peut-être effectuer une dernière transmission sur le fichier manifeste combiné pour corriger les numéros séquentiels du média, la durée du contenu, les numéros de séquence de discontinuité et toute autre balise devant être mise à jour pour tenir compte des nouveaux segments d'annonces. Une fois les différences avec la norme corrigées, transférez chaque fichier manifeste de variante spécifique à l'utilisateur vers votre CDN pour l'hébergement.
Si votre fichier manifeste de contenu est chiffré, vous devez stocker la dernière clé de chiffrement trouvée avant le début de la série d'annonces actuelle dans une balise #EXT-X-KEY
. Vous devez ensuite ajouter le tag #EXT-X-KEY:METHOD=NONE
pour supprimer le chiffrement avant le premier segment de chaque série d'annonces. Enfin, vous devez ajouter une copie de la balise #EXT-X-KEY
stockée avant le premier segment de contenu après chaque série d'annonces afin de restaurer le chiffrement du contenu.
Exemples de données de variantes collectées
Encoding profile: "1080p"
Content manifest: https://{...}/1080p.m3u8
Ad pods (start time -> manifest):
0 -> https://dai.google.com/{...}pod/0/profile/1080p.m3u8
15 -> https://dai.google.com/{...}pod/1/profile/1080p.m3u8
600 -> https://dai.google.com/{...}pod/2/profile/1080p.m3u8
Exemple de fichier manifeste de contenu
Il s'agit du contenu du fichier manifeste https://{...}/1080p.m3u8
répertorié dans les données de variantes collectées.
#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
Exemple de fichier manifeste de série d'annonces
Il s'agit du contenu du fichier manifeste https://dai.google.com/{...}/pod/1/profile/1080p.m3u8
répertorié dans les données de variantes collectées.
#EXTM3U
{...}
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
Exemple de fichier manifeste de variantes assemblées
Il s'agit du fichier manifeste de variante assemblée obtenu, transmis au CDN et hébergé à https://cdn.{...}/{userid}/1080p.m3u8
.
#EXTM3U
{...}
#EXTINF:5.000,
https://{...}/1080p/content-segment-0.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-1.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://dai.google.com/{...}/0.ts
#EXTINF:5.000,
https://dai.google.com/{...}/1.ts
#EXTINF:5.000,
https://dai.google.com/{...}/2.ts
#EXT-X-DISCONTINUITY
#EXTINF:5.000,
https://{...}/1080p/content-segment-3.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-4.ts
#EXTINF:5.000,
https://{...}/1080p/content-segment-5.ts
{...}
Créer une playlist de multivariantes
Collectez les adresses CDN pour chaque fichier manifeste de variante terminé, ainsi que les détails du profil d'encodage correspondant, puis assemblez les résultats dans un nouveau fichier manifeste de multivariantes. Ce fichier manifeste spécifique à l'utilisateur est renvoyé en réponse à la requête de fichier manifeste reçue à l'étape 1.
Exemple de playlist de multivariantes finale
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="https://cdn.{...}-subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.4d000c,mp4a.40.5"
https://cdn.{...}/{userid}/1080p.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1000000,RESOLUTION=640x360,CODECS="avc1.4d000d,mp4a.40.5"
https://cdn.{...}/{userid}/360p.m3u8
Flux MPEG DASH
Si vous assemblez un flux au format MPEG DASH, il vous suffit de produire un seul fichier. Cela peut rendre les flux DASH plus faciles à assembler que HLS.
Un fichier MPEG DASH Mediapresentation Description (MPD) correctement préparé doit comporter plusieurs points, chacun contenant plusieurs représentations. Chaque représentation doit correspondre à l'un de vos profils d'encodage. Chaque série d'annonces renvoyée par Ad Manager est également un fichier MPD contenant une séquence de points avec des représentations correspondantes.
Pour assembler ces fichiers MPD, commencez par noter les heures de début de chaque série d'annonces. Pour les annonces vidéo pré-roll, insérez les périodes de série d'annonces pré-roll avant toute période de contenu. Pour les annonces vidéo post-roll, insérez les périodes de série d'annonces post-roll après toutes les périodes de contenu. Itérez les périodes de la description de la présentation du média pour le contenu, en suivant le temps de lecture écoulé pour toutes les périodes de contenu traitées. Lorsque vous atteignez une limite entre les périodes correspondant à l'heure de début d'une série d'annonces, insérez les points du fichier MPD de la série d'annonces mid-roll correspondant à cette limite.
Le fichier MPD final assemblé doit être entièrement conforme aux spécifications MPEG_DASH. Par conséquent, vous devrez peut-être itérer une nouvelle fois le fichier final en corrigeant les heures de début des périodes, en corrigeant la durée de présentation du média pour tenir compte des nouvelles périodes d'annonces et en résolvant tout autre conflit pouvant survenir lors du processus d'assemblage.
Exemple de description de la présentation du média pour le contenu
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M00.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Example Stream</Title>
</ProgramInformation>
<Period duration="PT0H0M15.000S" id="content-period-1">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-2">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-3">
...
</Period>
...
</MPD>
Exemple de code JSON de série d'annonces
[{
"mpd_uri": "https://{...}pod/1.mpd",
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
}]
Exemple de description de la présentation du média pour la série d'annonces
Il s'agit du contenu du mpd_uri
du fichier JSON de série d'annonces ci-dessus.
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H0M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Ad Pod 1</Title>
</ProgramInformation>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
...
</Period>
...
</MPD>
Exemple de description de la présentation du média assemblé
Servir de réponse à la requête initiale du fichier manifeste de flux.
<?xml version="1.0" encoding="UTF-8"?>
<MPD xmlns="urn:mpeg:dash:schema:mpd:2011" minBufferTime="PT1.500000S" type="static" mediaPresentationDuration="PT0H10M15.000S" profiles="urn:mpeg:dash:profile:isoff-on-demand:2011">
<ProgramInformation moreInformationURL="http://.../info">
<Title>Example Stream</Title>
</ProgramInformation>
<Period duration="PT0H0M15.000S" id="content-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-1">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-2">
...
</Period>
<Period duration="PT0H0M5.000S" id="ad-pod-1-period-3">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-2">
...
</Period>
<Period duration="PT0H0M15.000S" id="content-period-3">
...
</Period>
...
</MPD>
Ressources supplémentaires
- Lecture de séries d'annonces avec le SDK IMA :
- Diffusion de séries d'annonces via l'API d'insertion dynamique d'annonce