L'API de diffusion de séries d'annonces permet d'accéder aux séries d'annonces vidéo à débit adaptatif préparées de manière à ce qu'elles puissent être assemblées directement dans un HLS destiné à l'utilisateur ou Playlist de contenus multimédias MPEG-DASH.
Ce guide est axé sur l'implémentation d'une manipulation de base du fichier manifeste pour la diffusion de séries d'annonces. 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 pour écouter le fichier manifeste à partir de l'application cliente du lecteur vidéo. Ce point de terminaison doit au minimum Collectez un ID de flux à partir de l'application du lecteur client. Cet ID de flux permet identifier la session en streaming auprès d'Ad Manager dans vos demandes de séries d'annonces.
Vous devez également recueillir d'autres informations pour identifier flux de contenu (par exemple, un système d'identification de contenu).
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 de chemin d'accès | |||||
---|---|---|---|---|---|
stream_id |
ID de flux Ad Manager provenant de l'application de lecteur vidéo cliente. | ||||
content_id |
ID fictif correspondant au contenu vidéo dans votre système. | ||||
format |
Paramètre hypothétique correspondant au format du flux. Au choix:
|
Récupérer le flux de contenu
Utiliser l'ID de contenu collecté dans la demande du fichier manifeste pour sélectionner le contenu pour ajouter des annonces.
Demander des fichiers manifestes de séries d'annonces
Pour demander des annonces à Ad Manager, votre serveur doit envoyer une demande POST à l'annonce au point de terminaison du pod, en transmettant les profils d'encodage, le tag d'emplacement publicitaire et le ciblage paramètres. Cette demande 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 et là où ils doivent être insérés 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 de chemin d'accès | |
---|---|
network_code |
Le 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 de 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, ces valeurs doivent correspondre à l'ensemble les profils d'encodage utilisés dans votre flux de contenu. |
ad_tag |
Required |
Un tag d'emplacement publicitaire pour demander des annonces VMAP. |
cuepoints |
Optional |
Une liste des points de repère du flux de contenu où les coupures publicitaires mid-roll
doit être insérée. 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 les décalages temporels positionnels. Cela n'est pas courant. |
content_duration_seconds |
Optional |
Durée du contenu en secondes.
Requis uniquement pour les réponses VMAP contenant des annonces vidéo mid-roll utilisant percentage. Cela n'est pas 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 l'affichage 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 mais vous ne pouvez pas utiliser plusieurs profils d'encodage portant le même nom le même flux. |
type |
Required |
Type d'encodage du flux décrit par ce profil d'encodage. Contenu
les types suivants sont: 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 type de profil d'encodage est iframe. Sinon, autorisé uniquement si le type de support contient "vidéo". Voir détails ci-dessous |
audio_settings |
Optional |
Obligatoire si le profil d'encodage contient de l'audio. Autorisé uniquement si le type est médias. Plus d'informations ci-dessous : |
subtitle_settings |
Optional |
Obligatoire si le profil d'encodage contient des sous-titres. Plus d'informations ci-dessous : |
Paramètres vidéo | ||
codec |
Required |
Chaîne de codec RFC6381.
Exemple : |
bitrate |
Required |
Nombre 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 la largeur et la hauteur de la vidéo en pixels.
Exemple : |
Paramètres audio | ||
codec |
Required |
Chaîne de codec RFC6381.
Exemple : |
bitrate |
Required |
Un nombre entier représentant le débit audio maximal de ce profil en octets par
seconde.
Exemple : |
channels |
Required |
Nombre entier représentant le nombre de canaux audio, y compris les basses fréquences canaux de distribution. |
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é pour les sous-titres intra-bandes. Les valeurs acceptées sont
webvtt ou ttml .
|
language |
Optional |
Langue du sous-titre en tant que chaîne de langue RFC5646. Si elle est fournie, cette valeur
n'est utilisé que pour le rendu DASH.
Exemple : |
Options d'insertion dynamique d'annonce | ||
dash_profile |
Optional |
Profil MPEG-DASH à appliquer aux fichiers manifestes de séries d'annonces. Ce paramètre est utilisé pour
Fichiers manifestes DASH uniquement. 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 à consacrer à la sélection des annonces et à la création de séries d'annonces, dans une fenêtre flottante
secondes. Une fois ce délai écoulé, Ad Manager renvoie
déjà sélectionnées dans la réponse ad_pods et s'arrête
en cours de traitement.
|
sam_id |
Optional |
Spécifie une autre clé de débogage pouvant être utilisée pour rechercher des sessions dans le activité de la diffusion surveiller. |
Réponse
Paramètres de réponse | |
---|---|
valid_for |
Durée de validité de ces playlists de séries d'annonces (dhms )
(jours, heures, minutes, secondes).
|
valid_until |
Date et heure de validité de ces playlists de séries d'annonces au format ISO 8601
Chaîne de date et heure, dans 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 du 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, exprimé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. 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
}
]
}
Intégrer des séries d'annonces au contenu
Le processus d'assemblage des séries d'annonces dans vos flux de contenu sur votre implémentation, le format du flux et les fonctionnalités que vous choisissez à implémenter selon les spécifications du format. Les workflows suivants des suggestions sur la façon de gérer ce processus. Les détails précis de votre mise en œuvre peut varier en fonction des besoins de votre entreprise et de votre contenu. flux.
Flux HLS
Si vous assemblez un flux au format HLS, votre flux de contenu sera un multivariante playlist de liens vers des fichiers manifestes de flux distincts, un pour chaque profil d'encodage. Votre annonce Les pods doivent être insérés dans chacun de ces fichiers manifestes de variantes. Une façon de il s'agit de préparer tous les fichiers manifestes des variantes et de les transmettre à une classe Content Réseau de diffusion (CDN) pour d'hébergement. La playlist de multivariantes finale est un ensemble de liens vers ces contenus hébergés sur CDN des fichiers manifestes.
Itérer sur les profils d'encodage
Pour chaque profil d'encodage, rassemblez tous les fichiers manifestes de séries d'annonces associés à partir des
Réponse d'Ad Manager, ainsi que les heures de début associées. Pour les annonces pré-roll
pods, définissez l'heure de début sur 0
. Pour les annonces vidéo post-roll, utilisez la durée du contenu comme suit :
l'heure de début de la série d'annonces. Identifier le flux de variantes dans le multivariant
qui correspond aux paramètres audio et vidéo de chaque profil d'encodage.
Exemple de tableau 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
Exemple 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 variante de flux, parcourez les segments du fichier manifeste de contenu, en gardant une
de la durée totale écoulée du contenu. Lorsque vous arrivez à la position de départ
d'une série d'annonces, extraire la liste des segments du fichier manifeste de la série d'annonces, encapsuler
liste de segments dans deux tags #EXT-X-DISCONTINUITY
, puis insérez la liste au niveau de
l'emplacement actuel dans le fichier manifeste de contenu. Continuez ainsi jusqu'à ce que toutes les
Les pods et les flux de variantes ont été traités.
Les fichiers manifestes obtenus doivent être conformes à la norme HLS. Par conséquent, en fonction des spécifications intégrées dans votre fichier manifeste de contenu, peut avoir besoin d'effectuer une dernière passe sur le fichier manifeste combiné pour corriger le contenu multimédia numéros de séquence, durée du contenu, numéros de séquence de discontinuité et toute les autres tags qui doivent être mis à jour pour prendre en compte les nouveaux segments d'annonces. Une fois les incohérences corrigées, repoussez chaque un fichier manifeste de variante spécifique à l'utilisateur vers votre CDN pour l'hébergement.
Si le fichier manifeste de votre contenu est chiffré, vous devez stocker le dernier chiffrement
trouvée avant le début de la série d'annonces actuelle dans un tag #EXT-X-KEY
. Ensuite,
vous devez ajouter la balise #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 du fichier
#EXT-X-KEY
avant le premier segment de contenu après chaque série d'annonces, pour
restaurer le chiffrement du contenu.
Exemple 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
listé dans la
ont collecté des données sur les variantes.
#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
Voici le contenu de
Fichier manifeste https://dai.google.com/{...}/pod/1/profile/1080p.m3u8
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 variante assemblée
Il s'agit du fichier manifeste de la variante assemblée qui est transmis au CDN,
hébergé sur 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 complété, ainsi que les détails du profil d'encodage correspondant, puis assembler les résultats dans un nouveau fichier manifeste de multivariantes. Ce fichier manifeste spécifique à l'utilisateur est renvoyé en tant que réponse à la demande de fichier manifeste que vous avez 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 faciliter l'assemblage des flux DASH qu'avec les flux HLS.
Un fichier de description de média MPEG DASH (MPD) correctement préparé doit se composent de plusieurs périodes, chacune contenant plusieurs représentations. Chaque doit correspondre à l'un de vos profils d'encodage. Chaque série d'annonces a renvoyé d'Ad Manager est également un fichier de la description de la présentation du média contenant une séquence de points avec des représentations correspondantes.
Pour assembler ces fichiers MPD, commencez par noter les heures de début pour chaque série d'annonces. Pour les annonces pré-roll, insérez les périodes de séries d'annonces pré-roll avant tout contenu période. Pour les annonces post-roll, insérez les périodes de séries d'annonces post-roll après tout le contenu périodes. Itérez les périodes de la description de la présentation du média (MPD) du contenu, en gardant une trace de la le temps de lecture écoulé pour toutes les périodes de contenu traités ; 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 à partir du fichier de description de la présentation du média de la série d'annonces mid-roll correspondante au niveau de cette limite.
Le fichier MPD final doit être entièrement conforme aux spécifications MPEG_DASH, Vous devrez donc peut-être itérer sur le fichier final une fois de plus pour corriger l'heure de début de la période, en corrigeant la durée de la présentation du média pour tenir compte les périodes d'annonces nouvellement insérées et à résoudre tout autre conflit résultant 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 pour une 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 une série d'annonces
Il s'agit du contenu de l'élément mpd_uri
issu du fichier JSON de la 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ée
Elle servira 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
- Diffusion de séries d'annonces avec le SDK IMA: <ph type="x-smartling-placeholder">
- Lecture de la diffusion de séries d'annonces avec l'insertion dynamique d'annonce API