> ## 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.

# Archivos y código de actores

> Referencia completa de la clase Actor, sus manejadores, conexiones, almacenamiento y temporizadores

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Estás viendo la documentación para desarrolladores
    </div>

    <div className="dev-docs-banner-text">
      Esta documentación es para desarrolladores que trabajan con la plataforma para desarrolladores de Base44.
    </div>
  </div>
</div>

Referencia completa de la clase `Actor` que se ejecuta en el backend de tu app. Para el SDK de cliente que se conecta a una sesión, consulta la [referencia del SDK de `actors`](/es/developers/references/sdk/docs/type-aliases/actors).

Para los conceptos y la terminología de los actores, consulta el [resumen de actores](/es/developers/backend/resources/actors/overview).

## Manejadores obligatorios

La clase `Actor` es abstracta. Implementa el cuerpo de cada uno de los siguientes manejadores. Los manejadores responden a eventos de los clientes y de los temporizadores.

| Manejador | Eventos |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | Un cliente se conecta. |
| [`handleMessage()`](#lifecycle-handlers) | Un cliente conectado envía un mensaje. |
| [`handleClose()`](#lifecycle-handlers) | Un cliente se desconecta. |
| [`handleTick()`](#timer-handlers-and-settings) | En cada intervalo de tick, mientras los ticks están activos. |

## Manejadores opcionales

Implementa estos manejadores cuando tu actor los necesite.

| Manejador | Eventos |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | La sesión se inicia, antes de que Base44 gestione una conexión. |
| [`shouldTick()`](#timer-handlers-and-settings) | Después de cada conexión, mensaje, desconexión y tick. |
| [`handleWake()`](#timer-handlers-and-settings) | Llega una hora definida con `schedule()`. |

Cuando la sesión usa ticks, define [`tickIntervalMs`](#timer-handlers-and-settings). Si omites `shouldTick()`, la sesión nunca usa ticks.

## Métodos que puedes llamar

La clase del actor ofrece funcionalidad integrada. Los siguientes métodos puedes usarlos al implementar los manejadores de un actor.

| Método | Propósito |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | Programa un despertar a la hora que elijas. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | Borra un despertar programado. |
| [`conn.send()`](#connections) | Responde a un cliente. |
| [`conn.reject()`](#connections) | Rechaza a un cliente que se conecta. |
| [`broadcast()`](#connections) | Llega a todos los clientes de la sesión. |
| [`getConnections()`](#connections) | Lista los clientes conectados. |
| [`this.storage.get()`](#storage) | Lee un valor de sesión guardado. |
| [`this.storage.put()`](#storage) | Guarda un valor de sesión. |
| [`this.storage.delete()`](#storage) | Elimina un valor guardado. |
| [`this.storage.deleteAll()`](#storage) | Vacía el almacén de la sesión. |
| [`secrets.get()`](#read-secrets) | Lee un secreto de la app. |

Usa [`this.client`](#entity-access) para leer y escribir [entidades](/es/developers/backend/resources/entities/overview).

## Declaración de la clase

Importa `Actor` desde `base44:runtime/actors` y exporta una clase que extienda `Actor` como exportación predeterminada desde `base44/actors/<actor-name>/entry.ts`.
El nombre de la carpeta se convierte en el nombre del actor en el SDK. Para los detalles de configuración, consulta [crear un actor](/es/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  Tipa los mensajes que el actor recibe de los clientes conectados. Se aplica al
  parámetro `msg` de `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  Tipa los mensajes que el actor envía a los clientes conectados. Se aplica a
  `conn.send()` y `broadcast()`.
</ResponseField>

## API del runtime

Los actores importan la clase `Actor` desde el módulo `base44:runtime/actors`:

```typescript theme={null}
import { Actor } from "base44:runtime/actors";
```

### Leer secretos

Usa `secrets.get()` para leer las variables de entorno de tu app desde un manejador. El método devuelve el valor como cadena, o `undefined` cuando el secreto no está definido.

Importa `secrets` desde el módulo `base44:runtime`:

```typescript theme={null}
import { secrets } from "base44:runtime";
```

Configura los secretos desde la CLI con [`secrets set`](/es/developers/references/cli/commands/secrets-set).

Te recomendamos llamar a una [función de backend](/es/developers/backend/resources/backend-functions/overview) para el trabajo que necesita un secreto. La función lee el secreto y devuelve el resultado, así el actor nunca recibe el secreto. Para ver un flujo de ejemplo, consulta [llamar a una función de backend para trabajo con secretos](/es/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Manejadores del ciclo de vida

Base44 llama a estos manejadores en respuesta a la actividad de los clientes en la sesión.
Tú implementas el cuerpo de cada uno.
Más información sobre [cómo interactúan los actores y los clientes](/es/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
Para ver un flujo de ejemplo, consulta [gestionar las conexiones de clientes](/es/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  Se ejecuta cada vez que una sesión se activa, por ejemplo:

  * Cuando se crea la sesión por primera vez.
  * Cuando un cliente se conecta a una sesión inactiva.
  * Cuando llega un mensaje a una sesión inactiva.
  * Cuando llega una hora programada.

  Devuelve `void` o una `Promise<void>`.
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  Se ejecuta cuando un cliente se conecta a la sesión.
  Puedes enviar el estado actual de la sesión con `conn.send()`, o rechazar la conexión con `conn.reject()`.
  Devuelve `void` o una `Promise<void>`.

  <Expandable title="Parámetros">
    <ResponseField name="conn" type="Conn" required>
      Representa al cliente que se conectó.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  Se ejecuta cuando un cliente conectado envía un mensaje.
  Puedes validar el mensaje antes de cambiar el estado de la sesión o acceder a los datos de la app.
  Devuelve `void` o una `Promise<void>`.

  <Expandable title="Parámetros">
    <ResponseField name="conn" type="Conn" required>
      Representa al cliente que envió el mensaje.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      Contiene el mensaje enviado por el cliente. El genérico `Incoming` define
      el tipo de mensaje.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  Se ejecuta cuando un cliente se desconecta.
  Usa este manejador para eliminar cualquier estado de sesión asociado al ID de conexión.
  Una reconexión que reutiliza el mismo ID sustituye el socket anterior sin ejecutar `handleClose()`.
  Devuelve `void` o una `Promise<void>`.

  <Expandable title="Parámetros">
    <ResponseField name="conn" type="Conn" required>
      Representa al cliente que se desconectó.
    </ResponseField>
  </Expandable>
</ResponseField>

## Manejadores y configuración de temporizadores

Estos manejadores y ajustes controlan el trabajo temporizado de la sesión.
Base44 los llama cuando llega una hora programada, no en respuesta a la actividad de los clientes.
Más información sobre el [trabajo programado](/es/developers/backend/resources/actors/overview#scheduled-work).
Para ver flujos de ejemplo, consulta [ejecutar ticks](/es/developers/backend/resources/actors/sample-flows#run-ticks) y [programar despertares](/es/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  Se ejecuta una vez por intervalo mientras `shouldTick()` devuelve `true` y la sesión tiene al menos un cliente.
  Devuelve `void` o una `Promise<void>`.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  Especifica el intervalo entre ticks en milisegundos. El valor predeterminado es `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  Devuelve un `boolean`. Devuelve `true` para mantener los ticks de la sesión, o `false` para detenerlos. Este método es síncrono.

  Mantén este método rápido y sin efectos secundarios. Base44 llama a este método después de cada conexión, mensaje, desconexión y tick.
</ResponseField>

<ResponseField name="handleWake" type="method">
  Se ejecuta una vez cuando llega una hora definida con `schedule()`.
  Devuelve `void` o una `Promise<void>`.

  <Expandable title="Parámetros">
    <ResponseField name="key" type="string" required>
      Contiene la clave pasada a `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  Programa una ejecución de `handleWake()` a una hora especificada.
  Devuelve una `Promise` que se resuelve después de que Base44 almacena la programación.
  La programación sobrevive a un periodo de inactividad y puede iniciar una sesión inactiva.
  Llamar de nuevo a este método con la misma clave sustituye la hora programada.

  <Expandable title="Parámetros">
    <ResponseField name="key" type="string" required>
      Identifica el despertar programado. Se pasa a `handleWake()` cuando se activa el despertar.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      Especifica cuándo se ejecuta `handleWake()`. Usa un objeto `Date` o los milisegundos
      transcurridos desde el 1 de enero de 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  Cancela el despertar programado asociado a una clave.
  Devuelve una `Promise` que se resuelve después de que Base44 borra la programación.

  <Expandable title="Parámetros">
    <ResponseField name="key" type="string" required>
      Especifica la clave pasada a `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Conexiones

Estas propiedades y métodos están disponibles en el objeto `conn` que se pasa a los manejadores del ciclo de vida que implican a un cliente.
Úsalos para leer la identidad del cliente, enviar mensajes y gestionar la conexión.
Para una descripción general de la mensajería, consulta [mensajes en tiempo real](/es/developers/backend/resources/actors/overview#realtime-messages).
Para ver un flujo de ejemplo, consulta [gestionar las conexiones de clientes](/es/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` es el extremo de backend del WebSocket, y `Connection` en el cliente es el otro extremo del mismo socket. Usa `conn` en la clase del actor. Consulta la referencia del SDK de `actors` para el objeto del cliente.
</Note>

<ResponseField name="conn.id" type="string">
  Identifica esta conexión. Coincide con el ID que pasó el cliente al conectarse,
  o con un ID que generó el SDK.
</ResponseField>

<ResponseField name="conn.identity" type="object">
  Identifica al cliente de esta conexión. Está presente en todas las
  conexiones.

  <Expandable title="Propiedades">
    <ResponseField name="type" type="string" required>
      Contiene `authenticated` o `anonymous`.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Identifica al cliente con sesión iniciada. Está presente cuando `type` es
      `authenticated`.
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      Identifica al cliente anónimo. Está presente cuando `type` es `anonymous`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  Envía un mensaje a esta conexión. Devuelve `void`.

  <Expandable title="Parámetros">
    <ResponseField name="data" type="Outgoing" required>
      Contiene el mensaje que se envía a esta conexión. El genérico `Outgoing` define el tipo de mensaje.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  Rechaza una conexión desde `handleConnect()`. Devuelve `void`.

  <Expandable title="Parámetros">
    <ResponseField name="code" type="number" required>
      Especifica el código de estado que se envía al cliente.
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      Describe por qué el actor rechazó la conexión.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  Envía un mensaje a todas las conexiones activas de la sesión. Devuelve `void`.

  <Expandable title="Parámetros">
    <ResponseField name="data" type="Outgoing" required>
      Contiene el mensaje que se envía a todas las conexiones de la sesión. El genérico `Outgoing` define el tipo de mensaje.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  Devuelve un array de los objetos `conn` activos de la sesión. Usa este método en
  `handleStart()` para asociar los datos restaurados con los clientes que siguieron conectados
  durante un periodo de inactividad.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  Propiedad a nivel de sesión. Contiene el ID de sesión que usó el cliente para llegar
  a esta sesión.
</ResponseField>

## Almacenamiento

Usa `this.storage` para leer y escribir datos de la sesión. A diferencia de los campos de clase, el almacenamiento sobrevive a los periodos de inactividad. Para elegir entre el almacenamiento y los campos de clase, consulta [almacenamiento](/es/developers/backend/resources/actors/overview#storage). Para ver un flujo de ejemplo, consulta [conservar los datos de sesión](/es/developers/backend/resources/actors/sample-flows#persist-session-data).

<ResponseField name="this.storage.get" type="method">
  Recupera un valor por clave. Devuelve una `Promise` que se resuelve con el valor
  almacenado, o `undefined` cuando la clave no existe.

  <Expandable title="Parámetros">
    <ResponseField name="key" type="string" required>
      Especifica la clave que se recupera.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  Guarda un valor por clave. Sustituye el valor ya almacenado con esa clave. Devuelve
  una `Promise` que se resuelve cuando termina la escritura.

  <Expandable title="Parámetros">
    <ResponseField name="key" type="string" required>
      Especifica la clave que se guarda.
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      Especifica el valor compatible con JSON que se guarda.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  Elimina un valor por clave. Devuelve una `Promise` que se resuelve con `true` cuando la
  clave existía, y con `false` en caso contrario.

  <Expandable title="Parámetros">
    <ResponseField name="key" type="string" required>
      Especifica la clave que se elimina.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  Elimina todos los datos guardados de la sesión. Devuelve una `Promise` que se resuelve cuando
  el almacén está vacío. Una conexión posterior empieza con el mismo almacenamiento vacío que
  una sesión nueva.
</ResponseField>

## Acceso a entidades

Usa `this.client` y `this.client.asServiceRole` para leer y escribir entidades de la app desde dentro de un manejador del actor. Para ver un flujo de ejemplo, consulta [escribir datos de entidades desde una sesión](/es/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  Proporciona un cliente de la app limitado a esta sesión. Este cliente usa autenticación
  anónima, así que el acceso a las entidades sigue las mismas reglas que un cliente
  sin sesión iniciada, y lee datos de producción.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  Proporciona acceso elevado que omite la seguridad a nivel de fila. Valida los mensajes
  antes de usar este cliente. Haz que las escrituras se puedan repetir de forma segura, porque la sesión puede volver a ejecutar un manejador
  después de un error.
</ResponseField>

## Ver también

* [Resumen de actores](/es/developers/backend/resources/actors/overview): Conceptos y terminología
* [Actores: flujos de ejemplo](/es/developers/backend/resources/actors/sample-flows): Ciclo de vida, temporizadores, conexiones, almacenamiento, entidades y funciones de backend
* [Referencia del SDK de `actors`](/es/developers/references/sdk/docs/type-aliases/actors): API del SDK de cliente
* [`secrets set`](/es/developers/references/cli/commands/secrets-set): Configura variables de entorno desde la CLI

<Note>Esta página fue traducida con IA. Para obtener la información más precisa y actualizada, consulta la [versión en inglés](/). </Note>


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