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

# File e codice degli actor

> Riferimento completo per la classe Actor, i suoi handler, le connessioni, lo storage e i timer

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Stai visualizzando la documentazione per sviluppatori
    </div>

    <div className="dev-docs-banner-text">
      Questa documentazione è per sviluppatori che lavorano con la piattaforma
      per sviluppatori di Base44.
    </div>
  </div>
</div>

Riferimento completo per la classe `Actor` eseguita nel backend della tua app. Per l'SDK client che si connette a una sessione, consulta il [riferimento SDK `actors`](/it/developers/references/sdk/docs/type-aliases/actors).

Per i concetti e la terminologia degli actor, consulta la [panoramica degli actor](/it/developers/backend/resources/actors/overview).

## Handler obbligatori

La classe `Actor` è astratta. Implementa il corpo di ciascuno dei seguenti handler. Gli handler rispondono agli eventi dei client e dei timer.

| Handler | Eventi |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | Un client si connette. |
| [`handleMessage()`](#lifecycle-handlers) | Un client connesso invia un messaggio. |
| [`handleClose()`](#lifecycle-handlers) | Un client si disconnette. |
| [`handleTick()`](#timer-handlers-and-settings) | A ogni intervallo di tick, mentre i tick sono attivi. |

## Handler facoltativi

Implementa questi handler quando servono al tuo actor.

| Handler | Eventi |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | La sessione si avvia, prima che Base44 gestisca una connessione. |
| [`shouldTick()`](#timer-handlers-and-settings) | Dopo ogni connessione, messaggio, disconnessione e tick. |
| [`handleWake()`](#timer-handlers-and-settings) | Arriva un orario impostato con `schedule()`. |

Quando la sessione usa i tick, imposta [`tickIntervalMs`](#timer-handlers-and-settings). Se ometti `shouldTick()`, la sessione non esegue mai tick.

## Metodi da chiamare

La classe actor offre funzionalità integrate. Di seguito i metodi che puoi usare quando implementi gli handler di un actor.

| Metodo | Scopo |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | Pianifica un wake nel momento che scegli. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | Annulla un wake pianificato. |
| [`conn.send()`](#connections) | Risponde a un client. |
| [`conn.reject()`](#connections) | Rifiuta un client che si connette. |
| [`broadcast()`](#connections) | Raggiunge tutti i client della sessione. |
| [`getConnections()`](#connections) | Elenca i client connessi. |
| [`this.storage.get()`](#storage) | Legge un valore di sessione salvato. |
| [`this.storage.put()`](#storage) | Salva un valore di sessione. |
| [`this.storage.delete()`](#storage) | Rimuove un valore salvato. |
| [`this.storage.deleteAll()`](#storage) | Svuota l'archivio della sessione. |
| [`secrets.get()`](#read-secrets) | Legge un secret dell'app. |

Usa [`this.client`](#entity-access) per leggere e scrivere le [entità](/it/developers/backend/resources/entities/overview).

## Dichiarazione della classe

Importa `Actor` da `base44:runtime/actors` ed esporta una classe che estende `Actor` come export predefinito di `base44/actors/<actor-name>/entry.ts`.
Il nome della cartella diventa il nome dell'actor nell'SDK. Per i dettagli di configurazione, consulta [creare un actor](/it/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  Tipizza i messaggi che l'actor riceve dai client connessi. Si applica al
  parametro `msg` di `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  Tipizza i messaggi che l'actor invia ai client connessi. Si applica a
  `conn.send()` e `broadcast()`.
</ResponseField>

## API di runtime

Gli actor importano la classe `Actor` dal modulo `base44:runtime/actors`:

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

### Leggere i secret

Usa `secrets.get()` per leggere le variabili d'ambiente della tua app da un handler. Il metodo restituisce il valore come stringa, oppure `undefined` se il secret non è impostato.

Importa `secrets` dal modulo `base44:runtime`:

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

Configura i secret dalla CLI con [`secrets set`](/it/developers/references/cli/commands/secrets-set).

Ti consigliamo di chiamare una [funzione backend](/it/developers/backend/resources/backend-functions/overview) per le operazioni che richiedono un secret. La funzione legge il secret e restituisce il risultato, così l'actor non riceve mai il secret. Per un flusso di esempio, consulta [chiamare una funzione backend per operazioni con secret](/it/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Handler del ciclo di vita

Base44 chiama questi handler in risposta all'attività dei client nella sessione.
Sei tu a implementare il corpo di ciascuno.
Scopri di più su [come interagiscono actor e client](/it/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
Per un flusso di esempio, consulta [gestire le connessioni dei client](/it/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  Viene eseguito ogni volta che una sessione si attiva, ad esempio:

  * Quando la sessione viene creata per la prima volta.
  * Quando un client si connette a una sessione inattiva.
  * Quando arriva un messaggio a una sessione inattiva.
  * Quando arriva un orario pianificato.

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

<ResponseField name="handleConnect" type="method" required>
  Viene eseguito quando un client si connette alla sessione.
  Puoi inviare lo stato attuale della sessione con `conn.send()` o rifiutare la connessione con `conn.reject()`.
  Restituisce `void` o una `Promise<void>`.

  <Expandable title="Parametri">
    <ResponseField name="conn" type="Conn" required>
      Rappresenta il client che si è connesso.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  Viene eseguito quando un client connesso invia un messaggio.
  Puoi validare il messaggio prima di modificare lo stato della sessione o accedere ai dati dell'app.
  Restituisce `void` o una `Promise<void>`.

  <Expandable title="Parametri">
    <ResponseField name="conn" type="Conn" required>
      Rappresenta il client che ha inviato il messaggio.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      Contiene il messaggio inviato dal client. Il generico `Incoming` definisce
      il tipo di messaggio.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  Viene eseguito quando un client si disconnette.
  Usa questo handler per rimuovere qualsiasi stato di sessione associato all'ID della connessione.
  Una riconnessione che riusa lo stesso ID sostituisce il vecchio socket senza eseguire `handleClose()`.
  Restituisce `void` o una `Promise<void>`.

  <Expandable title="Parametri">
    <ResponseField name="conn" type="Conn" required>
      Rappresenta il client che si è disconnesso.
    </ResponseField>
  </Expandable>
</ResponseField>

## Handler e impostazioni dei timer

Questi handler e impostazioni controllano il lavoro temporizzato nella sessione.
Base44 li chiama quando arriva un orario pianificato, non in risposta all'attività dei client.
Scopri di più sul [lavoro pianificato](/it/developers/backend/resources/actors/overview#scheduled-work).
Per flussi di esempio, consulta [eseguire i tick](/it/developers/backend/resources/actors/sample-flows#run-ticks) e [pianificare i wake](/it/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  Viene eseguito una volta per intervallo mentre `shouldTick()` restituisce `true` e la sessione ha almeno un client.
  Restituisce `void` o una `Promise<void>`.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  Specifica l'intervallo tra i tick in millisecondi. Il valore predefinito è `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  Restituisce un `boolean`. Restituisci `true` per continuare i tick della sessione, oppure `false` per fermarli. Questo metodo è sincrono.

  Mantieni questo metodo veloce e privo di effetti collaterali. Base44 chiama questo metodo dopo ogni connessione, messaggio, disconnessione e tick.
</ResponseField>

<ResponseField name="handleWake" type="method">
  Viene eseguito una volta quando arriva un orario impostato con `schedule()`.
  Restituisce `void` o una `Promise<void>`.

  <Expandable title="Parametri">
    <ResponseField name="key" type="string" required>
      Contiene la chiave passata a `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  Pianifica un'esecuzione di `handleWake()` in un momento specificato.
  Restituisce una `Promise` che si risolve dopo che Base44 ha salvato la pianificazione.
  La pianificazione sopravvive a un periodo di inattività e può avviare una sessione inattiva.
  Chiamare di nuovo questo metodo con la stessa chiave sostituisce l'orario pianificato.

  <Expandable title="Parametri">
    <ResponseField name="key" type="string" required>
      Identifica il wake pianificato. Viene passata a `handleWake()` quando il wake si attiva.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      Specifica quando viene eseguito `handleWake()`. Usa un oggetto `Date` o i millisecondi
      dal 1° gennaio 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  Annulla il wake pianificato associato a una chiave.
  Restituisce una `Promise` che si risolve dopo che Base44 ha eliminato la pianificazione.

  <Expandable title="Parametri">
    <ResponseField name="key" type="string" required>
      Specifica la chiave passata a `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Connessioni

Queste proprietà e metodi sono disponibili sull'oggetto `conn` passato agli handler del ciclo di vita che coinvolgono un client.
Usali per leggere l'identità del client, inviare messaggi e gestire la connessione.
Per una panoramica dei messaggi, consulta [messaggi in tempo reale](/it/developers/backend/resources/actors/overview#realtime-messages).
Per un flusso di esempio, consulta [gestire le connessioni dei client](/it/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` è l'estremità backend del WebSocket, mentre `Connection` nel client è l'altra estremità dello stesso socket. Usa `conn` nella classe actor. Consulta il riferimento SDK `actors` per l'oggetto client.
</Note>

<ResponseField name="conn.id" type="string">
  Identifica questa connessione. Corrisponde all'ID passato dal client durante la connessione,
  oppure a un ID generato dall'SDK.
</ResponseField>

<ResponseField name="conn.identity" type="object">
  Identifica il client su questa connessione. Presente su tutte le
  connessioni.

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

    <ResponseField name="userId" type="string">
      Identifica il client che ha effettuato l'accesso. Presente quando `type` è
      `authenticated`.
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      Identifica il client anonimo. Presente quando `type` è `anonymous`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  Invia un messaggio a questa connessione. Restituisce `void`.

  <Expandable title="Parametri">
    <ResponseField name="data" type="Outgoing" required>
      Contiene il messaggio da inviare a questa connessione. Il generico `Outgoing` definisce il tipo di messaggio.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  Rifiuta una connessione da `handleConnect()`. Restituisce `void`.

  <Expandable title="Parametri">
    <ResponseField name="code" type="number" required>
      Specifica il codice di stato inviato al client.
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      Descrive perché l'actor ha rifiutato la connessione.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  Invia un messaggio a ogni connessione attiva nella sessione. Restituisce `void`.

  <Expandable title="Parametri">
    <ResponseField name="data" type="Outgoing" required>
      Contiene il messaggio da inviare a ogni connessione della sessione. Il generico `Outgoing` definisce il tipo di messaggio.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  Restituisce un array degli oggetti `conn` attivi nella sessione. Usa questo metodo in
  `handleStart()` per associare i dati ripristinati ai client rimasti connessi
  durante un periodo di inattività.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  Proprietà a livello di sessione. Contiene l'ID di sessione usato dal client per raggiungere
  questa sessione.
</ResponseField>

## Storage

Usa `this.storage` per leggere e scrivere i dati di sessione. A differenza dei campi della classe, lo storage sopravvive ai periodi di inattività. Per scegliere tra storage e campi della classe, consulta [storage](/it/developers/backend/resources/actors/overview#storage). Per un flusso di esempio, consulta [rendere persistenti i dati di sessione](/it/developers/backend/resources/actors/sample-flows#persist-session-data).

<ResponseField name="this.storage.get" type="method">
  Recupera un valore tramite chiave. Restituisce una `Promise` che si risolve nel valore
  salvato, oppure in `undefined` se la chiave non esiste.

  <Expandable title="Parametri">
    <ResponseField name="key" type="string" required>
      Specifica la chiave da recuperare.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  Salva un valore tramite chiave. Sostituisce il valore già salvato con quella chiave. Restituisce
  una `Promise` che si risolve al completamento della scrittura.

  <Expandable title="Parametri">
    <ResponseField name="key" type="string" required>
      Specifica la chiave da salvare.
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      Specifica il valore compatibile con JSON da salvare.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  Rimuove un valore tramite chiave. Restituisce una `Promise` che si risolve in `true` se la
  chiave esisteva, altrimenti in `false`.

  <Expandable title="Parametri">
    <ResponseField name="key" type="string" required>
      Specifica la chiave da rimuovere.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  Rimuove tutti i dati salvati per la sessione. Restituisce una `Promise` che si risolve quando
  l'archivio è vuoto. Una connessione successiva parte con lo stesso storage vuoto di una
  nuova sessione.
</ResponseField>

## Accesso alle entità

Usa `this.client` e `this.client.asServiceRole` per leggere e scrivere le entità dell'app dall'interno di un handler dell'actor. Per un flusso di esempio, consulta [scrivere dati delle entità da una sessione](/it/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  Fornisce un client dell'app limitato a questa sessione. Questo client usa l'autenticazione
  anonima, quindi l'accesso alle entità segue le stesse regole di un client senza accesso.
  Legge i dati di produzione.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  Fornisce un accesso elevato che aggira la sicurezza a livello di riga. Valida i messaggi
  prima di usare questo client. Rendi le scritture sicure da ripetere, perché la sessione può eseguire
  di nuovo un handler dopo un errore.
</ResponseField>

## Vedi anche

* [Panoramica degli actor](/it/developers/backend/resources/actors/overview): Concetti e terminologia
* [Actor: flussi di esempio](/it/developers/backend/resources/actors/sample-flows): Ciclo di vita, timer, connessioni, storage, entità e funzioni backend
* [Riferimento SDK `actors`](/it/developers/references/sdk/docs/type-aliases/actors): API dell'SDK client
* [`secrets set`](/it/developers/references/cli/commands/secrets-set): Configura le variabili d'ambiente dalla CLI

<Note>Questa pagina è stata tradotta con l'AI. Per le informazioni più accurate e aggiornate, consulta la [versione inglese](/). </Note>


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