MediaTailor variables de anuncios dinámicos - AWS Elemental MediaTailor
MediaTailor referencia de parámetrosMediaTailor alias de configuraciónMediaTailor pasar los parámetros del ADSMediaTailorsolución de problemas de alias

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

MediaTailor variables de anuncios dinámicos

AWS Elemental MediaTailor La solicitud al servidor de decisiones publicitarias (ADS) incluye información sobre la sesión de visualización actual. Esta información ayuda al ADS a elegir los mejores anuncios para proporcionarlos en su respuesta. Al configurar la plantilla ADS en su MediaTailor configuración, puede incluir variables dinámicas, también conocidas como macros. Las variables dinámicas son cadenas reemplazables.

Las variables dinámicas pueden adoptar las siguientes formas:

  • Valores estáticos: valores que no cambian de una sesión a la siguiente. Por ejemplo, el tipo de respuesta que MediaTailor espera del ADS.

  • Variables de dominio: variables dinámicas que se pueden usar para los dominios URL, como la parte my-ads-server.com de la URL http://my-ads-server.com. Para obtener más información, consulte MediaTailor variables de dominio.

  • Datos de sesión: valores dinámicos que proporciona cada sesión, MediaTailor por ejemplo, el ID de sesión. Para obtener más información, consulte MediaTailor variables de sesión.

  • Datos del jugador: valores dinámicos que proporciona el jugador para cada sesión. Estos describen al espectador del contenido y ayudan al ADS a determinar qué anuncios MediaTailor deben incluirse en la transmisión. Para obtener más información, consulte MediaTailor variables de reproductor.

MediaTailor parámetros, referencia y limitaciones

AWS Elemental MediaTailor proporciona información completa sobre las restricciones de caracteres de los parámetros, las limitaciones de longitud y los formatos admitidos tanto para los parámetros de consulta del manifiesto como para los parámetros de ADS.

Restricciones de caracteres del parámetro de consulta del manifiesto

Los parámetros de consulta del manifiesto admiten caracteres específicos y tienen limitaciones de longitud definidas.

Caracteres admitidos (sin codificación de URL)

Puedes usar los siguientes caracteres directamente en los parámetros de consulta del manifiesto:

  • Caracteres alfanuméricos (A-Z, a-z, 0-9)

  • Períodos (.)

  • Guiones (-)

  • Guiones bajos (_)

  • Barras invertidas (\)

Caracteres compatibles con codificación URL

Cuando se codifica en URL, se admiten los siguientes caracteres especiales:

  • punto (.) = %2E

  • guión (-) = %2D

  • guión bajo (_) = %5F

  • porcentaje (%) = %25

  • tilde (~) = %7E

  • barra inclinada (/) = %2F

  • asterisco (*) = %2A

  • es igual a (=) = %3D

  • pregunta (?) = %3F

Soporte de codificación de URL

MediaTailor admite el signo de porcentaje (%) cuando se utiliza en la codificación de direcciones URL (por ejemplo, hello%20world = hello world). Puede utilizar cualquier carácter codificado en una URL, siempre que sean codificaciones de URL válidas de acuerdo con la especificación HTTP.

Caracteres no admitidos

No puedes usar los siguientes caracteres en los parámetros de consulta del manifiesto sin codificar la URL::,,, ? & =%, / (barra inclinada).

importante

MediaTailor no admite caracteres dobles como%%% o ==. No se pueden utilizar valores de parámetros de consulta completos URLs como manifiesto debido a las restricciones de caracteres.

Limitaciones de longitud

La longitud total de todos los parámetros de consulta del manifiesto (claves y valores combinados) no debe superar los 2000 caracteres.

Limitaciones de longitud de los parámetros ADS

Las siguientes limitaciones de longitud se aplican a los parámetros utilizados en las solicitudes al ADS:

  • Nombre del parámetro ADS: máximo 10 000 caracteres

  • Valor del parámetro ADS: 25 000 caracteres como máximo

  • URL de ADS: 25 000 caracteres como máximo

MediaTailor alias de configuración y reemplazo dinámico de variables

AWS Elemental MediaTailor Los alias de configuración permiten la sustitución dinámica de variables en los dominios URL y otros campos compatibles. Utilice esta función para utilizar varios dominios y realizar una configuración dinámica URLs durante la inicialización de la sesión.

Campos compatibles para el reemplazo dinámico de variables

Puede utilizar variables dinámicas en los siguientes campos de configuración:

  • VideoContentSourceUrl

  • AdDecisionServerUrl

  • LivePreroll.AdDecisionServerUrl

  • AdSegmentUrlPrefix

  • ContentSegmentUrlPrefix

  • TranscodeProfileName

  • SlateAdUrl

  • StartUrl

  • EndUrl

Reglas de parámetros a nivel de dominio

Al utilizar variables dinámicas en partes del dominio URLs, se aplican las siguientes restricciones:

  • Todas las variables dinámicas utilizadas en los dominios deben especificarse como ConfigurationAliases

  • Solo puede ser player_params

  • La lista de valores con alias debe ser exhaustiva

  • Los alias no válidos o faltantes provocan errores HTTP 400

ConfigurationAliases Estructura de parámetros de la API

El ConfigurationAliases parámetro utiliza la siguiente estructura JSON: 

{
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc.mediapackage.us-west-2.amazonaws.com",
            "iad": "xyz.mediapackage.us-east-1.amazonaws.com"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        }
    }
}
Coherencia de la API

playerParamsahora se admite como alternativa ads y adsParams para mejorar la coherencia de las API.

Comportamiento alternativo para los alias faltantes

Cuando los alias de configuración no se encuentran o no son válidos, MediaTailor implementa el siguiente comportamiento alternativo:

  • Variables de dominio: si falta un alias de variable de dominio o no es válido, la solicitud falla con el código de estado HTTP 400. Todas las variables de dominio deben tener definidos alias válidos.

  • Variables que no son de dominio: en el caso de las variables que se utilizan en partes que no son de dominio URLs (como los elementos de ruta o los parámetros de consulta), si faltan alias, se reemplaza una cadena vacía.

  • Validación de la configuración: MediaTailor valida que todos los alias necesarios estén presentes durante las operaciones de creación y actualización de la configuración.

Casos de uso avanzados de múltiples configuraciones

Los alias de configuración permiten arquitecturas sofisticadas de múltiples configuraciones para los siguientes escenarios:

ejemplo Configuración completa con alias

El siguiente ejemplo muestra una configuración completa que incluye alias de configuración y variables de dominio dinámicas: 

PUT /playbackConfiguration
{
    "Name": "aliasedConfig",
    "AdDecisionServerUrl": "https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=[player_params.ad_type]",
    "VideoContentSourceUrl": "https://[player_params.origin_domain].mediapackage.[player_params.region].amazonaws.com/out/v1/[player_params.endpoint_id]",
    
    "AdSegmentUrlPrefix": "https://[player_params.ad_cdn_domain]/ads/",
    "ContentSegmentUrlPrefix": "https://[player_params.content_cdn_domain]/content/",
    "TranscodeProfileName": "[player_params.transcode_profile]",
    "SlateAdUrl": "https://[player_params.slate_domain]/slate/[player_params.slate_type].mp4",
    "StartUrl": "https://[player_params.tracking_domain]/start?session=[session.id]",
    "EndUrl": "https://[player_params.tracking_domain]/end?session=[session.id]",
    
    "ConfigurationAliases": {
        "player_params.origin_domain": {
            "pdx": "abc",
            "iad": "xyz"
        },
        "player_params.region": {
            "pdx": "us-west-2",
            "iad": "us-east-1"
        },
        "player_params.endpoint_id": {
            "pdx": "abcd",
            "iad": "wxyz"
        },
        "player_params.ad_type": {
            "customized": "abc12345",
            "default": "defaultAdType"
        },
        "player_params.ad_cdn_domain": {
            "pdx": "ads-west.cdn.example.com",
            "iad": "ads-east.cdn.example.com"
        },
        "player_params.content_cdn_domain": {
            "pdx": "content-west.cdn.example.com",
            "iad": "content-east.cdn.example.com"
        },
        "player_params.transcode_profile": {
            "mobile": "mobile_optimized",
            "desktop": "high_quality",
            "tv": "4k_profile"
        },
        "player_params.slate_domain": {
            "pdx": "slate-west.example.com",
            "iad": "slate-east.example.com"
        },
        "player_params.slate_type": {
            "standard": "default_slate",
            "branded": "brand_slate"
        },
        "player_params.tracking_domain": {
            "pdx": "tracking-west.example.com",
            "iad": "tracking-east.example.com"
        }
    }
}
ejemplo Inicialización de la sesión con alias

Con la configuración anterior, cree una solicitud de inicialización de sesión especificando las variables y los alias del reproductor: 

POST master.m3u8
{
    "playerParams": {
        "origin_domain": "pdx",
        "region": "pdx", 
        "endpoint_id": "pdx",
        "ad_type": "customized",
        "ad_cdn_domain": "pdx",
        "content_cdn_domain": "pdx",
        "transcode_profile": "mobile",
        "slate_domain": "pdx",
        "slate_type": "branded",
        "tracking_domain": "pdx"
    }
}
ejemplo Flujo de procesamiento de parámetros

MediaTailor reemplaza las cadenas de alias por los valores mapeados en los alias de configuración. El procesamiento da como resultado las siguientes solicitudes:

  • Solicitud de ADS:

    https://abc.execute-api.us-west-2.amazonaws.com/ads?sid=[session.id]&ad_type=abc12345

  • VideoContentSource solicitud:

    https://abc.mediapackage.us-west-2.amazonaws.com/out/v1/abcd

  • AdSegmentUrlPrefix:

    https://ads-west.cdn.example.com/ads/

  • ContentSegmentUrlPrefix:

    https://content-west.cdn.example.com/content/

  • TranscodeProfileName:

    mobile_optimized

  • SlateAdUrl:

    https://slate-west.example.com/slate/brand_slate.mp4

  • StartUrl:

    https://tracking-west.example.com/start?session=[session.id]

  • EndUrl:

    https://tracking-west.example.com/end?session=[session.id]

MediaTailor pasar parámetros al ADS

AWS Elemental MediaTailor permite configurar variables dinámicas en las MediaTailor solicitudes al ADS mediante los siguientes pasos.

Métodos de inicialización de la sesión

MediaTailor admite varios métodos para la inicialización de la sesión y el paso de parámetros:

  1. POST con cuerpo de solicitud:

    POST <master>.m3u8
{
    "adsParams": {"param1": "value1", "param2": "value2"},
    "playerParams": {"param3": "value3"}
}

  2. Parámetros de consulta en la URL:

    GET <master>.m3u8?ads.param1=value1&ads.param2=value2&playerParams.param3=value3
importante

Solo puede especificar los parámetros una vez, en el momento de la inicialización. Los alias de configuración se resuelven con los valores reales antes de reenviarlos.

Para pasar información de la sesión y el reproductor a ADS

  1. Trabaje con el ADS para determinar la información que necesita para responder a una consulta de anuncios. AWS Elemental MediaTailor

  2. Crea una configuración MediaTailor que utilice una plantilla de URL de solicitud de ADS que cumpla los requisitos de ADS. En la URL, incluya parámetros estáticos y marcadores de posición para los parámetros dinámicos. Especifique la URL de la plantilla en el campo Ad decision server (Servidor de decisión de anuncios) de la configuración.

    En el siguiente ejemplo, la URL de la plantilla, correlation, proporciona datos de la sesión y deviceType proporciona datos del reproductor: 

    https://my.ads.server.com/path?correlation=[session.id]&deviceType=[player_params.deviceType]

  3. En el reproductor, configure la solicitud de inicio de sesión para que AWS Elemental MediaTailor proporcione los parámetros para los datos del reproductor. Incluya los parámetros en la solicitud de inicio de sesión y omítalos en las solicitudes de sesión posteriores.

    El tipo de llamada que realiza el jugador para inicializar la sesión determina si el jugador (cliente) o MediaTailor (servidor) proporciona informes de seguimiento de anuncios para la sesión. Para obtener información sobre estas dos opciones, consulte Datos de informes y seguimiento .

    Realice uno de los siguientes tipos de llamadas, en función de si desea realizar informes de seguimiento de anuncios en el servidor o en el cliente. En ambas llamadas de ejemplo, userID es para el ADS y auth_token es para el origen:

    • (Opcional) Solicita informes de seguimiento de anuncios en el servidor: añade un prefijo a los parámetros que quieres enviar MediaTailor al ADS. ads Suprima el prefijo para los parámetros que desee que MediaTailor envíe al servidor de origen:

      Los siguientes ejemplos muestran las solicitudes entrantes de HLS y DASH a. AWS Elemental MediaTailor MediaTailor usa el deviceType en su solicitud al ADS y el auth_token en su solicitud al servidor de origen.

      Ejemplo de HLS:

      GET master.m3u8?ads.deviceType=ipad&auth_token=kjhdsaf7gh

      Ejemplo de DASH:

      GET manifest.mpd?ads.deviceType=ipad&auth_token=kjhdsaf7gh

    • (Opcional) Solicita informes de seguimiento de anuncios por parte del cliente: proporciona parámetros para el ADS dentro de un objeto. adsParams

      Ejemplo de HLS:

      POST master.m3u8
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }

      Ejemplo de DASH:

      POST manifest.mpd
    {
        "adsParams": {
           "deviceType": "ipad"
       }
    }

Cuando el reproductor inicia una sesión, AWS Elemental MediaTailor reemplaza las variables de la URL de solicitud de ADS de la plantilla por los datos de la sesión y los parámetros del reproductor. ads Pasa los parámetros restantes del reproductor al servidor de origen.

ejemplo MediaTailor solicitudes con variables de anuncios

Los siguientes ejemplos muestran las llamadas al ADS y al servidor de origen desde AWS Elemental MediaTailor que se corresponden con los ejemplos de llamada de inicialización de sesión del reproductor anterior:

  • MediaTailor llama al ADS con los datos de la sesión y el tipo de dispositivo del jugador: 

    https://my.ads.server.com/path?correlation=896976764&deviceType=ipad

  • MediaTailor llama al servidor de origen con el token de autorización del jugador.

    • Ejemplo de HLS:

      https://my.origin.server.com/master.m3u8?auth_token=kjhdsaf7gh

    • Ejemplo de DASH:

      https://my.origin.server.com/manifest.mpd?auth_token=kjhdsaf7gh

Uso avanzado

Puede personalizar la solicitud de ADS de muchas formas con datos del reproductor y de la sesión. Solo necesita incluir el nombre de host de ADS.

En los siguientes ejemplos se muestran algunas de las maneras en que puede personalizar su solicitud:

  • Concatenar los parámetros del reproductor y los parámetros de la sesión para crear nuevos parámetros. Ejemplo: 

    https://my.ads.com?key1=[player_params.value1][session.id]

  • Usar un parámetro de reproductor como parte de un elemento de ruta. Ejemplo:

    https://my.ads.com/[player_params.path]?key=value

  • Usar parámetros del reproductor para pasar los elementos de ruta y las propias clave, en lugar de solo valores. Ejemplo: 

    https://my.ads.com/[player_params.path]?[player_params.key1]=[player_params.value1]

MediaTailor solución de problemas de alias de configuración

AWS Elemental MediaTailor proporciona una guía sistemática de solución de problemas relacionados con los alias de configuración y los escenarios de error más comunes.

Errores de validación del alias de configuración

Cuando faltan alias de configuración o no son válidos, MediaTailor devuelve respuestas de error específicas para ayudar a identificar el problema.

Escenarios de error comunes

En la siguiente tabla se describen los errores de alias de configuración más comunes y sus pasos para resolverlos:

Error Causa Resolución
HTTP 400: alias de parámetros de reproductor no válido No se encontró el valor del parámetro del reproductor en ConfigurationAliases Compruebe que el valor del parámetro del reproductor existe como clave en el ConfigurationAliases mapeo correspondiente
HTTP 400: falta el alias de configuración obligatorio Variable de dominio utilizada sin la ConfigurationAliases entrada correspondiente Añada el parámetro de jugador que falta ConfigurationAliases a todas las asignaciones de alias necesarias
HTTP 400: Falló la validación de la configuración ConfigurationAliases la estructura está mal formada o incompleta Valide la estructura JSON y asegúrese de que todas las variables de dominio tengan los alias correspondientes
Sustitución de una cadena vacía en URLs No se encontró el alias de una variable que no es de dominio Añada el mapeo de alias que falte o proporcione un valor predeterminado en ConfigurationAliases
Lista de verificación de validación

Utilice la siguiente lista de comprobación para validar la configuración de los alias de configuración:

  1. Cobertura de variables de dominio: asegúrese de que todas las variables utilizadas en las partes del dominio URLs tengan las entradas correspondientes ConfigurationAliases

  2. Integridad de los alias: compruebe que todos los valores posibles de los parámetros del jugador estén incluidos como claves en las asignaciones de alias

  3. Estructura de JSON: valida que el ConfigurationAliases JSON esté correctamente formateado y anidado

  4. Denominación de los parámetros: confirme que todos los parámetros del reproductor utilizan el prefijo player_params.

  5. Coherencia de valores: asegúrate de que los valores de alias sean válidos para el uso al que están destinados (nombres de perfilURLs, etc.)

Depuración de la configuración y resolución de alias

Siga este enfoque sistemático para depurar los problemas de resolución de los alias de configuración.

Step-by-step metodología de depuración

Siga los siguientes pasos para identificar y resolver los problemas de alias de configuración:

Procedimiento de depuración de alias de configuración

  1. Verifique la estructura de configuración: confirme que la configuración de reproducción incluye el formato correcto ConfigurationAliases

    {
    "ConfigurationAliases": {
        "player_params.example_param": {
            "alias1": "value1",
            "alias2": "value2"
        }
    }
}

  2. Compruebe el formato de los parámetros del reproductor: asegúrese de que la inicialización de la sesión incluya los parámetros del reproductor correctamente formateados

    {
    "playerParams": {
        "example_param": "alias1"
    }
}

  3. Validar el mapeo de alias: confirme que el valor del parámetro del reproductor («alias1") existe como clave en el mapeo ConfigurationAliases

  4. Pruebe con una configuración sencilla: comience con una configuración mínima para aislar el problema

  5. Supervise las respuestas a los errores: compruebe las respuestas MediaTailor de error para ver si hay mensajes de validación específicos

  6. Verificar resuelto URLs: confirme que las resoluciones finales URLs son válidas y accesibles

Prácticas recomendadas para los alias de configuración

Siga estas prácticas recomendadas para garantizar una implementación fiable de los alias de configuración.

Consideraciones de seguridad

Implemente las siguientes medidas de seguridad cuando utilice los alias de configuración:

  • Validación de entrada: valida todos los valores de los parámetros del reproductor antes de usarlos en la resolución de alias

  • Saneamiento de los valores de alias: asegúrese de que los valores de alias contengan solo los caracteres y formatos esperados

  • Restricciones de dominio: limite los alias de dominio a dominios controlados y de confianza

  • Control de acceso: restrinja la modificación de la configuración únicamente al personal autorizado

Optimización del rendimiento

Optimice el rendimiento de los alias de configuración con estas recomendaciones:

  • Minimice el recuento de alias: utilice solo los alias necesarios para reducir la sobrecarga de procesamiento

  • Nomenclatura eficiente: utilice convenciones de nomenclatura claras y coherentes para los alias y los parámetros

  • Valores predeterminados: proporcione alias predeterminados razonables para los casos de uso comunes

  • Almacenamiento en caché de la configuración: aproveche el almacenamiento en caché MediaTailor de la configuración para mejorar el rendimiento

Mantenimiento y supervisión

Mantenga operaciones de alias de configuración confiables con estas prácticas:

  • Validación periódica: valide periódicamente que todas las asignaciones de alias estén actualizadas y funcionen

  • Supervisión de errores: supervise los errores de HTTP 400 relacionados con alias faltantes o no válidos

  • Documentación: mantenga una documentación clara de todas las asignaciones de alias y sus propósitos

  • Procedimientos de prueba: Implemente pruebas exhaustivas para todas las combinaciones de alias

Para obtener más información sobre el uso de variables dinámicas de dominio, sesión y reproductor, seleccione el tema correspondiente.

Temas