Skip to main content
Stai visualizzando la documentazione per sviluppatori
Questa documentazione è per sviluppatori che lavorano con la piattaforma per sviluppatori di Base44.
Un actor è un processo di backend di lunga durata a cui più client si connettono contemporaneamente. Con gli actor puoi creare istanze di sessioni live che supportano le seguenti funzionalità:
  • Messaggi in tempo reale: Invia e ricevi messaggi con i client tramite WebSocket.
  • Storage persistente: Mantieni lo stato della sessione tra i periodi di inattività.
  • Lavoro pianificato: Esegui logica a un intervallo fisso o in un momento specifico.
Usa gli actor quando crei funzionalità in cui più client richiedono aggiornamenti e interazioni in tempo reale, come una chat room o un gioco multiplayer.

​
Actor

Actor è la classe che estendi nel tuo backend. La classe actor definisce il comportamento di una sessione live. Con gli actor puoi:
  • Gestire le connessioni: Accettare o rifiutare un client che si connette alla sessione e identificare chi si connette.
  • Gestire i messaggi: Ricevere un messaggio da un client, aggiornare lo stato della sessione e rispondere a un client o trasmettere a tutti.
  • Pianificare il lavoro: Eseguire logica a intervalli o in un momento pianificato.

​
Sessioni

Una sessione è un’istanza in esecuzione di un actor, identificata dal nome dell’actor e da un ID di sessione che scegli tu.
Ogni sessione gestisce in modo indipendente il proprio stato, lo storage e le connessioni dei client.

​
Connessioni

Una connessione rappresenta il WebSocket di un client verso una sessione. Ogni client che si unisce ottiene una connessione univoca. Un actor usa quella connessione per identificare chi si connette, gestire le connessioni dei client e inviare messaggi. Per saperne di più, consulta connessioni. Per un flusso di esempio, consulta gestire le connessioni dei client.

​
Sessioni attive e inattive

Una sessione si trova sempre in uno dei seguenti stati:
  • Attiva: La sessione è live ed elabora eventi. Una sessione diventa attiva quando un client si connette, quando un client invia un messaggio a una sessione inattiva o quando arriva l’orario di un wake pianificato.
  • Inattiva: La sessione non elabora eventi. Una sessione diventa inattiva poco dopo aver finito l’ultimo messaggio e quando tutto il lavoro pianificato si ferma. La sessione mantiene i dati salvati, gli orari pianificati e le connessioni aperte finché non torna attiva.
Quando una sessione diventa inattiva, i client con connessioni aperte restano connessi. Il loro messaggio successivo o un wake pianificato riattiva la sessione.

​
Client

Usa base44.actors nell’SDK JavaScript per connettere un client a una sessione di un actor e scambiare messaggi. L’SDK degli actor supporta le seguenti funzionalità:
  • Connect: Apre una connessione WebSocket a una sessione.
  • Subscribe: Riceve messaggi dall’actor.
  • Send: Invia messaggi all’actor.
  • Close: Chiude la connessione WebSocket all’actor.
Per saperne di più, consulta connettere un client a una sessione.

​
Come interagiscono actor e client

Il diagramma seguente mostra l’interazione generale tra un client e un actor:
  1. Il client si connette all’actor tramite un WebSocket.
  2. La sessione si attiva. handleStart() viene eseguito al primo avvio e ogni volta che la sessione si riattiva dallo stato inattivo.
  3. L’actor gestisce la connessione. Puoi verificare l’identità del client e rifiutare la connessione, oppure inviare lo stato attuale.
  4. Il client invia un messaggio.
  5. L’actor gestisce il messaggio. Puoi validare il formato e i permessi del mittente prima di modificare lo stato della sessione.
  6. L’actor trasmette l’aggiornamento a tutti i client connessi, oppure risponde solo al mittente.
  7. Il client chiude la connessione.
  8. L’actor gestisce la disconnessione. Puoi rimuovere lo stato legato alla connessione.

​
Messaggi in tempo reale

Ogni client connesso appartiene a una sessione e può inviare messaggi in tempo reale tramite WebSocket. I client possono anche ascoltare i messaggi in arrivo con subscribe().
Base44 offre diverse funzionalità in tempo reale che usano un listener basato su sottoscrizione:
  • subscribe() degli actor ascolta i messaggi che l’actor invia ai client connessi.
  • subscribe() delle entità ascolta le modifiche alle entità dell’app.
Verifica quale servizio usi per ricevere gli eventi che ti aspetti.
Con i messaggi in tempo reale puoi:
  • Rispondere a un client specifico.
  • Trasmettere a tutti i client connessi.
  • Elencare i client attualmente connessi.
  • Identificare ogni client e verificare se ha effettuato l’accesso.
Per saperne di più, consulta connessioni. Per un flusso di esempio, consulta gestire le connessioni dei client.

​
Tipi di messaggi

Un client e un actor si scambiano messaggi tramite una connessione. I messaggi rientrano nei seguenti tipi:
  • Messaggi in entrata: Ciò che un client connesso invia all’actor, come un testo, una mossa o un voto. Il client li invia con send() e l’actor li riceve in handleMessage().
  • Messaggi in uscita: Ciò che l’actor invia ai client connessi, come una risposta a un client, una trasmissione a tutti i client connessi o la plancia attuale quando qualcuno si unisce. L’actor li invia con conn.send() o broadcast() e il client li riceve in una callback di subscribe().
Ti consigliamo di tipizzare i messaggi, così l’actor e il client concordano sulla forma di ogni messaggio:
  • Backend: Passa i tipi Incoming e Outgoing come generici alla classe Actor. Per un esempio completo, consulta creare un actor.
  • Client: Estendi l’interfaccia ActorRegistry con le stesse forme, così TypeScript controlla i tipi di send() e subscribe().

​
Storage

Gli actor offrono diverse opzioni di storage a seconda di come la sessione usa e conserva i dati:
  • Storage in memoria: Stato di lavoro che vive nei campi della classe mentre la sessione è attiva e si azzera quando la sessione diventa inattiva.
  • Storage persistente: Un archivio chiave-valore per i dati che devono sopravvivere quando la sessione diventa inattiva.

​
Storage in memoria

I campi della classe contengono lo stato di lavoro mentre la sessione è attiva, come la plancia attuale o il timer di un round. Usa lo storage in memoria quando i dati cambiano spesso e non devono persistere quando la sessione diventa inattiva, come un punteggio live o la posizione di un cursore. Quando una sessione diventa inattiva, i campi della classe si azzerano.

​
Storage persistente

Ogni sessione ha un proprio archivio chiave-valore che puoi gestire completamente. Usa lo storage persistente quando i dati devono sopravvivere quando la sessione diventa inattiva, come la cronologia della chat o la plancia di gioco. Per salvare dati disponibili in tutta l’app, usa le entità. Per saperne di più sullo storage degli actor, consulta storage.

​
Ripristinare lo stato

Quando una sessione diventa inattiva, lo stato in memoria si azzera. Lo storage persistente sopravvive, ma la sessione non ricarica automaticamente in memoria i dati salvati quando si attiva. Usa handleStart() per ripristinare i dati persistenti, come la cronologia della chat o la plancia di gioco. Per un flusso di esempio, consulta rendere persistenti i dati di sessione.

​
Lavoro pianificato

Gli actor permettono a una sessione di eseguire logica secondo una pianificazione, indipendentemente dai messaggi dei client:
  • Tick: Eseguono codice a intervalli e mantengono attiva la sessione mentre si ripetono.
  • Wake: Vengono eseguiti una volta nel momento che scegli, sia che la sessione sia attiva sia che sia inattiva.

​
Tick

I tick eseguono codice a intervalli e mantengono attiva la sessione mentre si ripetono. Usa shouldTick() per impostare le condizioni in cui vengono eseguiti i tick. Un actor rivaluta shouldTick() dopo ogni connessione, messaggio, disconnessione e tick. Così i tick si fermano appena la condizione non è più soddisfatta.
I tick richiedono almeno un client connesso.
Con i tick puoi:
  • Scegliere la durata di ogni intervallo.
  • Definire una condizione che avvia e ferma i tick, come “almeno due giocatori sono nella sessione”.
  • Scrivere il codice eseguito a ogni intervallo.
Usa i tick per mantenere attiva una sessione anche quando i client non inviano messaggi, ad esempio per aggiornare il timer di un round. Per saperne di più sui tick, consulta handler e impostazioni dei timer e, per un flusso di esempio, eseguire i tick.

​
Wake

Un wake viene eseguito una volta nel momento che scegli, sia che la sessione sia attiva sia che sia inattiva. Con i wake puoi:
  • Pianificare quando viene eseguito un wake.
  • Implementare la logica eseguita quando si verifica un wake.
Usa un wake per pianificare un’azione singola, come terminare un turno di gioco, chiudere una lobby vuota, attivare un promemoria o avviare un evento in un momento specifico. Per saperne di più sui wake, consulta handler e impostazioni dei timer e, per un flusso di esempio, pianificare i wake.

​
Distribuire un actor

Distribuisci gli actor con actors deploy. Per pubblicare tutte le risorse del progetto in una volta, usa deploy. La distribuzione aggiunge e aggiorna gli actor remoti e lascia invariati gli altri.

​
Eliminare un actor

Per eliminare un actor:
  • Esegui actors delete per eliminare l’actor remoto da Base44.
  • Elimina la directory dell’actor dal tuo progetto locale.
Se non elimini l’actor dal tuo progetto locale, il successivo actors deploy o deploy ricrea e distribuisce l’actor nel tuo progetto Base44.

​
Vedi anche

Questa pagina è stata tradotta con l’AI. Per le informazioni più accurate e aggiornate, consulta la versione inglese.