MediaTailor variables publicitaires dynamiques - AWS Elemental MediaTailor
MediaTailor référence de paramètreMediaTailor alias de configurationMediaTailor transmission de paramètres ADSMediaTailorrésolution des problèmes liés aux alias

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

MediaTailor variables publicitaires dynamiques

AWS Elemental MediaTailor une demande adressée au serveur de décision publicitaire (ADS) inclut des informations sur la session de visionnage en cours. Ces informations aident l'ADS à choisir les meilleures annonces à fournir dans sa réponse. Lorsque vous configurez le modèle ADS dans votre MediaTailor configuration, vous pouvez inclure des variables dynamiques, également appelées macros. Les variables dynamiques sont des chaînes remplaçables.

Les variables dynamiques peuvent prendre les formes suivantes :

  • Valeurs statiques : valeurs qui ne changent pas d'une session à l'autre. Par exemple, le type de réponse que MediaTailor attend du serveur ADS.

  • Variables de domaine : variables dynamiques pouvant être utilisées pour les domaines URL, telles que la partie my-ads-server.com de l'URL http ://my-ads-server.com. Pour en savoir plus, consultez MediaTailor variables de domaine.

  • Données de session : valeurs dynamiques fournies par MediaTailor chaque session, par exemple l'ID de session. Pour en savoir plus, consultez MediaTailor variables de session.

  • Données du joueur : valeurs dynamiques fournies par le joueur pour chaque session. Ils décrivent le lecteur de contenu et aident l'ADS à déterminer quelles publicités MediaTailor doivent être intégrées au flux. Pour en savoir plus, consultez MediaTailor variables du joueur.

MediaTailor référence et limites des paramètres

AWS Elemental MediaTailor fournit des informations complètes sur les restrictions de caractères des paramètres, les limites de longueur et les formats pris en charge pour les paramètres de requête du manifeste et les paramètres ADS.

Restrictions relatives aux caractères des paramètres de requête manifeste

Les paramètres de requête du manifeste prennent en charge des caractères spécifiques et ont des limites de longueur définies.

Caractères pris en charge (sans codage d'URL)

Vous pouvez utiliser les caractères suivants directement dans les paramètres de requête du manifeste :

  • Caractères alphanumériques (A-Z, a-z, 0-9)

  • Périodes (.)

  • Tirets (-)

  • Soulignements (_)

  • Barres obliques inversées (\)

Caractères pris en charge avec encodage URL

Les caractères spéciaux suivants sont pris en charge lorsqu'ils sont codés en URL :

  • période (.) = %2E

  • tiret (-) = %2D

  • trait de soulignement (_) = %5F

  • pourcentage (%) = %25

  • tilde (~) = %7E

  • barre oblique (/) = %2F

  • astérisque (*) = %2A

  • est égal à (=) = %3D

  • une question (?) = 3 %F

Support du codage d'URL

MediaTailor prend en charge le signe du pourcentage (%) lorsque vous l'utilisez dans le codage d'URL (par exemple, hello%20world = hello world). Vous pouvez utiliser n'importe quel caractère codé en URL, à condition qu'il s'agisse d'encodages d'URL valides conformément à la spécification HTTP.

Personnages non pris en charge

Vous ne pouvez pas utiliser les caractères suivants dans les paramètres de requête du manifeste sans codage URL ::,?,,&, =%, / (barre oblique).

Important

MediaTailor ne prend pas en charge les caractères doubles tels que%%% ou ==. Vous ne pouvez pas utiliser la valeur complète URLs comme valeur de paramètre de requête manifeste en raison des restrictions de caractères.

Limites de longueur

La longueur totale de tous les paramètres de requête du manifeste (clés et valeurs combinées) ne doit pas dépasser 2 000 caractères.

Limites de longueur des paramètres ADS

Les limites de longueur suivantes s'appliquent aux paramètres utilisés dans les demandes adressées à l'ADS :

  • Nom du paramètre ADS : 10 000 caractères maximum

  • Valeur du paramètre ADS : 25 000 caractères maximum

  • URL ADS : 25 000 caractères maximum

MediaTailor alias de configuration et remplacement dynamique des variables

AWS Elemental MediaTailor les alias de configuration permettent le remplacement dynamique des variables dans les domaines URL et autres champs pris en charge. Utilisez cette fonctionnalité pour utiliser plusieurs domaines et effectuer une configuration dynamique URLs lors de l'initialisation de la session.

Champs pris en charge pour le remplacement dynamique des variables

Vous pouvez utiliser des variables dynamiques dans les champs de configuration suivants :

  • VideoContentSourceUrl

  • AdDecisionServerUrl

  • LivePreroll.AdDecisionServerUrl

  • AdSegmentUrlPrefix

  • ContentSegmentUrlPrefix

  • TranscodeProfileName

  • SlateAdUrl

  • StartUrl

  • EndUrl

Règles relatives aux paramètres au niveau du domaine

Lorsque vous utilisez des variables dynamiques dans des parties de domaine de URLs, les restrictions suivantes s'appliquent :

  • Toutes les variables dynamiques utilisées dans les domaines doivent être spécifiées comme ConfigurationAliases

  • Ne peut être que player_params

  • La liste des valeurs aliasées doit être exhaustive

  • Les alias non valides ou manquants entraînent des erreurs HTTP 400

ConfigurationAliases Structure des paramètres de l'API

Le ConfigurationAliases paramètre utilise la structure JSON suivante : 

{
    "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"
        }
    }
}
Cohérence des API

playerParamsest désormais pris en charge comme alternative ads et adsParams pour améliorer la cohérence des API.

Comportement de secours en cas d'alias manquants

Lorsque les alias de configuration sont introuvables ou ne sont pas valides, MediaTailor implémente le comportement de secours suivant :

  • Variables de domaine : si un alias de variable de domaine est manquant ou non valide, la demande échoue avec le code d'état HTTP 400. Des alias valides doivent être définis pour toutes les variables de domaine.

  • Variables non liées au domaine : pour les variables utilisées dans des parties non liées au domaine de URLs (telles que les éléments de chemin ou les paramètres de requête), les alias manquants entraînent le remplacement de chaînes vides.

  • Validation de la configuration : MediaTailor vérifie que tous les alias requis sont présents lors des opérations de création et de mise à jour de la configuration.

Cas d'utilisation multiconfiguration avancés

Les alias de configuration permettent d'utiliser des architectures multiconfigurations sophistiquées pour les scénarios suivants :

Exemple Configuration complète avec alias

L'exemple suivant montre une configuration complète qui inclut des alias de configuration et des variables de domaine dynamiques : 

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"
        }
    }
}
Exemple Initialisation de session avec des alias

À l'aide de la configuration précédente, créez une demande d'initialisation de session en spécifiant les variables et alias du joueur : 

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"
    }
}
Exemple Flux de traitement des paramètres

MediaTailor remplace les chaînes d'alias par les valeurs mappées dans les alias de configuration. Le traitement donne lieu aux demandes suivantes :

  • Demande ADS :

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

  • VideoContentSource demande :

    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 transmission de paramètres à l'ADS

AWS Elemental MediaTailor prend en charge la configuration de variables dynamiques dans les MediaTailor demandes adressées à l'ADS en suivant les étapes suivantes.

Méthodes d'initialisation de session

MediaTailor prend en charge plusieurs méthodes d'initialisation de session et de transmission de paramètres :

  1. POST avec le corps de la requête :

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

  2. Paramètres de requête dans l'URL :

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

Vous ne pouvez spécifier les paramètres qu'une seule fois, au moment de l'initialisation. Les alias de configuration sont résolus en valeurs réelles avant le transfert.

Pour transmettre les informations de session et de lecteur au serveur ADS

  1. Collaborez avec l'ADS pour déterminer les informations dont il a besoin pour répondre à une requête publicitaire provenant de celui-ci AWS Elemental MediaTailor.

  2. Créez une configuration MediaTailor qui utilise un modèle d'URL de demande ADS qui répond aux exigences ADS. Dans l'URL, incluez les paramètres statiques et les espaces réservés correspondant aux paramètres dynamiques. Entrez l'URL de votre modèle dans le champ Ad decision server (Serveur ADS) de la configuration.

    Dans l'exemple suivant d'URL du modèle correlation fournit les données de session et deviceType fournit des données de lecteur : 

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

  3. Sur le joueur, configurez la demande d'initiation de session pour que AWS Elemental MediaTailor fournisse les paramètres pour les données de lecteur. Incluez vos paramètres dans la demande d'initiation de session et omettez-les des demandes suivantes pour la session.

    Le type d'appel effectué par le joueur pour initialiser la session détermine si le joueur (client) ou MediaTailor (serveur) fournit des rapports de suivi publicitaire pour la session. Pour plus d'informations sur ces deux options, consultez la section Signalement des données de suivi et .

    Effectuez l'une des types suivants d'appels, selon que vous voulez un rapport de suivi publicitaire côté serveur ou côté client. Dans les deux exemples d'appels, userID est destiné au serveur ADS et auth_token à l'origine :

    • (Option) Demandez des rapports de suivi des publicités côté serveur — Préfixez les paramètres que vous souhaitez envoyer MediaTailor à l'ADS. ads Conservez le préfixe désactivé pour les paramètres que MediaTailor doit envoyer au serveur d'origine :

      Les exemples suivants montrent les demandes entrantes adressées à HLS et DASH à AWS Elemental MediaTailor. MediaTailor utilise le deviceType dans sa demande à l'ADS et auth_token dans sa demande au serveur d'origine.

      Exemple HLS :

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

      Exemple DASH :

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

    • (Option) Demandez des rapports de suivi des publicités côté client — Fournissez les paramètres de l'ADS à l'intérieur d'un objet. adsParams

      Exemple HLS :

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

      Exemple DASH :

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

Lorsque le joueur lance une session, il AWS Elemental MediaTailor remplace les variables du modèle d'URL de demande ADS par les données de session et les ads paramètres du joueur. Il transmet les paramètres restants du lecteur au serveur d'origine.

Exemple MediaTailor demandes avec variables publicitaires

Les exemples suivants illustrent les appels à l'ADS et au serveur d'origine provenant d' AWS Elemental MediaTailor qui correspondent aux exemples d'appel d'initialisation de session de lecteur précédents :

  • MediaTailor appelle l'ADS avec les données de session et le type d'appareil du joueur : 

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

  • MediaTailor appelle le serveur d'origine avec le jeton d'autorisation du joueur.

    • Exemple HLS :

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

    • Exemple DASH :

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

Utilisation avancée

Vous pouvez personnaliser la demande ADS de multiples façons avec les données du lecteur et les données de session. Il vous suffit d'inclure le nom d'hôte ADS.

Les exemples suivants illustrent certaines façons de personnaliser votre demande :

  • Concaténez les paramètres du lecteur et les paramètres de session pour créer de nouveaux paramètres. Exemple : 

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

  • Utilisez un paramètre du lecteur comme partie intégrante d'un élément du chemin. Exemple : 

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

  • Utilisez les paramètres du lecteur pour transmettre les éléments du chemin d'accès et les clés elles-mêmes, plutôt que les seules valeurs. Exemple : 

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

MediaTailor résolution des problèmes liés aux alias de configuration

AWS Elemental MediaTailor fournit des conseils de dépannage systématiques pour les problèmes d'alias de configuration courants et les scénarios d'erreur.

Erreurs de validation des alias de configuration

Lorsque les alias de configuration sont manquants ou non valides, MediaTailor renvoie des réponses d'erreur spécifiques pour aider à identifier le problème.

Scénarios d'erreur courants

Le tableau suivant décrit les erreurs d'alias de configuration courantes et leurs étapes de résolution :

Erreur Cause Résolution
HTTP 400 : alias de paramètre de joueur non valide La valeur du paramètre du joueur est introuvable dans ConfigurationAliases Vérifiez que la valeur du paramètre du joueur existe sous forme de clé dans le ConfigurationAliases mappage correspondant
HTTP 400 : alias de configuration requis manquant Variable de domaine utilisée sans ConfigurationAliases entrée correspondante Ajoutez le paramètre de joueur manquant à tous ConfigurationAliases les mappages d'alias requis
HTTP 400 : échec de la validation de la configuration ConfigurationAliases la structure est mal formée ou incomplète Validez la structure JSON et assurez-vous que toutes les variables de domaine ont des alias correspondants
Remplacement d'une chaîne vide dans URLs Alias de variable autre que le domaine introuvable Ajoutez un mappage d'alias manquant ou fournissez une valeur par défaut dans ConfigurationAliases
Liste de contrôle pour la validation

Utilisez la liste de contrôle suivante pour valider la configuration de vos alias de configuration :

  1. Couverture des variables de domaine : assurez-vous que toutes les variables utilisées dans les parties du domaine URLs ont des ConfigurationAliases entrées correspondantes

  2. Exhaustivité des alias : vérifiez que toutes les valeurs possibles des paramètres du joueur sont incluses sous forme de clés dans les mappages d'alias

  3. Structure JSON : vérifiez que le ConfigurationAliases JSON est correctement formaté et imbriqué

  4. Dénomination des paramètres : vérifiez que tous les paramètres du joueur utilisent le player_params. préfixe

  5. Cohérence des valeurs : assurez-vous que les valeurs des alias sont valides pour l'usage auquel elles sont destinées (noms de profilURLs, etc.)

Résolution des alias de configuration de débogage

Suivez cette approche systématique pour résoudre les problèmes de résolution des alias de configuration.

Step-by-step méthodologie de débogage

Procédez comme suit pour identifier et résoudre les problèmes liés aux alias de configuration :

Procédure de débogage des alias de configuration

  1. Vérifiez la structure de configuration : vérifiez que votre configuration de lecture inclut un formatage correct ConfigurationAliases

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

  2. Vérifiez le format des paramètres du lecteur : assurez-vous que l'initialisation de la session inclut les paramètres du lecteur correctement formatés

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

  3. Valider le mappage des alias : vérifiez que la valeur du paramètre du joueur (« alias1 ») existe sous forme de clé dans le mappage ConfigurationAliases

  4. Test avec une configuration simple : commencez par une configuration minimale pour isoler le problème

  5. Surveiller les réponses aux erreurs : vérifiez les réponses aux MediaTailor erreurs pour des messages de validation spécifiques

  6. Vérifier la résolution URLs : confirmez que les résolutions finales URLs sont valides et accessibles

Meilleures pratiques en matière d'alias de configuration

Suivez ces bonnes pratiques pour garantir une implémentation fiable des alias de configuration.

Considérations sur la sécurité

Mettez en œuvre les mesures de sécurité suivantes lorsque vous utilisez des alias de configuration :

  • Validation des entrées : validez toutes les valeurs des paramètres du joueur avant de les utiliser dans la résolution des alias

  • Nettoyage des valeurs d'alias : assurez-vous que les valeurs d'alias contiennent uniquement les caractères et les formats attendus

  • Restrictions de domaine : limitez les alias de domaine aux domaines fiables et contrôlés

  • Contrôle d'accès : limiter les modifications de configuration au personnel autorisé uniquement

Optimisation des performances

Optimisez les performances des alias de configuration à l'aide des recommandations suivantes :

  • Minimiser le nombre d'alias : utilisez uniquement les alias nécessaires pour réduire la charge de traitement

  • Nommage efficace : utilisez des conventions de dénomination claires et cohérentes pour les alias et les paramètres

  • Valeurs par défaut : fournissez des alias par défaut adaptés aux cas d'utilisation courants

  • Mise en cache de configuration : Tirez parti MediaTailor de la mise en cache de configuration pour améliorer les performances

Maintenance et surveillance

Maintenez des opérations d'alias de configuration fiables grâce aux pratiques suivantes :

  • Validation régulière : vérifiez régulièrement que tous les mappages d'alias sont à jour et fonctionnels

  • Surveillance des erreurs : surveillez les erreurs HTTP 400 liées à des alias manquants ou non valides

  • Documentation : Conservez une documentation claire de tous les mappages d'alias et de leurs objectifs

  • Procédures de test : mise en œuvre de tests complets pour toutes les combinaisons d'alias

Pour plus d'informations sur l'utilisation de variables dynamiques de domaine, de session et de joueur, sélectionnez la rubrique appropriée.

Rubriques