Obsoleto

Instruções: Autorização (Hardware)

Introdução

Neste guia, você vai aprender a autenticar e autorizar um dispositivo de hardware Camera to Cloud (C2C) em um projeto do Frame.io.Vamos abordar tanto o método de emparelhamento tradicional usando inserção manual de código quanto o novo método de emparelhamento por QR Code para uma experiência do usuário aprimorada.

O que vou precisar?

Caso ainda não tenha lido o guia Antes de começar a implementação, dê uma olhada rápida nele antes de continuar!Além disso, você deve ter recebido um client_secret da nossa equipe que será usado para identificar sua integração.Se você não recebeu um client_secret, consulte esta introdução ao ecossistema C2C e entre em contato com nossa equipe.

Pré-requisitos para emparelhamento por QR Code

Antes de começar o emparelhamento por QR Code, verifique se os seguintes pré-requisitos foram atendidos:

  • Ativação de sinalizador de recurso: um sinalizador de recurso específico (v4.c2c_qr_code_activate) deve estar habilitado na sua conta do Frame.io.Este sinalizador de recurso permitirá acesso ao método de emparelhamento baseado em QR Code.Seu ponto de contato designado do Frame.io pode ajudar a ativar esse recurso para a conta de sua escolha.
  • Compatibilidade da câmera: certifique-se de que o hardware da câmera esteja atualizado para dar suporte à geração de QR Code durante o processo de emparelhamento do dispositivo.

Como funciona o fluxo de autenticação por hardware

Vamos garantir que temos um entendimento de alto nível da experiência do usuário esperada para o fluxo de autorização que queremos implementar.Confira os recursos a seguir para ver esse fluxo do ponto de vista do usuário:

  • Artigo de suporte sobre como adicionar novos dispositivos de hardware.
  • Vídeo de treinamento sobre como autorizar um Teradek Cube.

O fluxo de autorização de hardware foi projetado para tirar o máximo de detalhes possível do implementador e, portanto, da interface do dispositivo.Com este fluxo, você não precisa se preocupar com:

  • O redirecionamento para um navegador da web.
  • O gerenciamento do login/autenticação do usuário no Frame.io.
  • Listar/selecionar a conta e o projeto aos quais se conectar.
  • Quaisquer elementos da interface do usuário além da exibição de informações básicas.

Aprimorando a experiência do usuário com emparelhamento por QR Code

À medida que cresce a demanda por eficiência e facilidade de uso, os usuários esperam cada vez mais interações contínuas com seus dispositivos.O processo atual para emparelhar câmeras ao serviço C2C do Frame.io requer várias etapas, incluindo a entrada manual de um código de emparelhamento.Embora funcional, esse processo pode ser simplificado.

Ao usar QR Codes, similar às experiências de emparelhamento de dispositivos vistas em serviços de streaming como Netflix ou Disney+, podemos simplificar o processo, eliminar erros causados pela entrada manual e reduzir o tempo necessário para emparelhar uma câmera.

Identificação do dispositivo (client_id)

Ao conectar ao Camera to Cloud, cada dispositivo de hardware físico precisará se identificar exclusivamente para que possamos listar as conexões de dispositivo no projeto de um usuário.

Para dispositivos de hardware, chamamos isso de client_id do dispositivo, dependendo do padrão de autorização que você escolher usar.Ao configurar sua implementação, você deve pensar em como fará isso.Você pode usar um número de série do dispositivo de hardware, um UUID ou alguma string de identificação exclusiva.Tenha cuidado para não vazar informações de identificação pessoal.O email do usuário, por exemplo, não é um valor válido para usar como client_id.

Da mesma forma, certifique-se de que você possui o identificador exclusivo.Se você está implementando a API C2C como um dispositivo de software, não use o endereço MAC do dispositivo, por exemplo.O endereço MAC não pertence ao seu software e também pode ser considerado informação de identificação pessoal.

Se você não tiver certeza de qual valor gostaria de usar, podemos discutir essa escolha juntos e garantir que seja escolhido um valor adequado, que torne a integração o mais fácil possível.

Etapa 1: solicitar um código de dispositivo

Vamos começar a implementação.A primeira coisa que precisamos fazer é solicitar um código de dispositivo para dar ao usuário para um dispositivo.Fazemos isso chamando o ponto de acesso /v2/auth/device/code:

Método de emparelhamento tradicional

curl -X POST https://api.frame.io/v2/auth/device/code \
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Ativação do emparelhamento por QR Code

Para ativar o emparelhamento baseado em QR Code, é necessária uma pequena alteração na chamada de API.Especificamente, dois novos cabeçalhos precisam ser adicionados à solicitação de código de dispositivo.Isso permite que os dispositivos se vinculem diretamente à página de emparelhamento e simplifiquem o processo de emparelhamento.

curl -X POST https://api.frame.io/v2/auth/device/code \
    --header "x-client-version: 2.0.0" \
    --header "x-client-platypus-enabled: true" \  # New header to enable QR code
    --form 'client_id=[client_id]' \
    --form 'client_secret=[client_secret]' \
    --form 'scope=asset_create offline' \
    | python -m json.tool

Observação: estamos usando dados de formulário aqui em vez de dados JSON.Os pontos de acesso de autenticação C2C aceitam apenas dados de formulário.Depois de autenticado, outros pontos de acesso aceitarão conteúdos JSON, mas os pontos de acesso de autenticação retornarão um erro se conteúdos JSON forem enviados.

Parâmetros do conteúdo

  • client_id: um identificador exclusivo para o dispositivo de hardware físico.Este valor precisa ter a garantia de ser exclusivo para o dispositivo.Pode ser um número de série ou um UUID gerado aleatoriamente.
  • client_secret: será emitido para você pelo suporte do Frame.io e identifica o modelo do seu dispositivo.Este valor deve ser mantido em segredo do usuário e deve ser criptografado em repouso.
  • scope: as permissões que estamos solicitando, com espaços usados como delimitadores.Dispositivos de hardware só podem solicitar os dois escopos a seguir:
  • asset_create: permite que o dispositivo crie e faça upload de ativos.
  • offline: permite que o dispositivo atualize a própria autorização usando um token de atualização.Os tokens de autorização expiram após 8 horas, então, sem esse escopo, um usuário precisaria autorizar novamente o dispositivo a cada 8 horas.

Na prática, os dispositivos quase sempre vão querer solicitar os dois escopos.

Entender a resposta da API

Quando fazemos a solicitação, obtemos uma resposta similar à seguinte:

Resposta de emparelhamento tradicional

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131"
}

Resposta de emparelhamento por QR Code

{
  "device_code": "[device_code]",
  "expires_in": 120,
  "interval": 5,
  "name": "MyDevice-[client_id]",
  "user_code": "573131",
  "verification_uri": "https://next.frame.io/pair",
  "verification_uri_complete": "https://next.frame.io/pair/573131"
}

Detalhamento da resposta

  • device_code: o código do dispositivo deve permanecer oculto ao usuário e é utilizado para identificar essa solicitação de autorização ao verificar se o usuário inseriu o código corretamente.
  • expires_in: o número de segundos até este código expirar.
  • interval: quanto tempo o usuário deve aguardar entre solicitações de polling para verificar se o usuário inseriu o código.
  • name: o nome do dispositivo que estamos tentando conectar.
  • user_code: o código de seis dígitos que o usuário inserirá no Frame.io para emparelhar o dispositivo com um projeto.
  • verification_uri: este é o URL que os usuários inserirão manualmente caso o QR Code não seja escaneado.Deve ser conciso e fácil de lembrar.
  • verification_uri_complete: este URL contém o código de emparelhamento e é destinado à transmissão não textual (por exemplo, o QR Code).Ao ser escaneado, ele direcionará automaticamente o usuário para o processo de emparelhamento, para que ele escolha uma conta e um projeto aos quais conectar seu dispositivo.

Exibir o QR Code para o usuário

Agora que temos o verification_uri_complete, podemos gerar um QR Code a partir deste URL e exibi-lo ao usuário na tela do dispositivo.Isso permite que o usuário simplesmente escaneie o QR Code com o dispositivo móvel ou a câmera, simplificando o processo de emparelhamento.

Exemplo: tela da câmera com QR Code exibido

Insira imagem ou Ilustração de uma tela de câmera exibindo o QR Code.

Se o usuário não conseguir escanear o QR Code por qualquer motivo, você também deve exibir o user_code e verification_uri para que possa inserir manualmente o código de emparelhamento como alternativa.Como alternativa, você também pode exibir o verification_uri como um QR Code estático para o usuário escanear com os dispositivos móveis.Se a integração for um aplicativo em um dispositivo móvel, exibir o verification_uri_complete como um hiperlink para os usuários tocarem é essencial para facilitar a conectividade, já que o usuário não consegue escanear o QR Code com o dispositivo em que o aplicativo está.

Etapa 2: polling para autorização do usuário

Depois de entregar o código de emparelhamento ou exibir o QR Code ao usuário, precisamos verificar se ele foi inserido.Para isso, podemos fazer a seguinte solicitação:

curl -X POST https://api.frame.io/v2/auth/token \
    --form 'client_id=[client_id]' \
    --form 'device_code=[device_code]' \
    --form 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
    | python -m json.tool

Parâmetros do conteúdo

  • client_id: o mesmo client_id enviado na Etapa 1.
  • device_code: o device_code retornado por /v2/auth/device/code.
  • grant_type: o tipo de concessão de autorização que nosso sistema OAuth está emitindo.Este valor sempre será urn:ietf:params:oauth:grant-type:device_code.

Nas primeiras vezes que fizermos essa solicitação, provavelmente receberemos uma resposta como esta:

{
  "error": "authorization_pending"
}

Mas não se preocupe!Esse não é um erro fatal.Significa simplesmente que o usuário ainda não inseriu o código do usuário na interface do Frame.io.Tudo o que precisamos fazer é continuar fazendo polling até que tenham inserido.

Se, em vez disso, recebermos um erro como este:

{
  "error": "expired_token"
}

Isso significa que nosso código expirou antes que o usuário pudesse inseri-lo.Nesse caso, devemos gerar um novo código de emparelhamento ou QR Code usando a Etapa 1, exibi-lo ao usuário e retomar o polling.

No final, devemos obter uma resposta como:

{
  "access_token": "[access_token]",
  "expires_in": 28800,
  "refresh_token": "[refresh_token]",
  "token_type": "bearer"
}

Se seu conteúdo de resposta for assim: Parabéns!Você autorizou seu primeiro dispositivo Camera to Cloud.Aproveite para comemorar!

Após ter comemorado, vamos dar uma olhada no conteúdo da resposta para garantir que o entendemos:

  • access_token: esta é sua chave para o restante do back-end do Frame.io.Precisaremos adicionar isto ao cabeçalho do restante das solicitações que faremos nestes tutoriais.
  • expires_in: o número de segundos até o access_token expirar.Após o tempo limite do token acabar, ele precisará ser atualizado, o que abordaremos em um tutorial futuro.
  • refresh_token: um token que podemos usar para gerenciar nosso access_token.Será usado mais comumente para atualizar nossa autorização, mas também pode ser usado para revogá-la.
  • token_type: sempre será bearer para a API C2C e não é acionável.

Reunir as etapas

Agora que conhecemos as chamadas que precisamos fazer, vamos reuni-las em um pseudocódigo semelhante ao Python.Lembre-se, é possível que nosso código do dispositivo expire, então precisamos lidar com essa possibilidade ao configurar nossa lógica:

Python
1def authorize_with_frame():
2    """
3    Handles authorizing our device with Frame.io.
4    """
5
6    # Our client ID can be a serial number, UUID, or some other unique string.
7    client_id = THIS_DEVICE.get_serial_number()
8
9    while True:
10        # Make the call to Frame.io to get our device codes.
11        pairing_codes = c2c.get_device_codes(client_id)
12
13        # We need to keep track of how long we have been polling for
14        polling_started = datetime.now()
15
16        # Now we are going to poll for authorization until the user enters the code.
17        while True:
18
19            # Re-write this output each time we poll. Note: This message will only update once
20            # per `interval` (e.g., 5 seconds), so if a smooth countdown is desired, that will
21            # need a different implementation.
22            print(
23                f"\rPAIRING CODE: {pairing_codes.user_code}, "
24                f"EXPIRES IN: {pairing_codes.expires_in - (datetime.now() - polling_started).seconds} seconds"
25            )
26
27            # Wait for `interval` before polling each time.
28            sleep(pairing_codes.interval)
29
30            # Make a call to Frame.io to see if the user has entered the code and authorized
31            # the device.
32            authorization, error = c2c.poll_for_authorization(
33                client_id, pairing_codes.device_code
34            )
35
36            if error and error.message == "authorization_pending":
37                # If the authorization is pending, try again.
38                continue
39            elif error and error.message == "expired_token":
40                # If the pairing codes have expired, break to generate new codes.
41                break
42            elif error:
43                # If we get another error, we should raise it. (advanced error handling will
44                # be covered in another tutorial)
45                raise Exception(error.message)
46
47            return authorization

Observação: neste pseudocódigo, adicionamos um loop externo para lidar com o caso em que os códigos de emparelhamento expiram e precisamos solicitar novos.A última coisa que devemos fazer é buscar as informações sobre o projeto ao qual nos conectamos no Frame.io e exibi-las ao usuário para uma camada extra de confirmação de que o dispositivo foi emparelhado ao projeto pretendido.Mostraremos isso no próximo tutorial.

Solução de problemas

Se você chegou até aqui, algo deu errado!O que seria uma integração com terceiros sem algum tipo de erro?Esta seção lista um conjunto de problemas comuns e orienta você nas etapas mais prováveis de resolvê-los.Veja a lista a seguir e verifique se algo corresponde ao problema que você está enfrentando.

Se você não encontrar uma solução aqui, adoraríamos saber qual problema encontrou para que possamos adicioná-lo.

  • Não Vejo um botão “Conectar dispositivo”: se você for ao painel de gerenciamento C2C e não vir um botão “Conectar dispositivo”, então uma de duas coisas está acontecendo:
  • C2C não está habilitado para sua conta: se a tela estiver em branco e houver uma mensagem informando que o C2C não está disponível para a sua conta, o gerente de conta precisa habilitá-lo para o seu projeto nas configurações da conta.
  • Você não é um gerenciador de dispositivos: se a tela estiver em branco e houver uma mensagem informando que você não tem permissões, o gerente de contas precisará alterar as permissões para definir quem tem permissão para conectar dispositivos C2C ou adicioná-lo a uma função que possua essas permissões.
  • Você já tem um dispositivo conectado: após o primeiro dispositivo ser conectado, o grande botão azul “Adicionar novo dispositivo” desaparece, e você precisa ir ao menu de três pontos no canto superior direito do painel Conexões C2C.
  • Erro de cliente inválido: invalid_client é retornado quando as informações que você nos fornece sobre o dispositivo não correspondem a nenhum registro que tenhamos em nossos arquivos.Isso provavelmente significa que seu client_secret está incorreto.
  • Erro de solicitação inválida: bad_request é retornado quando os dados da solicitação apresentam algum tipo de formato incorreto.Verifique novamente se você não escreveu incorretamente um nome de campo ou esqueceu de adicionar um campo obrigatório.

Próximas etapas

Se ainda não o fez, recomendamos que entre em contato com nossa equipe e, em seguida, siga para o próximo guia: LINK.Estamos ansiosos para ter notícias suas!

Estacionamento

Para fazer

Adicionar contingência para parceiros que não conseguem gerar um QR Code dinâmico

ou seja, pedir para exibirem “Acesse **verification_uri** para inserir este código” como plano de backup