> This page is for Camera to Cloud. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # Instruções: Gerenciar status e estado ## Introdução Este guia explica como gerenciar o status do dispositivo e manter a sincronização com o Frame.io. Utilizamos um protocolo WebSocket que permite a comunicação em tempo real entre o Frame.io e o seu dispositivo. Se você não estiver familiarizado com WebSockets, este guia o ajudará a entender sua implementação para integrações C2C. Os WebSockets permitem que o Frame.io envie mensagens para o seu dispositivo e, ao manter uma conexão persistente, proporcionam um canal de comunicação mais eficiente do que as solicitações HTTP tradicionais. Neste guia, abordaremos: * Como abrir uma conexão de socket para indicar que seu dispositivo está 'online' * Como recuperar informações sobre a conexão do seu dispositivo * Como verificar a disponibilidade do back-end do Frame.io ## Pré-requisitos Caso ainda não tenha feito isso, revise o guia [Implementação do C2C: Configuração](./implementing-c2c-setting-up) antes de prosseguir. Você precisará do `access_token` obtido durante o [processo de autenticação e autorização](./implementing-c2c-authentication-and-authorization). Lembre-se de que os tokens expiram após 8 horas. Portanto, talvez seja necessário atualizar seu token ou passar pelo processo de autorização novamente. Para os exemplos de conexão via WebSocket deste guia, recomendamos o uso do [websocat](https://github.com/vi/websocat), uma ferramenta de linha de comando (CLI) com instruções de instalação completas para diversos sistemas operacionais. Instale com: `brew install websocat` ## Recuperar informações de conexão Após qualquer nova autorização ou atualização do token, seu dispositivo deve consultar imediatamente o ponto de acesso `identity`. Isso fornece informações essenciais sobre sua conexão: ```shell curl -X GET https://api.frame.io/v2/devices/me \ --header 'Authorization: Bearer [access_token]' \ --header 'x-client-version: 2.0.0' \ | python -m json.tool ``` A resposta será semelhante a esta (com alguns dados abreviados): ``` { "_type": "project_device", "id": "a7e95254-8cd6-4d59-b54d-28c58570a8de", "asset_type": "video", "authorization": { "_type": "project_device_authorization", "creator": { "_type": "user", "id": "e7e96254-8bd6-4d59-b54d-28c58570a8de", "name": "Harry Potter" }, "expires_at": null, "id": "7b2b68e5-788d-497c-8597-f9362cb1a75e", ... "project_device_id": "14856308-46e0-4d7d-8438-320262eec74e", "scopes": { ... "asset_create": true, ... "id": "0fe0accb-447f-44f6-b2af-177d913b3a29", "offline": true, ... } }, ... "name": "Frameio-BPEAKE-TEST-DEVICE", "project": { "_type": "project", "id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3", "name": "Testbed" }, "project_id": "2ad59fe6-77b6-4fbc-a9d2-3dd0413ed4a3", "status": "online", ... } ``` Esse ponto de acesso ajuda a verificar os detalhes da conexão. Seu dispositivo deve exibir essas informações aos usuários: * `project.name` – o nome do projeto conectado * `authorization.creator.name` – o usuário que autorizou o dispositivo * `authorization.expires_at` (opcional) – hora de expiração da conexão, se definida * `status` (opcional) – status do dispositivo, que pode ser: * `online` – o dispositivo está conectado e emparelhado * `offline` – o dispositivo não se comunica há mais de 5 minutos (ao consultar este ponto de acesso, o status será alterado para `online`) * `paused` – o dispositivo foi desativado temporariamente no painel Conexões C2C do Frame.io Como o status de validade e de pausa pode mudar a qualquer momento no Frame.io, considere consultar essas informações periodicamente caso as exiba aos usuários. Recomendamos limitar a frequência de consulta a no máximo uma vez a cada 60 segundos. Anote o valor do `id`, pois você precisará dele para a conexão via WebSocket na próxima seção ## Estabelecer a conexão via WebSocket O painel Conexões C2C no Frame.io exibe o status de conexão de cada dispositivo. Quando um dispositivo possui uma conexão de socket ativa, ele aparece como `online` com um indicador verde no canto superior esquerdo do cartão. Dispositivos sem conexões ativas aparecem como `offline` com a exibição em cinza. O servidor encerra automaticamente as conexões de socket após 60 segundos sem uma mensagem de "heartbeat". Embora esse intervalo seja suficiente, recomendamos enviar heartbeats a cada 15 segundos para garantir a confiabilidade. Se a conexão for encerrada inesperadamente, basta restabelecê-la. A conexão com o WebSocket do Frame.io envolve duas etapas: 1. Estabelecer o handshake TCP/IP e abrir a conexão física do WebSocket 2. Entrar no canal específico do dispositivo para identificá-lo em nosso back-end Para abrir a conexão do WebSocket: ```shell websocat -n "wss://api.frame.io/devices/websocket?Authorization=Bearer ACCESS_TOKEN" ``` Ao contrário dos pontos de acesso API padrão, nos quais o token de acesso é inserido no cabeçalho `Authorization`, nas conexões WebSocket ele é incluído como um parâmetro de consulta codificado por URL. Observe que você ainda deve incluir `Bearer ` (com um espaço) antes do seu token de acesso. Em strings codificadas por URL, os espaços aparecem como `%20`, portanto, essa formatação é esperada. Uma conexão bem-sucedida retorna um código de status `101`, indicando a mudança do protocolo para `wss`. Sua biblioteca de WebSocket pode lidar com isso automaticamente Um token expirado gerará uma resposta `403`. Em seguida, entre no canal do seu dispositivo enviando esta mensagem JSON, usando o `id` das suas informações de conexão: ```json {"topic":"devices:YOUR_DEVICE_ID", "event":"phx_join", "payload":"", "ref":"channel_connect"} ``` Você receberá uma confirmação: ```json {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"channel_connect","topic":"devices:YOUR_DEVICE_ID"} ``` O campo `ref` correlaciona as respostas com os eventos que as iniciaram. Como a ordem dos eventos não é garantida, esse identificador ajuda a associar as respostas do servidor aos eventos que as acionaram. O Frame.io não usa esse campo para eventos recebidos. Ele serve exclusivamente como referência para o cliente. O campo `payload` deve estar sempre presente, mas muitas vezes pode ser uma string em branco (especificaremos quando um payload exigir conteúdo específico). Verifique o painel do C2C. Seu dispositivo já deve estar aparecendo como online! Recomendamos implementar um processo em segundo plano para manter essa conexão: **`Python`** ```python title="Python" def heartbeat_task(): """ Task that emits heartbeats every 15 seconds. """ while True: c2c.emit_socket_heartbeat() sleep(15) ``` O formato da mensagem de heartbeat: ```json {"topic":"phoenix", "event":"heartbeat", "payload":"", "ref":"heartbeat"} ``` Que recebe esta resposta: ```json {"event":"phx_reply","payload":{"response":{},"status":"ok"},"ref":"heartbeat","topic":"phoenix"} ``` Com uma conexão de socket ativa e uma assinatura de canal, seu dispositivo aparecerá como online no painel Conexões C2C do Frame.io. Quando a conexão for encerrada, ele aparecerá como offline. ## Exibir status do dispositivo Em vez de exibir os valores brutos de status (`online`, `offline`, `paused`), recomendamos traduzi-los em indicadores mais significativos para o usuário: * **Paused**: true/false – exibe `true` se o status for `paused`, caso contrário `false` * **Connected**: true/false – indica se o dispositivo consegue se conectar ao back-end do Frame.io (consulte o teste de conexão com o back-end abaixo) ## Gerenciar o status pausado Embora a exibição do status de pausa seja opcional, é importante compreender sua função. O recurso de pausa foi projetado para bloquear temporariamente o envio de conteúdo sensível. Ele não bloqueia o tráfego de rede, mas impede que mídias específicas cheguem ao Frame.io. Isso é útil em situações como a filmagem de cenas que contenham material sensível, nas quais o armazenamento imediato na nuvem pode ser inadequado. A pausa é controlada por meio da interface do Frame.io, e não por meio da sua integração. Quando um dispositivo está em pausa, apenas os arquivos de mídia criados durante o período de pausa são bloqueados. Os arquivos capturados anteriormente continuam aptos para upload. Considerações importantes: * Não confie exclusivamente no ponto de acesso de identidade para validar a elegibilidade do upload. Nosso back-end lida com isso automaticamente * Os eventos do socket notificam você sobre mudanças de status com `event: "status_updated"` e `payload: "paused"` ou `"resumed"` * Embora os eventos possam ajudar a gerenciar o status, eles podem ser perdidos ou entregues fora de ordem * Receber um erro `409` durante o upload não significa necessariamente que o dispositivo esteja pausado no momento. Isso pode indicar que a mídia foi criada durante um período de pausa anterior * Se for exibido um status de pausa, verifique se ele está correto, conferindo periodicamente as informações de conexão ## Verificar a conectividade do back-end Para verificar a disponibilidade do back-end do Frame.io, use este ponto de acesso: ```shell curl -X GET https://api.frame.io/health \ | python -m json.tool ``` Este ponto de acesso não requer autorização. Uma resposta bem-sucedida indica conectividade: ```json { "ok": true } ``` Essa verificação de integridade é particularmente valiosa, pois confirma a conectividade especificamente com o Frame.io, em vez da disponibilidade geral da rede. Pode haver cenários em que sua rede funcione, mas o Frame.io esteja inacessível devido a problemas de serviço ou de roteamento. ## Próximas etapas Recomendamos que você entre em contato com nossa equipe caso tenha alguma dúvida e consulte o [guia básico de upload](/camera-to-cloud/how-to-basic-upload). Esperamos poder apoiar o andamento da sua integração. Para obter mais informações sobre como gerenciar a autorização de dispositivos, consulte o [guia de gerenciamento de autorização](./how-to-authorization-management).