# Benvenuto della community

> Le schermate che la persona nuova vede al primo accesso (testo, video, regole da accettare e campi del profilo), la modalità obbligatoria o saltabile, chi le vede, e i Primi passi, con fino a 6 missioni, punti, badge e congratulazioni alla fine.

Il **benvenuto** è l'insieme delle schermate che la persona nuova vede al primo accesso, prima della community: un testo di presentazione, il video di benvenuto, le regole da leggere e accettare, i campi del profilo che la community vuole conoscere. Dopo arrivano i **Primi passi**, una scheda con fino a 6 missioni (completare il profilo, fare il primo post, andare al primo evento) che si completano da sole con l'uso e possono dare punti e badge.

**Dove si trova:** in **Impostazioni › Benvenuto**, per il proprietario e l'amministratore.

## A cosa serve

| Community | Come lo usa |
|---|---|
| Community con un codice di condotta | La prima schermata mostra le regole con **Ho letto e accetto**; nessuno entra senza accettare, e l'accettazione viene registrata con la data e il testo |
| Scuola online | Un video di benvenuto da guardare fino alla fine, e una missione "Completa la lezione inaugurale" |
| Community professionale | Una schermata chiede ruolo, azienda e interessi (campi personalizzati); le missioni portano alla prima presentazione nel Feed e al primo evento |
| Community aperta | Benvenuto saltabile: chi ha fretta entra subito, e la scheda dei Primi passi resta nel Feed |

## Chi può

| Ruolo | Cosa fa |
|---|---|
| Proprietario e amministratore | Configurano le schermate, la modalità e i Primi passi, e vedono quanti hanno completato, saltato o sono in sospeso |
| Moderatore e finanza | Filtrano la lista dei membri per stato del benvenuto; non cambiano la configurazione |
| Membro | Passa dal benvenuto e vede la propria scheda dei Primi passi |

Il team (proprietario, amministratore, moderatore e finanza) **non** passa mai dal benvenuto e non vede la scheda dei Primi passi.

## Come funziona

### Le schermate

Da **1 a 5 schermate**, nell'ordine in cui la persona le vedrà. Ogni schermata ha:

- **Titolo** (fino a 120 caratteri) e **testo**, con formattazione.
- **Video**, facoltativo: **Nessun video**, **Carica un video** (fino a 2 GB) o **Link YouTube o Vimeo**. Solo il video caricato può avere **Continua solo dopo averlo guardato fino alla fine**; con un link esterno non si può richiedere.
- **Regole**, facoltative: in **Chiedi di accettare le regole**, il testo delle regole, una per riga. La persona continua solo selezionando **Ho letto e accetto le regole**. L'accettazione viene salvata con la data e il testo accettato in quel momento, anche se le regole cambiano dopo.
- **Campi del profilo**, facoltativi: fino a 20 [campi personalizzati](/membros/campos-customizados) per schermata, con gli stessi controlli del profilo. Un campo obbligatorio va compilato per andare avanti.

La persona vede le schermate in ordine (*Passo 1 di 3*), con **Continua** e, nell'ultima, **Entra nella community**; se esce a metà, riprende da dove si era fermata. **Vedi come membro** mostra le schermate come le vede un nuovo membro, senza registrare nulla.

### La modalità

| Modalità | Cosa succede |
|---|---|
| **Obbligatorio** (predefinito) | La community resta bloccata finché la persona non completa l'ultima schermata |
| **Si può saltare** | La persona vede **Salta il benvenuto**; chi salta entra e non gli viene chiesto di nuovo |

Il benvenuto arriva **prima** di *Completa la tua registrazione* (vedi [Registrazione e accesso](/membros/cadastro-e-entrada#la-registrazione)): se dopo manca ancora un campo obbligatorio, la finestra di registrazione arriva subito dopo.

### Chi lo vede

Quando attivi il benvenuto, scegli se vale anche per chi è già membro:

- **Non selezionato** (predefinito): lo vedono solo i membri che entrano **da adesso in poi**.
- **Applica anche a chi è già membro**: tutti i membri lo vedono al prossimo accesso.

Disattivarlo fa entrare subito chi era in sospeso. **Riattivarlo non raggiunge chi è entrato mentre era disattivato**: il conteggio riparte quando lo riattivi, a meno che **Applica anche a chi è già membro** sia selezionato. A chi ha già completato o saltato non viene mai chiesto di nuovo.

### Primi passi

Nella stessa schermata, sotto le schermate, i **Primi passi**: da 1 a **6 missioni**, ognuna con il testo che appare nella scheda (**Come appare nella scheda**, fino a 80 caratteri) e, in **Quando la persona**, un'azione che la piattaforma già segue:

| Quando la persona | Si completa quando… |
|---|---|
| **Completa il profilo** | ha la foto e tutti i campi obbligatori compilati |
| **Pubblica per la prima volta in uno spazio** | pubblica nello spazio scelto |
| **Risponde a un modulo** | risponde al [modulo](/espacos/formularios) scelto |
| **Si iscrive a un evento** | si iscrive a un evento (**Qualsiasi evento**, o quello scelto) |
| **Completa un corso** | completa il corso scelto |

- Ogni missione può dare **punti** (da 0 a 10.000, con la [gamification](/membros/gamificacao) attiva) e un **badge** (vedi [Badge](/membros/engajamento#badge)). Completarle tutte può dare un **badge finale** (**Badge al completamento di tutte**).
- La missione viene segnata **entro circa 1 minuto** dall'azione, senza che la persona faccia nulla. Quella del profilo viene controllata anche quando si apre la scheda.
- **Quello che è stato fatto prima che la missione esistesse non conta.** Cambiare l'azione o l'elemento di una missione fa ripartire anche il suo conteggio; cambiare solo il titolo, i punti o il badge mantiene chi l'ha già completata.
- Valgono per i membri che entrano dopo l'attivazione dei Primi passi, o per tutti con **Mostra a chi è già membro**.

**La scheda.** La persona vede la scheda **Primi passi**, con l'avanzamento (*2 di 4*) e i punti di ogni missione, in cima alla colonna del Feed (anche con i widget disattivati) e nella propria pagina di membro, dopo il benvenuto. Completate tutte, vede le **congratulazioni una sola volta**, riceve il badge finale e la scheda sparisce. **Ignora** nasconde la scheda per sempre, e da quel momento nessuna missione conta.

### Monitorare

La configurazione mostra quanti membri hanno **completato**, **saltato** o sono **in sospeso** nel benvenuto e, nei Primi passi, quanti hanno **iniziato** (almeno una missione), **completato** e **ignorato**, con quanti hanno completato ogni missione.

Nella [lista dei membri](/membros/gerenciar-membros), il team usa il filtro **Benvenuto** (**In sospeso**, **Completato** o **Saltato**). La pagina di ogni membro mostra al team il blocco **Benvenuto e primi passi**, con lo stato del benvenuto e l'avanzamento nelle missioni.

### Automatizzare con i workflow

Due trigger di [workflow](/notificacoes/workflows) nel blocco **Membri**:

- **Ha completato il benvenuto**: la persona ha completato l'ultima schermata. Saltarlo non lo attiva.
- **Ha completato i primi passi**: la persona ha completato tutte le missioni, una volta per persona.

Entrambi arrivano anche ai [webhook](/api/eventos-de-webhook).

## Passo dopo passo

### Benvenuto con regole e video

*Ruolo: proprietario o amministratore.*

1. Apri **Impostazioni › Benvenuto**.
2. Nella **Schermata 1**, dai il titolo *Benvenuta nella community*, un testo breve e, in **Video**, **Carica un video**, con **Continua solo dopo averlo guardato fino alla fine**.
3. **Aggiungi schermata**: nella **Schermata 2**, seleziona **Chiedi di accettare le regole**, scrivi le regole e scegli i campi *Ruolo* e *Azienda* in **Campi del profilo**.
4. In **Per il membro**, lascia **Obbligatorio**. Attiva **Benvenuto attivo** e decidi se selezionare **Applica anche a chi è già membro**.
5. Controlla con **Vedi come membro** e salva.

### Primi passi con badge finale

1. Nella stessa schermata, attiva i **Primi passi** e usa **Aggiungi missione**: *Completa il tuo profilo* (**Completa il profilo**, 50 punti), *Presentati nel Feed* (**Pubblica per la prima volta in uno spazio**, spazio *Presentazioni*, 50 punti) e *Iscriviti al prossimo incontro* (**Si iscrive a un evento**, **Qualsiasi evento**).
2. In **Badge al completamento di tutte**, scegli *Pioniera*, decidi su **Mostra a chi è già membro** e salva.

## Esempio

Maria entra nella community. Prima di vedere qualsiasi spazio, guarda il video fino alla fine, accetta le regole e compila *Ruolo*. Nel Feed trova la scheda *Primi passi · 0 di 3*. Completa il profilo e pubblica la presentazione: entro circa 1 minuto la scheda mostra *2 di 3* e ha 100 punti. La settimana dopo si iscrive a un incontro, vede le congratulazioni, ottiene il badge *Pioniera*, e il workflow con **Ha completato i primi passi** la aggiunge al gruppo *Membri attivi*.

## Errori comuni e come risolverli

| Situazione | Cosa fare |
|---|---|
| Ho attivato il benvenuto e chi era già membro non l'ha visto | È il comportamento predefinito. Seleziona **Applica anche a chi è già membro** |
| Non riesco a richiedere che il video sia guardato fino alla fine | Solo il video caricato lo permette; con un link di YouTube o Vimeo, no |
| L'ho riattivato e chi è entrato mentre era disattivato non l'ha visto | Riattivare vale solo per chi entra da quel momento; seleziona **Applica anche a chi è già membro** |
| La missione non è stata segnata | Aspetta circa 1 minuto. Verifica che l'azione sia avvenuta nello spazio, modulo o corso scelto e dopo che la missione esisteva |
| La missione del profilo non viene segnata | Manca la foto o un campo obbligatorio del profilo |
| La missione non ha dato punti | La [gamification](/membros/gamificacao) deve essere attiva |
| Non riesco ad attivarlo senza schermate (o missioni) | Serve almeno una schermata per attivare il benvenuto, e una missione per attivare i Primi passi |

## Domande frequenti

**Il team passa dal benvenuto?**
No. Proprietario, amministratore, moderatore e finanza entrano subito e non vedono la scheda dei Primi passi.

**La persona può rivedere il benvenuto?**
No: dopo averlo completato o saltato, non le viene chiesto di nuovo, anche se cambi le schermate.

**Devo segnare le missioni a mano?**
No. Ogni missione si completa con l'uso, entro circa 1 minuto.

**Il membro può ignorare la scheda?**
Può chiuderla con **Ignora**. Sparisce per sempre, e le missioni smettono di contare per quella persona.

## Nell'API

`GET` e `PUT /api/welcome/settings` (proprietario e amministratore; gli altri ruoli ricevono 403): le schermate (`screens`, da 1 a 5, con `title`, `body`, `video` con `mediaId` e `requireFinish` oppure `url`, `rules.text` e `fieldIds`), `mode` (`REQUIRED`, predefinito, o `SKIPPABLE`), `enabled` e `applyToExisting`, con `stats` (`completed`, `skipped`, `pending`). I Primi passi vanno nella stessa rotta: `missionsEnabled`, `missionsShowExisting`, `finalBadgeId` e `missions` (da 1 a 6, con `kind` `profile_completed`, `first_post` con `spaceId`, `form_submitted` con `formId`, `event_registered` con `eventId` facoltativo o `course_completed` con `courseId`, `title`, `points` da 0 a 10.000 e `badgeId` facoltativo), con `missionStats`. Un errore di validazione torna con 422 sul campo (`screens[0].title`, `missions[1].spaceId`).

Per la persona stessa (qualsiasi ruolo): `GET /api/welcome` (lo stato, `off`, `exempt`, `pending`, `completed` o `skipped`, la schermata attuale e le schermate), `POST /api/welcome/progress` (completa la schermata attuale: `step`, `rulesAccepted`, `videoFinished` e `fields`; una schermata fuori ordine restituisce 409) e `POST /api/welcome/skip` (solo in modalità saltabile; altrimenti 409). La scheda: `GET /api/welcome/missions` (`status` `off`, `exempt`, `active`, `completed` o `dismissed`, `visible`, `celebrate`, `done` di `total` e le missioni), `POST /api/welcome/missions/dismiss` e `POST /api/welcome/missions/celebrated` (le congratulazioni sono state mostrate).

`GET /auth/me` restituisce `welcomePending`. `GET /api/members` filtra con `welcome=pending|completed|skipped`, e `GET /api/members/{id}` restituisce `welcome`, con `missions`. Gli eventi `member.welcome_completed` (`member`, `completedAt`) e `member.onboarding_completed` (`member`, `completedAt` e `missions`, il numero di missioni) arrivano ai workflow e ai webhook. Vedi il [Riferimento dell'API](/api/referencia).

## Con l'assistente (MCP)

Chiedi di vedere o cambiare il benvenuto e le missioni (*"attiva il benvenuto obbligatorio con una schermata di regole"*): [`get_welcome_settings`](/mcp/ferramentas-membros#get-welcome-settings) e [`update_welcome_settings`](/mcp/ferramentas-membros#update-welcome-settings), che chiede sempre conferma. Chi è in attesa: [`list_members`](/mcp/ferramentas-membros#list-members) con `welcome: pending`; l'avanzamento di qualcuno: [`get_member`](/mcp/ferramentas-membros#get-member).

## Correlati

- [Registrazione e accesso](/membros/cadastro-e-entrada)
- [Campi personalizzati](/membros/campos-customizados)
- [Gamification](/membros/gamificacao)
- [Coinvolgimento e badge](/membros/engajamento#badge)
- [Workflow](/notificacoes/workflows)