MediaTailor variáveis de anúncios dinâmicas - AWS Elemental MediaTailor
MediaTailor referência de parâmetrosMediaTailor aliases de configuraçãoMediaTailor passando parâmetros do ADSMediaTailoraliases de solução de problemas

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á.

MediaTailor variáveis de anúncios dinâmicas

AWS Elemental MediaTailor uma solicitação ao servidor de decisão de anúncios (ADS) inclui informações sobre a sessão de visualização atual. Essas informações ajudam o ADS a escolher os melhores anúncios para fornecer em sua resposta. Ao configurar o modelo ADS em sua MediaTailor configuração, você pode incluir variáveis dinâmicas, também conhecidas como macros. Variáveis dinâmicas são cadeias de caracteres substituíveis.

As variáveis dinâmicas podem assumir as seguintes formas:

  • Valores estáticos — Valores que não mudam de uma sessão para outra. Por exemplo, o tipo de resposta esperado pelo MediaTailor do ADS.

  • Variáveis de domínio — Variáveis dinâmicas que podem ser usadas para domínios de URL, como a parte my-ads-server.com da URL http://my-ads-server.com. Para obter detalhes, consulte MediaTailor variáveis de domínio.

  • Dados da sessão — valores dinâmicos fornecidos por MediaTailor para cada sessão, por exemplo, o ID da sessão. Para obter detalhes, consulte MediaTailor variáveis de sessão.

  • Dados do jogador — Valores dinâmicos que são fornecidos pelo jogador em cada sessão. Eles descrevem o visualizador do conteúdo e ajudam o ADS a determinar quais anúncios MediaTailor devem ser incluídos no stream. Para obter detalhes, consulte MediaTailor variáveis do jogador.

MediaTailor referência e limitações de parâmetros

AWS Elemental MediaTailor fornece informações abrangentes sobre restrições de caracteres de parâmetros, limitações de comprimento e formatos compatíveis tanto para parâmetros de consulta de manifesto quanto para parâmetros ADS.

Restrições de caracteres do parâmetro de consulta manifesto

Os parâmetros de consulta do manifesto oferecem suporte a caracteres específicos e têm limitações de comprimento definidas.

Caracteres compatíveis (sem codificação de URL)

Você pode usar os seguintes caracteres diretamente nos parâmetros de consulta do manifesto:

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

  • Períodos (.)

  • Hífens (-)

  • Sublinha (_)

  • Barras invertidas (\)

Caracteres compatíveis com codificação de URL

Os seguintes caracteres especiais são suportados quando codificados por URL:

  • período (.) = %2E

  • traço (-) = %2D

  • sublinhado (_) = %5F

  • por cento (%) = %25

  • tilde (~) = %7E

  • barra para frente (/) = %2F

  • asterisco (*) = %2A

  • é igual a (=) = %3D

  • pergunta (?) = %3F

Suporte para codificação de URL

MediaTailor suporta o sinal de porcentagem (%) quando você o usa na codificação de URL (por exemplo, hello%20world = hello world). Você pode usar qualquer caractere codificado em URL, desde que sejam codificações de URL válidas de acordo com a especificação HTTP.

Caracteres não suportados

Você não pode usar os seguintes caracteres nos parâmetros de consulta do manifesto sem a codificação de URL::,,,?, & =%, / (barra invertida).

Importante

MediaTailor não suporta caracteres duplos, como%%% ou ==. Você não pode usar full URLs como valores de parâmetros de consulta de manifesto devido a restrições de caracteres.

Limitações de comprimento

O tamanho total de todos os parâmetros de consulta do manifesto (chaves e valores combinados) não deve exceder 2.000 caracteres.

Limitações de comprimento do parâmetro ADS

As seguintes limitações de comprimento se aplicam aos parâmetros usados nas solicitações ao ADS:

  • Nome do parâmetro ADS: máximo de 10.000 caracteres

  • Valor do parâmetro ADS: máximo de 25.000 caracteres

  • URL do ADS: máximo de 25.000 caracteres

MediaTailor aliases de configuração e substituição dinâmica de variáveis

AWS Elemental MediaTailor os aliases de configuração permitem a substituição dinâmica de variáveis em domínios de URL e outros campos compatíveis. Use esse recurso para usar vários domínios e configurar dinamicamente URLs durante a inicialização da sessão.

Campos compatíveis para substituição dinâmica de variáveis

Você pode usar variáveis dinâmicas nos seguintes campos de configuração:

  • VideoContentSourceUrl

  • AdDecisionServerUrl

  • LivePreroll.AdDecisionServerUrl

  • AdSegmentUrlPrefix

  • ContentSegmentUrlPrefix

  • TranscodeProfileName

  • SlateAdUrl

  • StartUrl

  • EndUrl

Regras de parâmetros em nível de domínio

Quando você usa variáveis dinâmicas em partes do domínio URLs, as seguintes restrições se aplicam:

  • Todas as variáveis dinâmicas usadas em domínios devem ser especificadas como ConfigurationAliases

  • Só pode ser player_params

  • A lista de valores com alias deve ser exaustiva

  • Aliases inválidos ou ausentes resultam em erros HTTP 400

ConfigurationAliases Estrutura de parâmetros da API

O ConfigurationAliases parâmetro usa a seguinte estrutura 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"
        }
    }
}
Consistência da API

playerParamsagora é suportado como uma alternativa ads e adsParams para melhorar a consistência da API.

Comportamento alternativo para aliases ausentes

Quando os aliases de configuração não são encontrados ou são inválidos, MediaTailor implementa o seguinte comportamento de fallback:

  • Variáveis de domínio: se um alias de variável de domínio estiver ausente ou for inválido, a solicitação falhará com o código de status HTTP 400. Todas as variáveis de domínio devem ter aliases válidos definidos.

  • Variáveis que não são de domínio: para variáveis usadas em partes que não são de domínio URLs (como elementos de caminho ou parâmetros de consulta), aliases ausentes resultam na substituição de uma string vazia.

  • Validação de configuração: MediaTailor valida se todos os aliases necessários estão presentes durante as operações de criação e atualização da configuração.

Casos de uso avançados de várias configurações

Os aliases de configuração permitem arquiteturas sofisticadas de várias configurações para os seguintes cenários:

exemplo Configuração completa com aliases

O exemplo a seguir mostra uma configuração completa que inclui aliases de configuração e variáveis dinâmicas de domínio: 

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"
        }
    }
}
exemplo Inicialização da sessão com aliases

Usando a configuração anterior, crie uma solicitação de inicialização de sessão especificando as variáveis e os aliases do player: 

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"
    }
}
exemplo Fluxo de processamento de parâmetros

MediaTailor substitui as cadeias de caracteres de alias pelos valores mapeados nos aliases de configuração. O processamento resulta nas seguintes solicitações:

  • Solicitação de ADS:

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

  • VideoContentSource solicitação:

    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 passando parâmetros para o ADS

AWS Elemental MediaTailor suporta a configuração de variáveis dinâmicas em MediaTailor solicitações ao ADS usando as etapas a seguir.

Métodos de inicialização da sessão

MediaTailor suporta vários métodos para inicialização de sessão e passagem de parâmetros:

  1. POST com corpo de solicitação:

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

  2. Parâmetros de consulta no URL:

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

Você só pode especificar os parâmetros uma vez, no momento da inicialização. Os aliases de configuração são resolvidos para valores reais antes do encaminhamento.

Para passar informações de sessão e player ao ADS

  1. Trabalhe com o ADS para determinar as informações de que ele precisa para responder a uma consulta de anúncio AWS Elemental MediaTailor.

  2. Crie uma configuração MediaTailor que use um modelo de URL de solicitação do ADS que atenda aos requisitos do ADS. No URL, inclua parâmetros estáticos e espaços reservados para parâmetros dinâmicos. Digite o URL do modelo no campo Ad decision server (Servidor de decisões de anúncios) da configuração.

    No seguinte URL do modelo de exemplo, correlation fornece dados da sessão e deviceType fornece dados do player: 

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

  3. No player, configure a solicitação de iniciação da sessão para o AWS Elemental MediaTailor fornecer parâmetros para os dados do player. Inclua os parâmetros na solicitação de iniciação da sessão e os omita de solicitações subsequentes da sessão.

    O tipo de chamada que o jogador faz para inicializar a sessão determina se o jogador (cliente) ou MediaTailor (servidor) fornece relatórios de rastreamento de anúncios para a sessão. Para obter informações sobre essas duas opções, consulte Dados de relatórios e rastreamento .

    Faça um dos tipos de chamadas a seguir, dependendo do desejo de relatórios para o rastreamento de anúncios no lado do servidor ou do cliente. Em ambas as chamadas de exemplo, userID é desejado para o ADS e auth_token é desejado para a origem:

    • (Opção) Solicite relatórios de rastreamento de anúncios do lado do servidor — Prefixe os parâmetros com os quais você deseja enviar MediaTailor ao ADS. ads Deixe o prefixo desativado para parâmetros para os quais o MediaTailor deve enviar ao servidor de origem:

      Os exemplos a seguir mostram as solicitações recebidas de HLS e DASH para. AWS Elemental MediaTailor MediaTailor usa o deviceType em sua solicitação para o ADS e o auth_token em sua solicitação para o servidor de origem.

      Exemplo de HLS:

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

      Exemplo de DASH:

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

    • (Opção) Solicite relatórios de rastreamento de anúncios do lado do cliente — Forneça parâmetros para o ADS dentro de um objeto. adsParams

      Exemplo de HLS:

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

      Exemplo de DASH:

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

Quando o jogador inicia uma sessão, AWS Elemental MediaTailor substitui as variáveis no URL de solicitação do ADS modelo pelos dados da sessão e pelos parâmetros do ads jogador. Ele passa os parâmetros restantes do player para o servidor de origem.

exemplo MediaTailor solicitações com variáveis de anúncio

Os exemplos a seguir mostram as chamadas para o ADS e o servidor de origem do AWS Elemental MediaTailor que correspondem aos exemplos de chamada de inicialização de sessão do player anterior:

  • MediaTailor chama o ADS com os dados da sessão e o tipo de dispositivo do jogador: 

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

  • MediaTailor chama o servidor de origem com o token de autorização do jogador.

    • Exemplo de HLS:

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

    • Exemplo de DASH:

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

Uso avançado

Personalize a solicitação ADS de muitas maneiras com dados do player e da sessão. Você só precisa incluir o nome do host do ADS.

Os exemplos a seguir mostram algumas das maneiras de personalizar a solicitação:

  • Concatene os parâmetros do player e da sessão para criar novos parâmetros. Exemplo: 

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

  • Use um parâmetro de player como parte de um elemento do caminho. Exemplo:

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

  • Use os parâmetros do player para passar ambos os elementos de caminho e as chaves propriamente ditas, e não apenas valores. Exemplo: 

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

MediaTailor solução de problemas de aliases de configuração

AWS Elemental MediaTailor fornece orientação sistemática de solução de problemas de aliases de configuração e cenários de erro.

Erros de validação do alias de configuração

Quando os aliases de configuração estão ausentes ou são inválidos, MediaTailor retorna respostas de erro específicas para ajudar a identificar o problema.

Cenários de erro comuns

A tabela a seguir descreve erros comuns de alias de configuração e suas etapas de resolução:

Erro Causa Resolução
HTTP 400: alias de parâmetro de jogador inválido Valor do parâmetro do jogador não encontrado em ConfigurationAliases Verifique se o valor do parâmetro do player existe como uma chave no ConfigurationAliases mapeamento correspondente
HTTP 400: Falta o alias de configuração necessário Variável de domínio usada sem ConfigurationAliases entrada correspondente Adicione o parâmetro do player ausente a ConfigurationAliases com todos os mapeamentos de aliases necessários
HTTP 400: falha na validação da configuração ConfigurationAliases a estrutura está malformada ou incompleta Valide a estrutura JSON e garanta que todas as variáveis de domínio tenham aliases correspondentes
Substituição de string vazia em URLs Alias de variável não pertencente ao domínio não encontrado Adicione o mapeamento de aliases ausente ou forneça o valor padrão em ConfigurationAliases
Lista de verificação de validação

Use a lista de verificação a seguir para validar sua configuração de aliases:

  1. Cobertura de variáveis de domínio: garanta que todas as variáveis usadas em partes do domínio URLs tenham ConfigurationAliases entradas correspondentes

  2. Completude do alias: verifique se todos os valores possíveis dos parâmetros do jogador estão incluídos como chaves nos mapeamentos de aliases

  3. Estrutura JSON: valide se o ConfigurationAliases JSON está devidamente formatado e aninhado

  4. Nomeação dos parâmetros: confirme se todos os parâmetros do player usam o prefixo player_params.

  5. Consistência de valores: garanta que os valores de alias sejam válidos para o uso pretendido (URLs, nomes de perfil etc.)

Resolução de alias de configuração de depuração

Siga essa abordagem sistemática para depurar problemas de resolução de aliases de configuração.

Step-by-step metodologia de depuração

Use as etapas a seguir para identificar e resolver problemas de alias de configuração:

Procedimento de depuração de alias de configuração

  1. Verifique a estrutura de configuração: confirme se sua configuração de reprodução inclui a formatação adequada ConfigurationAliases

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

  2. Verifique o formato dos parâmetros do player: certifique-se de que a inicialização da sessão inclua parâmetros do player formatados corretamente

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

  3. Validar o mapeamento de alias: confirme se o valor do parâmetro do jogador (“alias1") existe como uma chave no mapeamento ConfigurationAliases

  4. Teste com configuração simples: comece com uma configuração mínima para isolar o problema

  5. Monitore respostas de erro: verifique as respostas MediaTailor de erro para mensagens de validação específicas

  6. Verificar se os resolvidos foram confirmados URLs: confirme se URLs os resolvidos finais são válidos e acessíveis

Melhores práticas de aliases de configuração

Siga essas práticas recomendadas para garantir a implementação confiável do alias de configuração.

Considerações sobre segurança

Implemente as seguintes medidas de segurança ao usar aliases de configuração:

  • Validação de entrada: valide todos os valores dos parâmetros do jogador antes de usá-los na resolução de aliases

  • Limpeza do valor do alias: certifique-se de que os valores do alias contenham somente caracteres e formatos esperados

  • Restrições de domínio: limite os aliases de domínio a domínios confiáveis e controlados

  • Controle de acesso: restrinja a modificação da configuração somente ao pessoal autorizado

Otimização de desempenho

Otimize o desempenho do alias de configuração com estas recomendações:

  • Minimize a contagem de aliases: use somente os aliases necessários para reduzir a sobrecarga de processamento

  • Nomenclatura eficiente: use convenções de nomenclatura claras e consistentes para aliases e parâmetros

  • Valores padrão: forneça aliases padrão sensatos para casos de uso comuns

  • Cache de configuração: aproveite MediaTailor o cache de configuração para melhorar o desempenho

Manutenção e monitoramento

Mantenha operações confiáveis de alias de configuração com estas práticas:

  • Validação regular: valide periodicamente se todos os mapeamentos de aliases são atuais e funcionais

  • Monitoramento de erros: monitore erros de HTTP 400 relacionados a aliases ausentes ou inválidos

  • Documentação: mantenha uma documentação clara de todos os mapeamentos de aliases e suas finalidades

  • Procedimentos de teste: implemente testes abrangentes para todas as combinações de aliases

Para obter mais informações sobre o uso de variáveis dinâmicas de domínio, sessão e jogador, selecione o tópico aplicável.

Tópicos