Skip to main content
Você está vendo a documentação para desenvolvedores
Esta documentação é para desenvolvedores que trabalham com a plataforma para desenvolvedores Base44.
Um actor é um processo de backend de longa duração ao qual vários clientes se conectam simultaneamente. Com actors, você pode criar instâncias de sessões ao vivo que oferecem as seguintes funcionalidades:
  • Mensagens em tempo real: Envie e receba mensagens com clientes via WebSockets.
  • Armazenamento persistente: Mantenha o estado da sessão entre períodos de inatividade.
  • Trabalho agendado: Execute lógica em um intervalo definido ou em um horário específico.
Use actors quando você estiver criando recursos em que vários clientes precisam de atualizações e interação em tempo real, como uma sala de chat ou um jogo multiplayer.

​
Actors

Actor é a classe que você estende no seu backend. A classe do actor define o comportamento de uma sessão ao vivo. Com actors, você pode:
  • Gerenciar conexões: Aceite ou rejeite um cliente que se conecta à sessão e identifique quem está se conectando.
  • Processar mensagens: Receba uma mensagem de um cliente, atualize o estado da sessão e responda a um cliente ou transmita para todos.
  • Agendar trabalho: Execute lógica em um intervalo ou em um horário agendado.

​
Sessões

Uma sessão é uma instância em execução de um actor, identificada pelo nome do actor e por um ID de sessão que você escolhe.
Cada sessão gerencia seu próprio estado, armazenamento e conexões de clientes de forma independente.

​
Conexões

Uma conexão representa o WebSocket de um cliente com uma sessão. Cada cliente que entra recebe uma conexão única. Um actor usa essa conexão para identificar quem está se conectando, gerenciar conexões de clientes e enviar mensagens. Para saber mais, veja conexões. Para um fluxo de exemplo, veja gerenciar conexões de clientes.

​
Sessões ativas e inativas

Uma sessão está sempre em um dos seguintes estados:
  • Ativa: A sessão está ao vivo e processando eventos. Uma sessão fica ativa quando um cliente se conecta, quando um cliente envia uma mensagem para uma sessão inativa ou quando chega o horário de um wake agendado.
  • Inativa: A sessão não está processando eventos. Uma sessão fica inativa pouco depois de terminar sua última mensagem e de todo o trabalho agendado parar. A sessão mantém seus dados armazenados, horários agendados e conexões abertas até ficar ativa novamente.
Quando uma sessão fica inativa, os clientes com conexões abertas continuam conectados. A próxima mensagem deles ou um wake agendado ativa a sessão novamente.

​
Cliente

Use base44.actors no SDK JavaScript para conectar um cliente a uma sessão de actor e trocar mensagens. O SDK de actors oferece as seguintes funcionalidades:
  • Conectar: Abre uma conexão WebSocket com uma sessão.
  • Inscrever-se: Recebe mensagens do actor.
  • Enviar: Envia mensagens para o actor.
  • Fechar: Fecha a conexão WebSocket com o actor.
Para saber mais, veja conectar um cliente a uma sessão.

​
Como actors e clientes interagem

O diagrama a seguir mostra a interação geral entre um cliente e um actor:
  1. O cliente se conecta ao actor por um WebSocket.
  2. A sessão é ativada. handleStart() é executado na primeira inicialização e sempre que a sessão é ativada a partir do estado inativo.
  3. O actor processa a conexão. Você pode verificar a identidade do cliente e rejeitar a conexão, ou enviar o estado atual.
  4. O cliente envia uma mensagem.
  5. O actor processa a mensagem. Você pode validar o formato e as permissões do remetente antes de alterar o estado da sessão.
  6. O actor transmite a atualização para todos os clientes conectados, ou responde apenas ao remetente.
  7. O cliente fecha a conexão.
  8. O actor processa a desconexão. Você pode remover o estado por conexão.

​
Mensagens em tempo real

Cada cliente conectado pertence a uma sessão e pode enviar mensagens em tempo real via WebSockets. Os clientes também podem escutar mensagens recebidas usando subscribe().
A Base44 oferece vários recursos em tempo real que usam um listener baseado em inscrição:
  • O subscribe() de actors escuta as mensagens que o actor envia para os clientes conectados.
  • O subscribe() de entidades escuta mudanças nas entidades do app.
Verifique qual serviço você usa para receber os eventos esperados.
Com mensagens em tempo real, você pode:
  • Responder a um cliente específico.
  • Transmitir para todos os clientes conectados.
  • Listar os clientes que estão conectados no momento.
  • Identificar cada cliente e verificar se ele fez login.
Para saber mais, veja conexões. Para um fluxo de exemplo, veja gerenciar conexões de clientes.

​
Tipos de mensagem

Um cliente e um actor trocam mensagens por uma conexão. As mensagens se dividem nos seguintes tipos:
  • Mensagens recebidas: O que um cliente conectado envia para o actor, como um texto, uma jogada ou um voto. O cliente as envia com send(), e o actor as recebe em handleMessage().
  • Mensagens enviadas: O que o actor envia para os clientes conectados, como uma resposta a um cliente, uma transmissão para todos os clientes conectados ou o tabuleiro atual quando alguém entra. O actor as envia com conn.send() ou broadcast(), e o cliente as recebe em um callback de subscribe().
Recomendamos tipar suas mensagens para que o actor e o cliente concordem sobre o formato de cada mensagem:
  • Backend: Passe os tipos Incoming e Outgoing como genéricos para a classe Actor. Para um exemplo completo, veja criar um actor.
  • Cliente: Estenda a interface ActorRegistry com os mesmos formatos, para que o TypeScript verifique os tipos de send() e subscribe().

​
Armazenamento

Os actors oferecem várias opções de armazenamento, dependendo de como sua sessão usa e retém dados:
  • Armazenamento em memória: Estado de trabalho que fica em campos da classe enquanto a sessão está ativa e é redefinido quando a sessão fica inativa.
  • Armazenamento persistente: Um armazenamento de chave-valor para dados que precisam sobreviver quando a sessão fica inativa.

​
Armazenamento em memória

Os campos da classe guardam o estado de trabalho enquanto a sessão está ativa, como o tabuleiro atual ou um timer de rodada. Use o armazenamento em memória quando seus dados mudam com frequência e não precisam persistir quando a sessão fica inativa, como um placar ao vivo ou a posição de um cursor. Quando uma sessão fica inativa, os campos da classe são redefinidos.

​
Armazenamento persistente

Cada sessão tem seu próprio armazenamento de chave-valor, que você pode gerenciar totalmente. Use o armazenamento persistente quando seus dados precisam sobreviver quando a sessão fica inativa, como o histórico de chat ou um tabuleiro de jogo. Para armazenar dados disponíveis em todo o app, use entidades. Para saber mais sobre o armazenamento de actors, veja armazenamento.

​
Restaurando o estado

Quando uma sessão fica inativa, o estado em memória é redefinido. O armazenamento persistente sobrevive, mas a sessão não carrega automaticamente os dados armazenados de volta para a memória quando é ativada. Use handleStart() para restaurar dados persistentes, como o histórico de chat ou o tabuleiro do jogo. Para um fluxo de exemplo, veja persistir dados da sessão.

​
Trabalho agendado

Os actors oferecem funcionalidades para que uma sessão execute lógica em uma programação, independentemente das mensagens dos clientes:
  • Ticks: Executam código em um intervalo e mantêm a sessão ativa enquanto se repetem.
  • Wakes: Executam uma vez em um horário que você escolhe, esteja a sessão ativa ou inativa.

​
Ticks

Os ticks executam código em um intervalo e mantêm a sessão ativa enquanto se repetem. Use shouldTick() para definir as condições em que os ticks são executados. Um actor reavalia shouldTick() após cada conexão, mensagem, desconexão e tick, então os ticks param assim que a condição deixa de ser atendida.
Os ticks precisam de pelo menos um cliente conectado.
Com ticks, você pode:
  • Escolher a duração de cada intervalo.
  • Definir uma condição que inicia e interrompe os ticks, como “pelo menos dois jogadores estão na sessão”.
  • Escrever o código que é executado a cada intervalo.
Use ticks para manter uma sessão ativa mesmo quando os clientes não estão enviando mensagens, como ao atualizar um timer de rodada. Para saber mais sobre ticks, veja handlers e configurações de timers e executar ticks para um fluxo de exemplo.

​
Wakes

Um wake é executado uma vez em um horário que você escolhe, esteja a sessão ativa ou inativa. Com wakes, você pode:
  • Agendar quando um wake é executado.
  • Implementar a lógica que é executada quando um wake ocorre.
Use um wake para agendar uma ação única, como encerrar a vez de um jogador, fechar um lobby vazio, disparar um lembrete ou iniciar um evento em um horário específico. Para saber mais sobre wakes, veja handlers e configurações de timers e agendar wakes para um fluxo de exemplo.

​
Implantar um actor

Implante actors com actors deploy. Para enviar todos os recursos do projeto de uma vez, use deploy. A implantação adiciona e atualiza actors remotos e mantém o restante como está.

​
Excluir um actor

Para excluir um actor:
  • Execute actors delete para excluir o actor remoto da Base44.
  • Exclua o diretório do actor do seu projeto local.
Se você não excluir o actor do seu projeto local, o próximo actors deploy ou deploy recria e implanta o actor no seu projeto da Base44.

​
Veja também

Esta página foi traduzida usando IA. Para as informações mais precisas e atualizadas, consulte a versão em inglês.