La API de Pod Serving proporciona acceso a los grupos de anuncios de video con tasa de bits adaptable preparados de manera que puedan unirse directamente a un servidor HLS orientado al usuario Playlist de contenido multimedia MPEG-DASH.
Esta guía se enfoca en implementar una manipulación básica del manifiesto de Publicación de grupos de anuncios para transmisiones de VOD.
Cómo recibir solicitudes de manifiesto de transmisión
Tu manipulador de manifiestos debe proporcionar un extremo de API para escuchar el manifiesto de la app cliente del reproductor de video. Como mínimo, este extremo debe recopilar un ID de transmisión de la app de reproductor cliente Este ID de transmisión se usa para identificar la sesión de transmisión a Ad Manager en tus solicitudes de grupos de anuncios.
También debe recopilar otra información para identificar la la transmisión de contenido, por ejemplo, un ID de contenido.
Ejemplo de extremo de solicitud de manifiesto
GET /api/stream_id/{stream_id}/video/{content_id}.{format}
Host: {your_domain}
Parámetros de ruta | |||||
---|---|---|---|---|---|
stream_id |
Es el ID de transmisión de Ad Manager de la app del reproductor de video del cliente. | ||||
content_id |
Un ID hipotético que corresponde al video de contenido en tu sistema. | ||||
format |
Es un parámetro hipotético que corresponde al formato de transmisión. Uno de los siguientes:
|
Recupera la transmisión de contenido
Usa el ID de contenido recopilado de la solicitud del manifiesto para seleccionar el contenido transmitir para unir anuncios.
Solicitar manifiestos de grupos de anuncios
Para solicitar anuncios de Ad Manager, su servidor debe enviar una solicitud POST al anuncio extremo de grupos de anuncios, pasando los perfiles de codificación, la etiqueta de anuncios y la segmentación solicitados. parámetros. Esta solicitud también incluye el ID de transmisión que recopilaste en el paso 1)
A cambio, recibe una lista de objetos de grupos de anuncios que contienen archivos de manifiesto de los grupos de anuncios solicitados por la etiqueta de anuncio del publicador y la información dónde deberían insertarse en tu contenido.
POST /ondemand/pods/api/v1/network/{network_code}/streams/{stream_id}/adpods
Host: dai.google.com
Content-Type: application/json
Parámetros de ruta | |
---|---|
network_code |
Es el código de red de Ad Manager 360 del publicador. |
stream_id |
El ID de transmisión de la app de reproductor de video del cliente. |
Cuerpo JSON
Parámetros corporales | ||
---|---|---|
encoding_profiles |
Required |
Una lista de representaciones JSON de los perfiles de codificación que quieres recibir
para cada pausa publicitaria. Sigue leyendo para conocer más detalles
Para que la reproducción sea lo más fluida posible, esto debe coincidir con el conjunto de los perfiles de codificación utilizados en la transmisión de contenido. |
ad_tag |
Required |
Una etiqueta de anuncio para solicitar anuncios de VMAP. |
cuepoints |
Optional |
Una lista de puntos de inserción dentro de la transmisión de contenido donde se mostrarán las pausas publicitarias durante el video.
insertar. Los puntos de inserción se miden en segundos de punto flotante.
Obligatorio solo para las respuestas de VMAP que contienen anuncios durante el video con posicionales. Esto es poco común. |
content_duration_seconds |
Optional |
Es la duración del contenido en segundos.
Obligatorio solo para las respuestas de VMAP que contienen anuncios durante el video con percentage. Esto es poco común. |
manifest_type |
Optional |
El formato de los flujos de anuncios que se solicitan, ya sea hls o
dash El valor predeterminado es hls .
|
dai_options |
Optional |
Son opciones adicionales que controlan aspectos de la manera en que se representan los manifiestos. Sigue leyendo para conocer más detalles |
Perfil de codificación | ||
profile_name |
Required |
Es un identificador para este perfil de codificación. Este valor puede ser cualquier cadena que pero no puedes tener varios perfiles de codificación con el mismo nombre en la misma transmisión. |
type |
Required |
El tipo de codificación de la transmisión que describe este perfil de codificación. Contenido
Los tipos son media , iframe y subtitles .
|
container_type |
Required |
El formato de contenedor que usa este perfil de codificación. Los formatos de contenedor son los siguientes:
mpeg2ts , fmp4cmaf y hls_packed_audio
|
video_settings |
Optional |
Obligatorio si el tipo de perfil de codificación es iframe. De lo contrario, solo se permite si el tipo de medio contiene video. Consulta a continuación |
audio_settings |
Optional |
Obligatorio si el perfil de codificación contiene audio. Solo se permite si el tipo es medios de comunicación. Sigue leyendo para conocer más detalles |
subtitle_settings |
Optional |
Obligatorio si el perfil de codificación contiene subtítulos. Sigue leyendo para conocer más detalles |
Configuración de video | ||
codec |
Required |
La cadena del códec RFC6381.
Ejemplo: |
bitrate |
Required |
Un número entero que representa la tasa de bits de video máxima de este perfil en bytes por por segundo. |
frames_per_second |
Required |
Es el valor de FPS de punto flotante del video. |
resolution |
Required |
Un valor codificado en JSON que contiene el valor "width" y "height" del video en píxeles.
Ejemplo: |
Configuración de audio | ||
codec |
Required |
La cadena del códec RFC6381.
Ejemplo: |
bitrate |
Required |
Un número entero que representa la tasa de bits de audio máxima de este perfil en bytes por
por segundo.
Ejemplo: |
channels |
Required |
Un número entero que representa la cantidad de canales de audio, incluida la frecuencia baja canales. |
sample_rate |
Required |
Es un número entero que representa la tasa de muestreo de audio en hercios.
Ejemplo: |
Configuración de subtítulos | ||
format |
Required |
Formato de archivo que usan los subtítulos en banda. Valores admitidos:
webvtt o ttml .
|
language |
Optional |
El idioma de subtítulos como una cadena de idioma RFC5646. Si se proporciona, este valor
solo se usa para el procesamiento DASH.
Ejemplo: |
Opciones de DAI | ||
dash_profile |
Optional |
Es el perfil de MPEG-DASH que se aplicará a los manifiestos de grupos de anuncios. Este parámetro de configuración se usa para
Solo manifiestos de DASH. Los valores permitidos son live o
on-demand El valor predeterminado es on-demand .
El valor
El valor |
ad_pod_timeout |
Optional |
El tiempo máximo que se debe dedicar a seleccionar anuncios y crear grupos de anuncios en anuncios flotantes
punto y segundos. Una vez transcurrido ese tiempo, Ad Manager mostrará
los anuncios ya seleccionados en la respuesta ad_pods y se detienen
el procesamiento de datos.
|
sam_id |
Optional |
Especifica una clave de depuración alternativa que se puede usar para buscar sesiones en el actividad de transmisión supervisión. |
Respuesta
Parámetros de respuesta | |
---|---|
valid_for |
Duración de la validez de estas playlists de grupos de anuncios en dhms
(días, horas, minutos, segundos).
|
valid_until |
La fecha y hora hasta la que estas playlists de grupos de anuncios son válidas como norma ISO8601
String de fecha y hora, en yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm
de un conjunto de datos
tengan un formato común.
|
ad_pods |
Es una lista de grupos de anuncios seleccionados para esta transmisión. |
Grupo de anuncios | |
manifest_uris |
Solo para transmisiones HLS. Es una asignación de los IDs de perfiles de codificación a los URI de manifiesto de HLS. |
mpd_uri |
Solo para transmisiones DASH. El URI de la MPD de DASH. |
type |
Es el tipo de grupo de anuncios. Los tipos de grupos de anuncios son: pre , mid o
post
|
start |
Solo para grupos de anuncios durante el video. Es la posición en la transmisión en la que este grupo de anuncios. debe insertarse en segundos de punto flotante. |
duration |
Es la duración de este grupo de anuncios en segundos de punto flotante. |
midroll_index |
Solo para grupos de anuncios durante el video. Es el índice del grupo de anuncios durante el video actual. Indexación
comienza con 1 .
|
Solicitud de ejemplo (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
Cuerpo de la solicitud de ejemplo
Este es el contenido de request-body.json
al que se hace referencia en la llamada cURL anterior.
{
"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"
}
Ejemplo de respuesta
{
"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
}
]
}
Unir grupos de anuncios en el contenido
El proceso de unir grupos de anuncios a sus transmisiones de contenido varía según sobre tu implementación, el formato de transmisión y las funciones que elijas implementar a partir de las especificaciones del formato. Los siguientes flujos de trabajo son sugerencias sobre cómo manejar este proceso. Los detalles precisos de tus de implementación puede variar según las necesidades de tu empresa y tu contenido transmisiones continuas.
Transmisiones HLS
Si quieres unir una transmisión en el formato HLS, la transmisión de contenido será una multivariante playlist de vínculos a manifiestos de transmisión separados, uno para cada perfil de codificación. Su anuncio Pods deben insertarse en cada uno de estos manifiestos de variantes. Una forma de hacer esto es preparar todos los manifiestos de variantes y pasarlos a una de distribución (CDN) para web. La última playlist de múltiples variantes es un conjunto de vínculos a estas manifiestos.
Cómo iterar en perfiles de codificación
Para cada perfil de codificación, recopile todos los manifiestos de grupos de anuncios asociados de
Es la respuesta de Ad Manager, junto con sus horas de inicio asociadas. Para anuncios previos al video
Pods, establece la hora de inicio en 0
. Para los anuncios al final del video, usa la duración del contenido como
la hora de inicio del grupo de anuncios. Identifica el flujo de variantes en la multivariante
playlist que coincida con la configuración de audio y video de cada perfil de codificación.
Ejemplo de array de grupos de anuncios
"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
}
]
Ejemplo de playlist de contenido de múltiples variantes
#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
Ejemplo de datos de variantes recopilados
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
Inserta anuncios en el manifiesto de cada variante
Para cada transmisión de variantes, revisa los segmentos del manifiesto de contenido y mantén un
el total de tiempo del contenido transcurrido. Cuando llegues a la posición inicial
de un grupo de anuncios, extraer la lista de segmentos del manifiesto del grupo de anuncios, unir
una lista de segmentos en dos etiquetas #EXT-X-DISCONTINUITY
y, luego, inserta la lista en el
la ubicación actual en el manifiesto de contenido. Continúa este proceso hasta que se muestren
los Pods y las transmisiones de variantes.
Los manifiestos resultantes deben cumplir con el estándar HLS. Por lo tanto, dependiendo sobre las funciones de la especificación que incorpora tu manifiesto de contenido, quizás debas hacer un repaso final del manifiesto combinado para corregir el contenido multimedia de secuencia, la duración del contenido, los números de secuencia de discontinuidad y cualquier otras etiquetas que deben actualizarse para tener en cuenta los nuevos segmentos de anuncios. Cuando se hayan corregido las discrepancias con el estándar, envía cada del manifiesto de la variante específica del usuario a tu CDN para el hosting.
Si tu manifiesto de contenido está encriptado, debes almacenar el último archivo
que se encuentra antes del inicio del grupo de anuncios actual en una etiqueta #EXT-X-KEY
. Luego,
debes agregar la etiqueta #EXT-X-KEY:METHOD=NONE
para quitar la encriptación antes
el primer segmento de cada grupo de anuncios. Por último, debes agregar una copia del archivo
Etiqueta #EXT-X-KEY
antes del primer segmento de contenido después de cada grupo de anuncios para
restablecer la encriptación de contenido.
Ejemplo de datos de variantes recopilados
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
Ejemplo de manifiesto de contenido
Este es el contenido del manifiesto https://{...}/1080p.m3u8
que se menciona en el
datos de variantes recopilados.
#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
{...}
Ejemplo de manifiesto de grupo de anuncios
Este es el contenido del
Manifiesto de https://dai.google.com/{...}/pod/1/profile/1080p.m3u8
que se enumeran en los datos recopilados de las variantes.
#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
Ejemplo de manifiesto de variante unida
Este sería el manifiesto de la variante unida resultante, que se pasa a la CDN y
alojado en 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
{...}
Crea playlists de múltiples variantes
Recopila las direcciones de la CDN de cada manifiesto de variante completado, junto con los hacer coincidir los detalles del perfil de codificación y reunir los resultados en una nueva manifiesto de múltiples variantes. Este manifiesto específico del usuario se muestra como respuesta a la solicitud de manifiesto que recibiste en el paso 1.
Ejemplo de playlist final de múltiples variantes
#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
Transmisiones MPEG DASH
Si vas a unir una transmisión en formato MPEG DASH, solo debes producir un solo archivo. Esto puede hacer que las transmisiones DASH sean más fáciles de unir que las HLS.
Un archivo de descripción de presentación multimedia (MPD) MPEG DASH preparado correctamente debe constan de varios períodos, cada uno de los cuales contiene múltiples representaciones. Cada la representación debe coincidir con uno de tus perfiles de codificación. Cada grupo de anuncios devuelto de Ad Manager también es un archivo MPD que contiene una secuencia de puntos con representaciones coincidentes.
Para unir estos archivos MPD, comienza por tomar nota de las horas de inicio de para cada grupo de anuncios. Para los anuncios previos al video, inserte los puntos del grupo de anuncios previos al video antes de cualquier anuncio. período. Para los anuncios al final del video, inserte los puntos del grupo de anuncios al final del video después de todo el contenido. en los períodos de prueba. Iterar en los períodos de la MPD de contenido y hacer un seguimiento del tiempo de reproducción transcurrido para todos los períodos de contenido procesado. Cuando alcances un límite entre los períodos que corresponden a la hora de inicio de un grupo de anuncios, inserte los puntos del archivo MPD del grupo de anuncios durante el video coincidente en ese límite.
El archivo MPD unido final debe cumplir por completo con las especificaciones MPEG_DASH, por lo que quizás debas iterar sobre el archivo final una vez más y corregir de inicio del período y corregir la duración de la presentación en los medios para dar cuenta del los períodos publicitarios insertados recientemente y la resolución de cualquier otro conflicto que podría haber surgen del proceso de costura.
Ejemplo de MPD de contenido
<?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>
Ejemplo de JSON de grupo de anuncios
[{
"mpd_uri": "https://{...}pod/1.mpd",
"type": "mid",
"start": 15.0,
"duration": 15.0,
"midroll_index": 1
}]
Ejemplo de MPD de grupo de anuncios
Este es el contenido de mpd_uri
del JSON del grupo de anuncios anterior.
<?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>
Ejemplo de MPD unida
Úsala como respuesta a la solicitud inicial del manifiesto de transmisión.
<?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>
Recursos adicionales
- Reproducción de publicación de grupos de anuncios con el SDK de IMA:
- Reproducción de grupos de anuncios con la DAI API