View a markdown version of this page

Guia de início rápido do Functions - AWS Elemental MediaTailor
Pré-requisitosEtapa 1: criar uma função doEtapa 2: anexar a função a uma configuração de reproduçãoEtapa 3: iniciar uma sessão e verificar se a função foi executadaO que acontece nos bastidoresTópicos sugeridos

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Guia de início rápido do Functions

Este guia explica como criar sua primeira função, anexá-la a uma configuração de reprodução e verificar se ela foi executada. Ao final, você terá uma função funcional que classifica o tipo de dispositivo de cada espectador (ctv,mobile, oudesktop) e o armazena como um parâmetro de player disponível em cada solicitação do ADS.

Pré-requisitos

Antes de começar, verifique se você tem uma configuração de MediaTailor reprodução existente. Se você não tiver uma, consulte Começando com MediaTailor.

Etapa 1: criar uma função do

Nesta etapa, você cria uma função que classifica o tipo de dispositivo do visualizador com base na string do agente do usuário e armazena o resultado nos parâmetros do player. A função usa um tipo de saída personalizado (sem chamadas externas de API) com uma Referência de expressão JSonata expressão para avaliar o agente do usuário.

  1. Abra o MediaTailor console em https://console.aws.amazon.com/mediatailor/.

  2. Selecione Funções no painel de navegação.

  3. Escolha a opção Criar função.

  4. No modal do assistente de criação, selecione Criar do zero e escolha Continuar.

  5. Em Tipo de função, selecione o quadro de saída personalizada.

  6. Em Detalhes da função, insira o seguinte:

    • ID da função: myFirstFunction

    • Descrição: Classify device type from user agent

  7. Em Configuração de saída personalizada, na seção Saída, adicione uma linha:

    • Chave: player_params.deviceType

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

  8. Escolha a opção Criar função.

Uma notificação de sucesso confirma que a função foi criada e você será redirecionado para a página de detalhes da função.

A configuração da função resultante é:

{
    "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' %}"
        }
    }
}

Etapa 2: anexar a função a uma configuração de reprodução

Mapeie a função para um gancho de ciclo de vida em sua configuração de reprodução. O mapeamento informa MediaTailor quando executar a função.

  1. No painel de navegação, escolha Configurações.

  2. Escolha a configuração de reprodução que você deseja atualizar.

  3. Escolha Editar.

  4. Expanda a seção Configuração de funções.

  5. Para Gancho de inicialização da sessão, selecione no myFirstFunction menu suspenso.

  6. Escolha Salvar.

Isso se conecta myFirstFunction ao gancho do INICIALIZAÇÃO DA PRÉ-SESSÃO ciclo de vida. O mapeamento de funções resultante é:

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

MediaTailor executa a função uma vez no início de cada nova sessão nessa configuração de reprodução.

Etapa 3: iniciar uma sessão e verificar se a função foi executada

Inicie uma nova sessão de reprodução para acionar a função. Use uma solicitação de inicialização de sessão para o endpoint de inicialização de sessão da sua configuração de reprodução.

MediaTailor publica automaticamente CloudWatch métricas para cada execução de função, sem a necessidade de aceitação. Depois de iniciar uma sessão, verifique as seguintes métricas no AWS/MediaTailor namespace para confirmar se sua função foi executada:

  • PreSessionInitHook.Invocations— Confirma que o gancho foi acionado.

  • PreSessionInitHook.Errors— Deveria ser 0 se a função for bem-sucedida.

  • Function.Invocations— Confirma a função individual executada. Essa métrica incluiFunctionId,FunctionType, e HookType dimensões para que você possa filtrar myFirstFunction especificamente.

Se a função falhar, MediaTailor emite eventos de registro de erros para os registros manifestos por padrão (sem necessidade de configuração):

  • PRE_SESSION_INIT_HOOK_ERROR— Hook-level falha com errorType cause e.

  • PRE_SESSION_INIT_FUNCTION_ERROR— Function-level falha com os detalhes específicos functionId e do erro.

O exemplo a seguir mostra um PRE_SESSION_INIT_FUNCTION_ERROR evento para um erro de sintaxe na expressão da função:

{
    "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": {}
}

Use o eventId campo para correlacionar eventos de erro de gancho e função para a mesma execução. O errorType campo indica a classe da falha — consulte Solução de problemas e monitoramento para obter uma lista completa dos tipos e correções de erros.

nota

Para obter um registro detalhado de sucesso, opte por participar PRE_SESSION_INIT_HOOK_SUMMARY e participar de PRE_SESSION_INIT_FUNCTION_COMPLETED eventos na configuração do Registro de Manifestos. Eventos resumidos mostram o resultado final de cada execução. Os eventos concluídos mostram a entrada, a saída e request/response os detalhes HTTP de cada função. Eles são desativados por padrão para minimizar os custos de registro. Para obter mais informações, consulte Solução de problemas e monitoramento.

O que acontece nos bastidores

Aqui está o fluxo completo da solicitação para a função que você acabou de criar:

  1. O jogador inicia uma sessão com MediaTailor.

  2. MediaTailor dispara o gancho do PRE_SESSION_INITIALIZATION ciclo de vida e funciona. myFirstFunction

  3. A função avalia o session.user_agent campo e grava ctvmobile, ou desktop paraplayer_params.deviceType.

  4. MediaTailor cria a sessão e retorna o manifesto para o player.

  5. O player encontra uma pausa publicitária durante a reprodução.

  6. MediaTailor aciona o gancho do PRE_ADS_REQUEST ciclo de vida e, em seguida, constrói a solicitação ADS. Como deviceType está armazenado nos parâmetros do player, ele está disponível para inclusão no URL de solicitação do ADS por meio da substituição dinâmica de variáveis.

  7. O ADS usa o tipo de dispositivo para retornar anúncios criativos direcionados.

  8. MediaTailor junta os anúncios no manifesto e os devolve ao player.

Se a função falhar por algum motivo, MediaTailor descarta a saída e prossegue como se nenhuma função estivesse anexada. O espectador ainda vê anúncios, mas sem a segmentação por tipo de dispositivo.

Tópicos sugeridos

Agora você tem uma função funcional anexada a uma configuração de reprodução. A partir daqui: