Passa al contenuto principale

Flusso del gate di onboarding

Gli 8 passaggi del gate di onboarding che ogni installazione nuova deve superare prima che il launcher venga renderizzato. L'ordine è strutturale: ogni passo imposta uno stato da cui dipendono i successivi, oppure applica un confine di compliance.

Flusso​

PassoCategoriaImpostaBlocca rigidamente su
1 Età + PaeseGateageConfirmed, countryCheckbox non spuntato, nessun paese
2 Benvenuto / LinguaGatelanguage (en / it)n/d — avanzamento al click
3 VideoGate—n/d — sia SKIP che CONTINUE fanno avanzare
4 LegaleComplianceconsents.tos, .privacy, .eulaAnche una sola delle 3 checkbox non spuntata
5 Consenso EDCComplianceconsents.edcGameplayToggle gameplay o checkbox non spuntati
6 Connetti SteamIdentityoauth.steam.{status,username}, OTEL host.usernameOAuth Steam non si completa mai
7 System CheckDiagnosticsSystemCheckReport (solo telemetria)Qualsiasi voce con severity: blocking
8 Pronto / GODoneplayroll.onboardingV3Complete = truen/d — avanzamento con singolo pulsante

Perché questo ordine​

  • Compliance prima dell'identità. Legal + EDC devono essere accettati prima che venga collegato qualunque account, in modo che i record di consenso abbiano un timestamp acceptedAt antecedente alla registrazione dell'ID Steam.
  • Identità prima della diagnostica. L'OAuth Steam al passo 6 chiama otelLogger.setUserContext({ ownerId, username }). Ogni evento diagnostico emesso dal passo 7 viene quindi taggato automaticamente con host.username + enduser.id, così i guasti opachi arrivano su SigNoz già attribuiti a un tester noto invece che a un dispositivo anonimo.
  • Diagnostica prima del launcher. I blocchi a livello hardware (assenza di encoder GPU, driver NVIDIA troppo vecchio, disco pieno, OS troppo vecchio) emergono prima del primo tentativo di registrazione, con pulsanti d'azione che li risolvono con un click.

Passo 7 — System Check​

Cinque probe, tre livelli di severità. CONTINUE è subordinato a hasBlockers === false.

ControlloSorgenteSoglieScala di severità
OSos.release()Win10 build 18362 / 20348block < 18362 · warn < 20348 · ok
CPUos.cpus().length8 / 12 threadwarn < 8 · ok
RAMos.totalmem()8 / 16 GBblock < 8 · warn < 16 · ok
Discostatfs(recordingsPath)10 / 50 GB liberiblock < 10 · warn < 50 · ok
GPU/api/environment/{check,adapter} (playroll-core)Driver NVIDIA ≥ 570 (NVENC-only)block su sistemi AMD-only / Intel-only, o encoder NVIDIA inutilizzabile · warn driver vecchio · ok

Le soglie rispecchiano la pagina Notion 🖥️ System Requirements. Aggiornare entrambe in sincronia quando una build sposta una soglia.

Telemetria — attribuita per design​

L'OAuth Steam al passo 6 inizializza setUserContext in otel-logger.ts, così gli eventi del passo 7 arrivano su SigNoz con host.username già allegato.

EventoQuandoLivelloAttributi chiave
onboarding.system_check.resultogni esecuzione (auto + retry)mappato da overalloutcome, has_blockers, gpu_probe_source, entries.{count,blockers,warnings}, run_trigger
onboarding.system_check.entryper ogni voce non-okmappato da severityentry.id, entry.severity, entry.measured, entry.required, entry.action_hint
onboarding.system_check.unavailableIPC mancante / crashwarn / errorreason (ipc_missing / ipc_error), error.message

Query di triage ClickHouse:

-- testers blocked at GPU step with NVIDIA driver too old
SELECT host.username, system_check.entry.measured
FROM otel_logs
WHERE event.name = 'onboarding.system_check.entry'
  AND system_check.entry.id = 'gpu'
  AND system_check.entry.action_hint = 'update_nvidia_driver';

-- block-rate per check id
SELECT system_check.entry.id, count() AS blocks
FROM otel_logs
WHERE event.name = 'onboarding.system_check.entry'
  AND system_check.entry.severity = 'blocking'
GROUP BY system_check.entry.id;

Superficie di stato​

OnboardingState è mantenuto in un useReducer e riversato in GateState tramite setGateState al completamento. Lo stato locale dei componenti (checkbox, toggle) si resetta su BACK; lo stato del reducer (lingua, paese, età, consensi, OAuth) persiste attraverso la navigazione all'indietro.

I consent records raccolti qui (age + tos + privacy + eula + edcGameplay) vengono batch-submittati alla edge function consents-accept dopo lo step 6 (login Steam), così le righe atterrano su playroll_user_consents con lo user_id autenticato. La logica di re-prompt al boot (quando ruotiamo un documento sotto una modifica material) vive in Versioning dei consensi.

ChiaveTipoImpostato aPersistenza
playroll.onboardingV3CompletebooleanPasso 8GateStore — blocca il rientro nell'onboarding
playroll.language"en" | "it"Passo 2GateStore — locale dell'intera app
playroll.profile.countryCountryCodePasso 1GateStore
playroll.consents.{tos,privacy,eula,edcGameplay}{acceptedAt}Passi 4–5GateStore — audit trail
oauth.steam.{status,username}solo reducerPasso 6persistito tramite AuthManager, non in GateStore
SystemCheckReportsolo reducerPasso 7solo telemetria, non persistito

Postura pre-lancio​

La v3 è stata progettata per installazioni nuove. Non esiste un percorso di migrazione da nessuna versione precedente dell'onboarding — ogni dispositivo vede la v3 da zero al primo avvio. I frame v2 esistenti rimangono sulla canvas Paper marcati DEPRECATED — DO NOT USE solo a scopo archivio.

Riferimenti​