View a markdown version of this page

Guide de démarrage rapide des fonctions - AWS Elemental MediaTailor
Conditions préalablesÉtape 1 : Création d’une fonctionÉtape 2 : associer la fonction à une configuration de lectureÉtape 3 : démarrer une session et vérifier que la fonction a été exécutéeQue se passe-t-il dans les coulissesSujets suggérés

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.

Guide de démarrage rapide des fonctions

Ce guide vous explique comment créer votre première fonction, l'associer à une configuration de lecture et vérifier qu'elle fonctionne. À la fin, vous disposerez d'une fonction fonctionnelle qui classe le type d'appareil (ctvmobile, oudesktop) de chaque spectateur et le stocke en tant que paramètre de lecteur disponible dans chaque demande ADS.

Conditions préalables

Avant de commencer, assurez-vous de disposer d'une configuration de MediaTailor lecture existante. Si vous n'en avez pas, veuillez consulter Commencer avec MediaTailor.

Étape 1 : Création d’une fonction

Au cours de cette étape, vous allez créer une fonction qui classe le type d'appareil du spectateur en fonction de la chaîne de l'agent utilisateur et stocke le résultat dans les paramètres du lecteur. La fonction utilise un type de sortie personnalisé (aucun appel d'API externe) avec une JSONataréférence d'expression expression pour évaluer l'agent utilisateur.

  1. Ouvrez la console MediaTailor.

  2. Dans le volet de navigation, choisissez Fonctions.

  3. Choisissez Créer une fonction.

  4. Dans le mode de l'assistant de création, sélectionnez Créer à partir de zéro, puis choisissez Continuer.

  5. Sous Type de fonction, sélectionnez la vignette de sortie personnalisée.

  6. Dans Détails de la fonction, entrez les informations suivantes :

    • ID de fonction  : myFirstFunction

    • Description : Classify device type from user agent

  7. Sous Configuration de sortie personnalisée, dans la section Sortie, ajoutez une ligne :

    • Clé : player_params.deviceType

    • Value (Valeur) : {% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}

  8. Choisissez Créer une fonction.

Une notification de réussite confirme que la fonction a été créée et vous êtes redirigé vers la page des détails de la fonction.

La configuration des fonctions qui en résulte est la suivante :

{
    "FunctionId": "myFirstFunction",
    "FunctionType": "CUSTOM_OUTPUT",
    "Description": "Classify device type from user agent",
    "CustomOutputConfiguration": {
        "Runtime": "JSONATA",
        "Output": {
            "player_params.deviceType": "{% $contains(session.user_agent, 'CTV') ? 'ctv' : $contains(session.user_agent, 'Mobile') ? 'mobile' : 'desktop' %}"
        }
    }
}

Étape 2 : associer la fonction à une configuration de lecture

Associez la fonction à un élément du cycle de vie de votre configuration de lecture. Le mappage indique MediaTailor quand exécuter la fonction.

  1. Dans le volet de navigation, choisissez Configurations.

  2. Choisissez la configuration de lecture que vous souhaitez mettre à jour.

  3. Choisissez Modifier.

  4. Développez la section Configuration des fonctions.

  5. Pour le hook d'initialisation de session, sélectionnez dans myFirstFunction la liste déroulante.

  6. Choisissez Enregistrer.

Cela se rattache myFirstFunction au hook du Pre-session initialisation cycle de vie. Le mappage des fonctions qui en résulte est le suivant :

{
    "FunctionMapping": {
        "PRE_SESSION_INITIALIZATION": "myFirstFunction"
    }
}

MediaTailor exécute la fonction une fois au début de chaque nouvelle session sur cette configuration de lecture.

Étape 3 : démarrer une session et vérifier que la fonction a été exécutée

Démarrez une nouvelle session de lecture pour activer la fonction. Envoyez une demande d'initialisation de session au point de terminaison d'initialisation de session de votre configuration de lecture.

MediaTailor publie automatiquement des CloudWatch métriques pour chaque exécution de fonction, aucun opt-in n'est requis. Après avoir démarré une session, vérifiez les métriques suivantes dans l'AWS/MediaTailorespace de noms pour confirmer que votre fonction a été exécutée :

  • PreSessionInitHook.Invocations— Confirme que l'hameçon a été tiré.

  • PreSessionInitHook.Errors— Doit être égal à 0 si la fonction a réussi.

  • Function.Invocations— Confirme la fonction individuelle exécutée. Cette métrique inclut FunctionIdFunctionType, et des HookType dimensions afin que vous puissiez filtrer de myFirstFunction manière spécifique.

Si la fonction échoue, MediaTailor envoie les événements du journal des erreurs vers Manifest Logs par défaut (aucune configuration n'est requise) :

  • PRE_SESSION_INIT_HOOK_ERROR— Hook-level échec avec errorType etcause.

  • PRE_SESSION_INIT_FUNCTION_ERROR— Function-level échec concernant les détails spécifiques functionId et les informations relatives à l'erreur.

L'exemple suivant illustre un PRE_SESSION_INIT_FUNCTION_ERROR événement lié à une erreur de syntaxe dans l'expression de la fonction :

{
    "eventTimestamp": "2024-01-01T12:00:00.076000000Z",
    "eventType": "PRE_SESSION_INIT_FUNCTION_ERROR",
    "eventDescription": "Function execution failed",
    "awsAccountId": "123456789012",
    "originId": "my-config",
    "sessionId": "session-123",
    "requestId": "req-abc",
    "eventId": "5dc6f040-0f72-4e8c-a64e-25eeef62708c",
    "functionId": "myFirstFunction",
    "functionType": "CUSTOM_OUTPUT",
    "executionTimeMs": 2,
    "errorType": "SYNTAX_ERROR",
    "cause": "Expected \")\" before end of expression",
    "input": {}
}

Utilisez ce eventId champ pour corréler les événements d'erreur de hook et de fonction pour la même exécution. Le errorType champ indique la classe de défaillance. Consultez Dépannage et surveillance la liste complète des types d'erreurs et des solutions.

Note

Pour une journalisation détaillée des réussites, inscrivez-vous à la configuration de votre journal des manifestes PRE_SESSION_INIT_HOOK_SUMMARY et inscrivez-vous aux PRE_SESSION_INIT_FUNCTION_COMPLETED événements. Les événements récapitulatifs indiquent le résultat du hook pour chaque exécution. Les événements terminés affichent les request/response informations d'entrée, de sortie et HTTP de chaque fonction. Ils sont désactivés par défaut pour minimiser les coûts de journalisation. Pour de plus amples informations, veuillez consulter Dépannage et surveillance.

Que se passe-t-il dans les coulisses

Voici le flux de demande complet pour la fonction que vous venez de créer :

  1. Le joueur lance une session avec MediaTailor.

  2. MediaTailor déclenche le hook PRE_SESSION_INITIALIZATION du cycle de vie et s'exécutemyFirstFunction.

  3. La fonction évalue le session.user_agent champ et écrit ctvmobile, ou desktop surplayer_params.deviceType.

  4. MediaTailor crée la session et renvoie le manifeste au joueur.

  5. Le joueur rencontre une pause publicitaire pendant la lecture.

  6. MediaTailor déclenche le hook PRE_ADS_REQUEST du cycle de vie, puis construit la demande ADS. Comme il deviceType est stocké dans les paramètres du joueur, il peut être inclus dans l'URL de la demande ADS par substitution dynamique de variables.

  7. L'ADS utilise le type d'appareil pour renvoyer des créations publicitaires ciblées.

  8. MediaTailor insère les publicités dans le manifeste et le renvoie au joueur.

Si la fonction échoue pour une raison quelconque, MediaTailor supprime la sortie et procède comme si aucune fonction n'était attachée. Le spectateur voit toujours des publicités, mais sans le ciblage par type d'appareil.

Sujets suggérés

Vous disposez désormais d'une fonction fonctionnelle associée à une configuration de lecture. À partir de là :