Cookbook REST API V2 (servidor para servidor) rest-api-v2-cookbook-server-to-server

Comunique-se com o serviço Adobe Pass em nome do aplicativo de streaming.

Colete e transmita um identificador de dispositivo exclusivo para o Dispositivo de Streaming, conforme exigido pelo cabeçalho AP-Device-Identifier.

Colete e transmita informações precisas do Dispositivo de Streaming, incluindo a porta de origem e os detalhes específicos do dispositivo, conforme exigido pelo cabeçalho X-Device-Info.

Colete e passe o endereço IP do dispositivo de transmissão conforme exigido pelo cabeçalho X-Forwarded-For.

Armazene com segurança parâmetros como ID de dispositivo, ID de cliente e segredo do cliente no Aplicativo de streaming ou no Serviço de programador.

Formate e envie dados em conformidade com MVPDs e aplicativos integrados, incluindo IP do dispositivo, porta de origem, informações específicas do dispositivo, MRSS e identificadores opcionais, como ECID.

Mantenha e gerencie com segurança os certificados compartilhados com o Adobe para transmissão criptografada de metadados do usuário.

Respeite o perfil de autenticação e a validade da decisão de autorização ao armazenar em cache, garantindo que os estados de autenticação e autorização sejam invalidados quando notificados.

Devolver as decisões de autorização e as instruções relevantes ao aplicativo de transmissão.

O Adobe Pass Service opera em vários data centers geograficamente dispersos nos EUA para otimizar o desempenho e minimizar a latência.

• O Serviço de programador deve adotar uma estratégia de infraestrutura semelhante, garantindo tempos de resposta de baixa latência da Adobe Pass.

O Programador deve fornecer o intervalo IP público de seu ambiente de produção.

• Esses IPs serão adicionados a um incluo na lista de permissões na infraestrutura da Adobe Pass.

O Serviço de programador deve limitar o cache DNS a um máximo de 30 segundos para permitir o redirecionamento dinâmico caso o Adobe precise redirecionar o tráfego devido à indisponibilidade de um data center.

Ele deve permitir versões de teste antes da implantação na produção.

Deve permanecer operacionalmente semelhante à produção, permitindo testes realistas.

Idealmente, o ambiente de preparo deve estar conectado aos ambientes de teste do Adobe Pass para:

• Permitir que os programadores testem em relação à infraestrutura da Adobe.

• Ativar o Adobe para auxiliar no teste e na solução de problemas quando necessário.

Recuperar credenciais do cliente: o Serviço Programador recupera credenciais do cliente chamando o ponto de extremidade /o/client/register.

• O Serviço do programador ou Aplicativo do programador deve armazenar as credenciais do cliente e usá-las indefinidamente quando precisar recuperar um token de acesso.

Recuperar token de acesso: o Serviço Programador recupera o token de acesso chamando o ponto de extremidade /o/client/token.

• O Serviço do programador ou Aplicativo do programador deve armazenar e usar o token de acesso até que ele expire, depois descartá-lo e obter um novo.

Recuperar perfis: O Serviço Programador verifica os perfis existentes em nome do Aplicativo de Streaming chamando o ponto de extremidade /api/v2/{serviceProvider}/profiles.

Cenário 1: Existem perfis, o Serviço Programador pode prosseguir para a Fase de Pré-autorização ou a Fase de Autorização.

Cenário 2: Não há perfis existentes, o Serviço Programador pode prosseguir para a próxima etapa para Autenticar o usuário.

Cenário 3: Não há perfis existentes, o Serviço de Programador pode continuar a fornecer ao usuário acesso temporário por meio do recurso TempPass.

• Este cenário está fora do escopo deste documento. Consulte a documentação Fluxos de Acesso Temporário para obter mais informações.

Recuperar configuração: O Serviço Programador recupera a lista de MVPDs disponíveis chamando o ponto de extremidade /api/v2/{serviceProvider}/configuration.

• O Serviço de programador pode implementar um mecanismo de filtragem personalizado para refinar a lista de MVPDs a partir da resposta de configuração, de modo que o Aplicativo de transmissão exiba apenas os provedores pretendidos enquanto oculta outros (por exemplo, MVPDs em desenvolvimento, MVPDs de teste, TempPass). Isso garante que os usuários sejam apresentados a uma seleção com curadoria ao escolher seu provedor de TV.

Criar sessão de autenticação: O Serviço Programador inicia uma sessão de autenticação chamando o ponto de extremidade /api/v2/{serviceProvider}/sessions.

• O Serviço Programador deve retornar code e url para o Aplicativo de Streaming.

Cenário 1: O Aplicativo de Streaming pode abrir um navegador ou uma exibição da Web, portanto, deve carregar a autenticação url.

• O usuário envia seu nome de usuário e senha na página de logon do MVPD. Após a autenticação bem-sucedida, o redirecionamento final exibe uma página de sucesso.

Cenário 2: o Aplicativo de Streaming não pode abrir um navegador, portanto, deve exibir a autenticação code. É necessário um aplicativo Web separado para solicitar que o usuário insira o code, crie a autenticação url e abra: /api/v2/authenticate/{serviceProvider}/{code}.

• O usuário envia seu nome de usuário e senha na página de logon do MVPD. Após a autenticação bem-sucedida, o redirecionamento final exibe uma página de sucesso.

Recuperar perfil para código específico: O Serviço Programador deve implementar um mecanismo de sondagem usando code para verificar se o perfil foi gerado e salvo com êxito, chamando o ponto de extremidade /api/v2/{serviceProvider}/profiles/code/{code}.

• O Serviço Programador deve iniciar o mecanismo de sondagem sob as seguintes condições:

  • Autenticação executada no aplicativo (tela) primário: O Serviço Programador deve iniciar a sondagem quando o usuário atingir a página de destino final, depois que o componente do navegador carregar a URL especificada para o parâmetro redirectUrl na solicitação do ponto de extremidade Sessões.

  • Autenticação executada em um aplicativo secundário (tela): O aplicativo de Serviço Programador deve iniciar a sondagem assim que o usuário iniciar o processo de autenticação, logo após receber a resposta do ponto de extremidade Sessões e exibir o código de autenticação ao usuário.

• O Serviço Programador deve interromper 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 seu status de autenticação. Neste ponto, a pesquisa 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, conforme indicado pelo carimbo de data/hora notAfter (por exemplo, 30 minutos) na resposta do ponto de extremidade Sessões. Se isso acontecer, o usuário deverá reiniciar o processo de autenticação e a pesquisa usando o código de autenticação anterior deverá ser interrompida imediatamente.

  • Novo código de autenticação gerado: Se o usuário solicitar um novo código de autenticação no dispositivo primário (tela), a sessão existente não será mais válida e a sondagem usando o código de autenticação anterior deverá ser interrompida imediatamente.

• O Serviço Programador deve configurar a frequência do mecanismo de sondagem sob as seguintes condições:

  • Autenticação executada no aplicativo (tela) primário: O Serviço Programador deve sondar a cada 3-5 segundos ou mais.

  • Autenticação executada em um aplicativo secundário (tela): O Serviço Programador deve sondar a cada 3-5 segundos ou mais.

• O Serviço de programador deve armazenar em cache partes das informações de perfil do usuário em um armazenamento persistente para evitar solicitações desnecessárias e melhorar a experiência do usuário.

Recuperar decisões de pré-autorização: O Serviço Programador recupera decisões de pré-autorização para uma lista de recursos chamando o ponto de extremidade /api/v2/{serviceProvider}/Decisions/preauthorize/{mvpd}.

• O Serviço do programador deve passar a lista de decisões de permissão e negação de pré-autorização para o aplicativo de streaming.

• O Serviço do Programador não é necessário para armazenar decisões de pré-autorização em armazenamento persistente. No entanto, é recomendável armazenar em cache as decisões de permissão na memória para melhorar a experiência do usuário. Isso ajuda a evitar chamadas desnecessárias para recursos que já foram pré-autorizados, reduzindo a latência e melhorando o desempenho.

• O Serviço de Programador pode determinar o motivo de uma decisão de pré-autorização negada ao inspecionar o código de erro e a mensagem incluídos na resposta do ponto de extremidade de Pré-autorização de Decisões. Esses detalhes fornecem informações sobre o motivo específico pelo qual a solicitação de pré-autorização foi negada, ajudando a informar a experiência do usuário ou acionar qualquer manipulação necessária no aplicativo. Certifique-se de que qualquer mecanismo de repetição implementado para recuperar decisões de pré-autorização não resulte em um loop infinito se a decisão de pré-autorização for negada. Considere limitar as tentativas a um número razoável e lidar com as negações normalmente ao exibir comentários claros para o usuário.

• O Serviço do programador pode obter uma decisão de pré-autorização para um número limitado de recursos em uma única solicitação de API, geralmente até 5, devido a condições impostas pelos MVPDs. Este número máximo de recursos pode ser exibido e alterado após a aceitação dos MVPDs por meio do Painel TVE da Adobe Pass por um dos administradores da organização ou por um representante da Autenticação Adobe Pass que atue em seu nome.

Recuperar decisão de autorização: O Serviço Programador recupera a decisão de autorização para um recurso específico passado pelo Aplicativo de Streaming chamando o ponto de extremidade /api/v2/{serviceProvider}/decision/authorize/{mvpd}.

• O Serviço do Programador não é necessário para armazenar decisões de autorização em armazenamento persistente.

• O Serviço de Programador pode determinar o motivo de uma decisão de autorização negada ao inspecionar o código de erro e a mensagem incluídos na resposta do ponto de extremidade de Autorização de Decisões. Esses detalhes fornecem ao insight o motivo específico pelo qual a solicitação de autorização foi negada, ajudando a informar a experiência do usuário ou acionar qualquer manipulação necessária no aplicativo de streaming. Certifique-se de que qualquer mecanismo de repetição implementado para recuperar decisões de autorização não resulte em um loop infinito se a decisão de autorização for negada. Considere limitar as tentativas a um número razoável e lidar com as negações normalmente ao exibir comentários claros para o usuário.

• O Serviço de programador pode avaliar outras regras de negócio e devolver uma decisão de autorização apropriada ao Aplicativo de streaming.

• O Serviço de programador não é necessário para atualizar um token de mídia expirado enquanto o fluxo estiver sendo reproduzido ativamente. Se o token de mídia expirar durante a reprodução, o fluxo deverá continuar sem interrupções. No entanto, o cliente deve solicitar uma nova decisão de autorização — e obter um novo token de mídia — na próxima vez que o usuário tentar reproduzir um recurso.

• O Serviço de programador pode obter uma decisão de autorização para um número limitado de recursos em uma única solicitação de API, geralmente até 1, devido a condições impostas pelos MVPDs.

Iniciar logout do Adobe Pass: O Serviço Programador inicia o fluxo de logout conforme solicitado pelo Aplicativo de Streaming ao chamar o ponto de extremidade /api/v2/{serviceProvider}/logout/{mvpd}.

• O Serviço do programador pode apagar todas as informações armazenadas sobre o usuário autenticado.

• O Serviço Programador deve seguir as instruções fornecidas nos atributos actionName e actionType da resposta do ponto de extremidade de logout para garantir que o processo de logout seja concluído corretamente.

  • Se o atributo actionType na resposta for definido como "interativo", o Serviço de Programador deverá retornar o valor do atributo url para o Aplicativo de Streaming.

    • Cenário 1: O Aplicativo de Streaming pode abrir um navegador ou uma exibição da Web, portanto, deve carregar o logout url.

    • Cenário 2: o Aplicativo de Streaming não pode abrir um navegador, portanto, o processo de logout pode ser interrompido porque a sessão do MVPD não foi mantida em um cache de navegador do Dispositivo de Streaming.