> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Visão geral de actors

> Saiba como os actors executam sessões compartilhadas ao vivo com mensagens em tempo real e timers

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Você está vendo a documentação para desenvolvedores
    </div>

    <div className="dev-docs-banner-text">
      Esta documentação é para desenvolvedores que trabalham com a plataforma para desenvolvedores
      Base44.
    </div>
  </div>
</div>

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`](/pt-BR/developers/backend/resources/actors/reference) é 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](#connections):** Aceite ou rejeite um cliente que se conecta à sessão e identifique quem está se conectando.
* **[Processar mensagens](#realtime-messages):** Receba uma mensagem de um cliente, atualize o estado da sessão e responda a um cliente ou transmita para todos.
* **[Agendar trabalho](#scheduled-work):** 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](/pt-BR/developers/backend/resources/actors/reference#connections). Para um fluxo de exemplo, veja [gerenciar conexões de clientes](/pt-BR/developers/backend/resources/actors/sample-flows#manage-client-connections).

### 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](#storage), 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](#wakes) agendado ativa a sessão novamente.

## Cliente

Use [`base44.actors`](/pt-BR/developers/references/sdk/docs/type-aliases/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](/pt-BR/developers/backend/resources/actors/sample-flows#connect-a-client-to-a-session).

## Como actors e clientes interagem

O diagrama a seguir mostra a interação geral entre um cliente e um actor:

```mermaid theme={null}
sequenceDiagram
    participant C as Cliente
    participant A as Actor

    C->>A: 1. connect(sessionId)
    A->>A: 2. handleStart()
    A->>A: 3. handleConnect(conn)
    C->>A: 4. send(data)
    A->>A: 5. handleMessage(conn, msg)
    A-->>C: 6. broadcast(data)
    C->>A: 7. close()
    A->>A: 8. handleClose(conn)
```

1. O cliente se conecta ao actor por um WebSocket.
2. A sessão é ativada. [`handleStart()`](/pt-BR/developers/backend/resources/actors/reference#lifecycle-handlers) é 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()`](/pt-BR/developers/references/sdk/docs/type-aliases/actors#subscribe).

<Note>
  A Base44 oferece vários recursos em tempo real que usam um listener baseado em inscrição:

  * O [`subscribe()`](/pt-BR/developers/references/sdk/docs/type-aliases/actors#subscribe) de actors escuta as mensagens que o actor envia para os clientes conectados.
  * O [`subscribe()`](/pt-BR/developers/references/sdk/docs/type-aliases/entities#subscribe) de entidades escuta mudanças nas entidades do app.

  Verifique qual serviço você usa para receber os eventos esperados.
</Note>

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](#connections). Para um fluxo de exemplo, veja [gerenciar conexões de clientes](/pt-BR/developers/backend/resources/actors/sample-flows#manage-client-connections).

## 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()`](/pt-BR/developers/references/sdk/docs/type-aliases/actors#send), e o actor as recebe em [`handleMessage()`](/pt-BR/developers/backend/resources/actors/reference#lifecycle-handlers).
* **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()`](/pt-BR/developers/backend/resources/actors/reference#connections) ou `broadcast()`, e o cliente as recebe em um callback de [`subscribe()`](/pt-BR/developers/references/sdk/docs/type-aliases/actors#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](/pt-BR/developers/backend/resources/actors/create-actor).
* **Cliente:** Estenda a interface [`ActorRegistry`](/pt-BR/developers/references/sdk/docs/type-aliases/actors#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](#in-memory-storage):** 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](#persistent-storage):** 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](/pt-BR/developers/backend/resources/entities/overview).

Para saber mais sobre o armazenamento de actors, veja [armazenamento](/pt-BR/developers/backend/resources/actors/reference#storage).

### 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()`](/pt-BR/developers/backend/resources/actors/reference#lifecycle-handlers) 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](/pt-BR/developers/backend/resources/actors/sample-flows#persist-session-data).

## Trabalho agendado

Os actors oferecem funcionalidades para que uma sessão execute lógica em uma programação, independentemente das mensagens dos clientes:

* **[Ticks](#ticks):** Executam código em um intervalo e mantêm a sessão ativa enquanto se repetem.
* **[Wakes](#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()`](/pt-BR/developers/backend/resources/actors/reference#timer-handlers-and-settings) 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.

<Note>
  Os ticks precisam de pelo menos um cliente conectado.
</Note>

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](/pt-BR/developers/backend/resources/actors/reference#timer-handlers-and-settings) e [executar ticks](/pt-BR/developers/backend/resources/actors/sample-flows#run-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](/pt-BR/developers/backend/resources/actors/reference#timer-handlers-and-settings) e [agendar wakes](/pt-BR/developers/backend/resources/actors/sample-flows#schedule-wakes) para um fluxo de exemplo.

## Implantar um actor

Implante actors com [`actors deploy`](/pt-BR/developers/references/cli/commands/actors-deploy). Para enviar todos os recursos do projeto de uma vez, use [`deploy`](/pt-BR/developers/references/cli/commands/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`](/pt-BR/developers/references/cli/commands/actors-delete) para excluir o actor remoto da Base44.
* Exclua o diretório do actor do seu projeto local.

<Note>
  Se você não excluir o actor do seu projeto local, o próximo [`actors deploy`](/pt-BR/developers/references/cli/commands/actors-deploy) ou [`deploy`](/pt-BR/developers/references/cli/commands/deploy) recria e implanta o actor no seu projeto da Base44.
</Note>

## Veja também

* [Criar um actor](/pt-BR/developers/backend/resources/actors/create-actor): Arquivos do actor e uma classe mínima
* [Actors: fluxos de exemplo](/pt-BR/developers/backend/resources/actors/sample-flows): Ciclo de vida, timers, conexões, armazenamento, entidades e funções de backend
* [Arquivos e código de actors](/pt-BR/developers/backend/resources/actors/reference): API completa da classe de backend
* [Referência do SDK de `actors`](/pt-BR/developers/references/sdk/docs/type-aliases/actors): API do SDK do cliente

<Note>Esta página foi traduzida usando IA. Para as informações mais precisas e atualizadas, consulte a [versão em inglês](/). </Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.