Lista de verificação da REST API V2 rest-api-v2-checklist

Requisitos

Riscos

Use um aplicativo registrado com escopo REST API v2.

Riscos de acionamento de respostas de erro "Não autorizado" HTTP 401, sobrecarga de recursos do sistema e latência crescente.

Armazene as credenciais do cliente no armazenamento persistente e reutilize-as para cada solicitação de token de acesso.

Há risco de perda de autenticação quando as credenciais do cliente forem geradas novamente.

Armazene os tokens de acesso no armazenamento persistente e reutilize-os até que expirem.

Não solicite um novo token para cada chamada REST API v2. Atualize os tokens de acesso somente quando eles expirarem.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Requisitos

Riscos

Recupere a resposta de configuração somente quando for necessário solicitar que o usuário selecione o MVPD (provedor de TV) antes da Fase de autenticação.

Não há necessidade de recuperar a resposta da configuração quando:

• O usuário já está autenticado.
• O usuário recebe acesso temporário.
• A autenticação do usuário expirou, mas o usuário pode ser solicitado a confirmar que ainda é assinante do MVPD selecionado anteriormente.

Riscos de sobrecarga dos recursos do sistema e aumento da latência.

Armazene a seleção do provedor de TV por assinatura (MVPD) do usuário no armazenamento persistente para usá-la em todas as fases subsequentes:

• No armazenamento de resposta de configuração, o usuário selecionou MVPD "id".
• No armazenamento de resposta de configuração, o usuário selecionou "displayName" do MVPD.
• No armazenamento de resposta de configuração, o usuário selecionou "logoUrl" do MVPD.

Riscos de sobrecarga dos recursos do sistema e aumento da latência.

Requisitos

Riscos

Inicie o mecanismo de sondagem sob as seguintes condições:

Autenticação executada no aplicativo (tela) primário

• O aplicativo principal (streaming) deve iniciar o polling quando o usuário atingir a página de destino final, depois que o componente do navegador carregar o URL especificado para o parâmetro "redirectUrl" na solicitação de ponto de extremidade de sessões.

Autenticação executada em um aplicativo secundário (tela)

• O aplicativo principal (transmissão) deve iniciar o polling assim que o usuário iniciar o processo de autenticação, logo após receber a resposta do endpoint de sessões e exibir o código de autenticação ao usuário.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Pare o mecanismo de sondagem sob as seguintes condições:

Autenticação bem-sucedida

• As informações de perfil do usuário foram recuperadas com êxito, confirmando o status de autenticação. Portanto, a sondagem não é mais necessária.

Sessão de autenticação e expiração do código

• A sessão de autenticação e o código expiram, o usuário deve reiniciar o processo de autenticação e a pesquisa usando o código de autenticação anterior deve ser interrompida imediatamente.

Novo código de autenticação gerado

• Se o usuário solicitar um novo código de autenticação, a sessão existente será invalidada e a pesquisa usando o código de autenticação anterior deverá ser interrompida imediatamente.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Configure a frequência do mecanismo de sondagem nas seguintes condições:

Autenticação executada no aplicativo (tela) primário

• O aplicativo principal (transmissão) deve pesquisar a cada 3-5 segundos ou mais.

Autenticação executada em um aplicativo secundário (tela)

• O aplicativo principal (transmissão) deve pesquisar a cada 3-5 segundos.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Armazene partes das informações de perfil do usuário no armazenamento persistente para melhorar o desempenho e minimizar chamadas desnecessárias da API REST v2.

O armazenamento em cache deve se concentrar nos seguintes campos de resposta de perfis:

mvpd

• O aplicativo cliente pode usá-lo para rastrear o provedor de TV selecionado pelo usuário e continuar a usá-lo durante as Fases de Pré-autorização ou Autorização.
• Quando o perfil de usuário atual expira, o aplicativo cliente pode usar a seleção MVPD lembrada e solicitar a confirmação do usuário.

atributos

• Usado para personalizar a experiência do usuário com base em diferentes chaves de metadados de usuário (por exemplo, zip, maxRating etc.).
• Os metadados do usuário ficam disponíveis após a conclusão do fluxo de autenticação, portanto, o aplicativo cliente não precisa consultar um endpoint separado para recuperar as informações de metadados do usuário, pois já estão incluídas nas informações do perfil.
• Determinados atributos de metadados podem ser atualizados durante a fase de autorização, dependendo da MVPD (por exemplo, Estatuto) e do atributo de metadados específico (por exemplo, householdID). Como resultado, o aplicativo cliente pode precisar consultar as APIs de perfis novamente após a autorização para recuperar os metadados do usuário mais recentes.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Requisitos

Riscos

Use decisões de pré-autorização para filtragem de conteúdo e nunca para decisões de reprodução.

Riscos de violação de acordos contratuais entre programadores, MVPDs e Adobe.

Riscos ao ignorar nossos sistemas de monitoramento e alerta.

Manipule os códigos de erro aprimorados adequadamente e utilize o campo de ação para determinar as etapas de correção necessárias.

Somente um número limitado de códigos de erro aprimorados garante uma nova tentativa, enquanto a maioria requer resoluções alternativas, conforme especificado no campo de ação.

Verifique se qualquer mecanismo de repetição implementado para recuperar decisões de pré-autorização não resulta em um loop infinito e se ele limita as tentativas a um número razoável (ou seja, 2-3).

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

O cache bem-sucedido permite decisões na memória para melhorar o desempenho e minimizar chamadas desnecessárias da API REST v2, pois as atualizações de assinatura enquanto o aplicativo está em execução não são frequentes.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Requisitos

Riscos

Obter decisões de autorização antes da reprodução — independentemente se uma decisão de pré-autorização existe.

Permitir que os fluxos continuem sem interrupções mesmo que o token de mídia expire durante a reprodução e solicite uma nova decisão de autorização contendo um token de mídia (novo) quando o usuário fizer sua próxima solicitação de reprodução, independentemente de ser para o mesmo recurso ou para um diferente.

Os fluxos ao vivo executados por longos períodos podem optar por solicitar uma nova decisão de autorização após operações de vídeo, como pausar conteúdo, iniciar interrupções comerciais ou modificar configurações no nível do ativo quando o MRSS for alterado.

Riscos de violação de acordos contratuais entre programadores, MVPDs e Adobe.

Riscos ao ignorar nossos sistemas de monitoramento e alerta.

Manipule os códigos de erro aprimorados adequadamente e utilize o campo de ação para determinar as etapas de correção necessárias.

Somente um número limitado de códigos de erro aprimorados garante uma nova tentativa, enquanto a maioria requer resoluções alternativas, conforme especificado no campo de ação.

Certifique-se de que qualquer mecanismo de repetição implementado para recuperar decisões de autorização não resulte em um loop infinito e que limite as tentativas a um número razoável (ou seja, 2-3).

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Requisitos

Riscos

Implemente a API de logout para permitir que os usuários desconectem manualmente, encerrando seus perfis autenticados e seguindo o nome de ação da API REST v2 especificado para cada perfil removido:

• Para MVPDs que oferecem suporte a um endpoint de logout, o aplicativo cliente requer a navegação até o "url" fornecido em um user-agent.
• Para perfis do tipo "appleSSO", o aplicativo cliente exige que o oriente o usuário para também fazer logoff do nível do parceiro (configurações do sistema da Apple).

Há risco de mau funcionamento do aplicativo cliente devido à falta de suporte no lado do aplicativo cliente.

Requisitos

Riscos

Envie o cabeçalho Autorização para cada solicitação REST API v2.

Riscos de acionamento de respostas de erro "Não autorizado" HTTP 401, sobrecarga de recursos do sistema e latência crescente.

Envie o cabeçalho AP-Device-Identifier para cada solicitação REST API v2.

Mesmo quando a solicitação é originada de um servidor em nome de um dispositivo, o valor do cabeçalho AP-Device-Identifier deve refletir o identificador real do dispositivo de streaming.

Riscos de disparar respostas de erro HTTP 400 "Solicitação inválida", sobrecarregando os recursos do sistema e aumentando a latência.

Envie o cabeçalho X-Device-Info para cada solicitação REST API v2.

Mesmo quando a solicitação se origina de um servidor em nome de um dispositivo, o valor do cabeçalho X-Device-Info deve refletir as informações reais do dispositivo de streaming.

Os riscos são classificados como originários de uma plataforma desconhecida e tratados como inseguros, ficando sujeitos a regras mais restritivas, como TTLs de autenticação mais curtas.

Além disso, alguns campos, como o dispositivo de streaming connectionIp e connectionPort, são obrigatórios para recursos como Autenticação da Base Inicial do Spectrum.

Calcule e armazene um identificador de dispositivo estável que não é alterado nas atualizações ou reinicializações do cabeçalho AP-Device-Identifier.

Para plataformas sem um identificador de hardware, gere um identificador exclusivo a partir dos atributos do aplicativo e mantenha-o.

Há risco de perda de autenticação quando o identificador do dispositivo é alterado.

Verifique se você está enviando apenas os parâmetros e cabeçalhos esperados da REST API v2.

Riscos de disparar respostas de erro HTTP 400 "Solicitação inválida", sobrecarregando os recursos do sistema e aumentando a latência.

Requisitos

Riscos

Manipule os códigos de erro aprimorados adequadamente e utilize o campo de ação para determinar as etapas de correção necessárias.

Somente um número limitado de códigos de erro aprimorados garante uma nova tentativa, enquanto a maioria requer resoluções alternativas, conforme especificado no campo de ação.

A maioria dos códigos de erro aprimorados listados na documentação Códigos de Erro Aprimorados - REST API V2 pode ser totalmente evitada se manipulada corretamente durante a fase de desenvolvimento, antes de iniciar o aplicativo.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Há risco de mau funcionamento do aplicativo cliente devido à falta de tratamento dos códigos de erro aprimorados, causando mensagens de erro não claras, orientação incorreta do usuário ou comportamento de fallback incorreto.

Diferencie entre manipular respostas de erro HTTP (por exemplo, 400, 401, 403, 404, 405, 500) e respostas de sucesso (por exemplo, 200, 201) que contêm cargas de códigos de erro aprimorados, conforme discutido acima.

Somente um número limitado de códigos de erro HTTP garante uma nova tentativa, enquanto a maioria requer resoluções alternativas.

A maioria das respostas de erro HTTP pode ser totalmente evitada se manipulada corretamente durante a fase de desenvolvimento antes da inicialização do aplicativo.

Riscos de sobrecarga dos recursos do sistema, aumento da latência e possível acionamento de respostas de erro HTTP 429 "Muitas solicitações".

Há risco de mau funcionamento do aplicativo cliente devido à falta de tratamento dos códigos de erro aprimorados, causando mensagens de erro não claras, orientação incorreta do usuário ou comportamento de fallback incorreto.

Requisitos

Riscos

Desenvolva e teste o aplicativo usando os ambientes oficiais de não produção de Autenticação do Adobe Pass:

• Pré-produção
• Estágios de lançamento

Execute controle de qualidade (QA) completo nesses ambientes antes de iniciar a produção da versão.

Os aplicativos cliente não devem prosseguir para a Produção de Versão sem antes concluir a validação completa em ambientes que não sejam de produção.

Há riscos de lançamento com defeitos críticos e graves.

A falta de um caminho de depuração curto e eficiente pode impedir que o Suporte e a Engenharia da Adobe intervenham rapidamente.

Práticas

Riscos

Verifique proativamente a validade do token de acesso para atualizá-lo quando expirar.

Verifique se qualquer mecanismo de repetição para manipular erros "Não autorizados" do HTTP 401 atualiza primeiro o token de acesso antes de repetir a solicitação original.

Riscos de acionamento de respostas de erro "Não autorizado" HTTP 401, sobrecarga de recursos do sistema e latência crescente.

Práticas

Riscos

Armazene a resposta de configuração na memória ou no armazenamento persistente por um curto período de tempo (por exemplo, de 3 a 5 minutos) para melhorar o desempenho e minimizar chamadas REST API v2 desnecessárias.

Riscos de sobrecarga dos recursos do sistema e aumento da latência.

Práticas

Riscos

Valide o código de autenticação enviado por meio da entrada do usuário no aplicativo secundário (segunda) (tela) antes de chamar a API /api/v2/authenticate nas seguintes condições:

Autenticação executada no aplicativo secundário (tela) com mvpd pré-selecionado

• Use Retomar sessão de autenticação - POST /api/v2/{serviceProvider}/sessions/{code}

Autenticação executada no aplicativo secundário (tela) sem mvpd pré-selecionado

• Use Recuperar sessão de autenticação - GET /api/v2/{serviceProvider}/sessions/{code}

O aplicativo cliente receberia um erro se o código de autenticação fornecido fosse digitado incorretamente ou caso a sessão de autenticação expirasse.

Arrisca várias respostas de erro e problemas de fluxo de trabalho durante a autenticação.

Certifique-se de que o aplicativo cliente possa lidar com vários perfis, solicitando que o usuário selecione um perfil ou aplicando uma lógica personalizada, como selecionar automaticamente o perfil com o período de validade mais longo.

Há risco de mau funcionamento do aplicativo cliente devido à falta de suporte no lado do aplicativo cliente.

Suporte a fluxos não básicos, caso o negócio de aplicativos clientes exija:

• Fluxos de acesso degradados (recurso premium)
• Fluxos de acesso temporário (recurso premium)
• Fluxos de acesso de logon único (recurso padrão)

Corre o risco de criar uma experiência do usuário inferior à ideal.

Práticas

Riscos

Exiba feedback claro do usuário se uma decisão de pré-autorização for negada, usando as mensagens fornecidas por MVPDs ou Adobe por meio de códigos de erro aprimorados.

Corre o risco de criar uma experiência do usuário inferior à ideal.

Práticas

Riscos

Valide tokens de mídia usando a biblioteca Verificador de Token de Mídia.

Riscos de esquemas de fraude, como a extração de fluxo.

Exibir comentários claros do usuário se uma decisão de autorização for negada, usando as mensagens fornecidas por MVPDs ou Adobe por meio de códigos de erro aprimorados.

Corre o risco de criar uma experiência do usuário inferior à ideal.

Práticas

Riscos

Evite chamar a API de logout automaticamente (de forma programática) em cenários como pré-autorização ou autorização negada, pois a API de logout só deve ser invocada em resposta a uma solicitação direta do usuário.

Riscos de confusão do usuário quanto à falha da autenticação.

Práticas

Riscos

Reutilize o código da REST API v1 para calcular o identificador do dispositivo e as informações do dispositivo com ajustes secundários, mas verifique se você está enviando apenas os parâmetros e cabeçalhos esperados da REST API v2.

Reutilize o código da API REST v1 para chamar a API DCR e recuperar um token de acesso.

-

Práticas

Riscos

Verifique se os seguintes fluxos básicos foram testados em dispositivos e plataformas:

Fluxos de autenticação

• Cenário de autenticação do aplicativo primário (tela)
• Cenário de autenticação de aplicativo secundário (tela)

(Opcional) Fluxos de pré-autorização

• Cenário de decisões de licenciamento de teste
• Testar cenário de decisões de negação

Fluxos de autorização

• Cenário de decisões de licenciamento de teste
• Testar cenário de decisões de negação

Fluxos de logout

Além disso, teste outros fluxos de acesso, se aplicável:

• Fluxos de acesso degradados (recurso premium)
• Fluxos de acesso temporário (recurso premium)
• Fluxos de acesso de logon único (recurso padrão)

Aborde as principais integrações do MVPD (abrangendo os provedores mais usados).

Corre o risco de falhas imprevistas na produção, especialmente em plataformas testadas com menos frequência ou fluxos raros, como cenários negativos.

Use o site Adobe Developer.

-

Fase

Obrigatório

(Recomendado)

Armazenar em cache credenciais de cliente

Tokens de acesso em cache

Validar e atualizar tokens de acesso

Minimizar recuperações de resposta de configuração

Resposta de configuração de cache

O mecanismo de sondagem está ajustando

partes do cache de perfis

Suporte a vários perfis

Recurso de Degradação de Suporte (se necessário ao negócio)

Recurso TempPass Suporte (se necessário ao negócio)

Recurso de Logon Único Suporte (se necessário ao negócio)

Decisões de pré-autorização de permissão de cache

Repetir ajuste do mecanismo

Melhorar a experiência do usuário usando códigos de erro para decisões de pré-autorização negadas

Recuperar decisão de autorização quando o usuário solicitar a reprodução

Repetir ajuste do mecanismo

Melhore a experiência do usuário usando códigos de erro para decisões de autorização negadas

Validação de token de mídia

Implemente a API de logout para permitir que os usuários saiam manualmente

Evite chamar automaticamente a API de logout

Obrigatório

(Recomendado)

Siga as especificações de cabeçalhos obrigatórios

Reutilizar código da API REST v1

Implementar tratamento de erros aprimorado

Implementar tratamento de erros HTTP

-