Eventi

La piattaforma emette CustomEvent del browser su window. Tutti gli eventi hanno il prefisso mindtraining: e il payload è sempre disponibile in event.detail.

---

mindtraining:ready

Viene emesso quando: lo script ha finito di caricarsi e la API globale MindtrainingPlatform è disponibile su window.

Quando usarlo: è l'hook consigliato per chiamare init. Ascoltando questo evento eviti race condition tra il caricamento dello script e l'esecuzione del tuo codice di inizializzazione.

event.detail

Campo	Tipo	Descrizione
api	object	Riferimento a window.MindtrainingPlatform

window.addEventListener('mindtraining:ready', function (event) {
  // event.detail.api === window.MindtrainingPlatform
  MindtrainingPlatform.init('mindtraining', {
    viewer: { loggedIn: false },
  })
})

Script già caricato? Se registri il listener dopo che lo script è già stato eseguito, l'evento non verrà emesso di nuovo. Usa questo pattern di guardia:

function initializeMindtraining() {
  MindtrainingPlatform.init('mindtraining', {
    viewer: { loggedIn: false },
  })
}

if (window.MindtrainingPlatform) {
  initializeMindtraining()
} else {
  window.addEventListener('mindtraining:ready', initializeMindtraining, { once: true })
}

---

mindtraining:config

Viene emesso quando: la configurazione della piattaforma viene aggiornata, sia dopo la chiamata iniziale a init() sia dopo qualsiasi updateConfig() successivo.

Quando usarlo: usalo per reagire a cambi di configurazione provenienti dall'esterno della piattaforma, ad esempio per sincronizzare lo stato della tua UI.

event.detail

L'oggetto PlatformInitConfig normalizzato completo al momento del cambiamento.

Campo	Tipo	Descrizione
viewer	object	Impostazioni correnti del viewer/utente
viewer.userId	string | null	ID dell'utente attivo
viewer.loggedIn	boolean	Se l'utente è autenticato
viewer.subscribed	boolean	Se l'utente ha un abbonamento attivo
ui	object	Impostazioni correnti di UI
ui.mode	'web' | 'app'	Modalità di rendering
ui.actions	object	Callback delle azioni registrate
access	object	Regole di accesso correnti per tipo di gioco

window.addEventListener('mindtraining:config', function (event) {
  const config = event.detail

  console.log('Utente autenticato:', config.viewer?.loggedIn)
  console.log('Utente abbonato:', config.viewer?.subscribed)
  console.log("Regole di accesso attive:", config.access?.games)
})

---

Eventi di gioco e navigazione

I seguenti eventi vengono emessi durante il gameplay e la navigazione. Usali per analytics, tracking, integrazioni host e osservabilità.

---

mindtraining:game:loaded

Viene emesso quando: una sessione o schermata di gioco è pronta all'interazione.

Quando usarlo: usalo per tracciare pageview interne del gioco, misurare quali giochi vengono davvero caricati o attivare logica host in base al tipo di gioco.

event.detail

Campo	Tipo	Descrizione
gameType	string	Tipo di gioco (es. crossword, sudoku)
gameId	string	Identificatore univoco del gioco
variant	string	Variante del gioco (es. default, mini)
route	string	Percorso interno
source	string	Origine del gioco (es. today, archive)

window.addEventListener('mindtraining:game:loaded', function (event) {
  Analytics.track('mindtraining_game_loaded', event.detail)
})

---

mindtraining:game:playing

Viene emesso quando: l'utente inizia a interagire davvero con il gioco (per esempio, prima mossa o primo input).

Quando usarlo: usalo per distinguere tra un gioco caricato e un gioco effettivamente giocato, misurare l'attivazione o tracciare l'engagement.

event.detail

Campo	Tipo	Descrizione
gameType	string	Tipo di gioco
gameId	string	Identificatore univoco del gioco
variant	string	Variante del gioco
startedAt	string	Timestamp ISO 8601 di inizio

window.addEventListener('mindtraining:game:playing', function (event) {
  Analytics.track('mindtraining_game_playing', event.detail)
})

---

mindtraining:game:completed

Viene emesso quando: l'utente completa con successo un gioco.

Quando usarlo: usalo per funnel completi, analisi della difficoltà o ranking/gamification lato host.

event.detail

Campo	Tipo	Descrizione
gameType	string	Tipo di gioco
gameId	string	Identificatore univoco del gioco
variant	string	Variante del gioco
completedAt	string	Timestamp ISO 8601 di completamento
durationMs	number	Durata della sessione in millisecondi
score	number	Punteggio finale (se applicabile)

window.addEventListener('mindtraining:game:completed', function (event) {
  Analytics.track('mindtraining_game_completed', event.detail)
})

---

mindtraining:game:abandoned

Viene emesso quando: l'utente abbandona una sessione di gioco dopo aver iniziato a giocare e prima di completarla.

Quando usarlo: usalo per rilevare attriti, misurare l'abbandono per gioco o variante o migliorare i flussi di retention.

event.detail

Campo	Tipo	Descrizione
gameType	string	Tipo di gioco
gameId	string	Identificatore univoco del gioco
variant	string	Variante del gioco
durationMs	number	Tempo speso prima dell'abbandono
progress	number	Progresso (0–1) al momento dell'abbandono

window.addEventListener('mindtraining:game:abandoned', function (event) {
  Analytics.track('mindtraining_game_abandoned', event.detail)
})

---

mindtraining:game:state:saved

Viene emesso quando: lo stato del gioco viene persistito (ad esempio per la funzionalità “continua a giocare”).

Quando usarlo: usalo per tracciare retention, flussi di ripresa o verificare che il salvataggio dello stato funzioni correttamente.

event.detail

window.addEventListener('mindtraining:game:state:saved', function (event) {
  Analytics.track('mindtraining_game_state_saved', event.detail)
})

---

mindtraining:access:blocked

Viene emesso quando: la piattaforma rileva che una superficie (gioco di oggi, archivio, ecc.) è bloccata per l'utente.

Quando usarlo: usalo per attivare paywall contestuali, misurare domanda insoddisfatta o personalizzare i messaggi host.

event.detail

window.addEventListener('mindtraining:access:blocked', function (event) {
  Analytics.track('mindtraining_access_blocked', event.detail)
  if (event.detail.blockedReason === 'subscription_required') {
    Paywall.show({ context: 'game_archive' })
  }
})

---

mindtraining:route:changed

Viene emesso quando: cambia la route interna della piattaforma (per esempio, navigazione all'interno della SPA).

Quando usarlo: usalo per pageview virtuali o per sincronizzare l'analytics con la navigazione interna della piattaforma.

event.detail

window.addEventListener('mindtraining:route:changed', function (event) {
  Analytics.track('mindtraining_route_changed', event.detail)
})

---

mindtraining:pageview

Viene emesso quando: la piattaforma registra una vista navigabile rilevante per l'analytics.

Quando usarlo: usalo per il tracciamento delle pageview, il reporting per sezione e tipo di gioco o l'attribuzione della navigazione interna.

event.detail

Campo	Tipo	Descrizione
pathname	string	Percorso corrente
title	string	Titolo della pagina
gameType	string	Tipo di gioco, se applicabile
gameId	string	Identificativo del gioco, se applicabile
variant	string	Variante del gioco, se applicabile
source	string	Origine della vista (ad esempio today, archive)

window.addEventListener('mindtraining:pageview', function (event) {
  Analytics.track('mindtraining_pageview', event.detail)
})

---

mindtraining:user:action

Si attiva quando: l'utente esegue un'interazione chiave (ad esempio clicca sull'archivio o seleziona un gioco).

Quando usarlo: usalo per tracciare clic rilevanti, eseguire esperimenti o strumentare la UI senza collegare ogni pulsante dall'host.

event.detail

Campo	Tipo	Descrizione
action	string	Identificativo dell'azione (ad esempio click_archive)
location	string	Posizione nella UI (ad esempio home_header)
gameType	string	Tipo di gioco, se applicabile
variant	string	Variante del gioco, se applicabile
index	number	Posizione zero-based del blocco/item di gioco cliccato nella lista renderizzata, se applicabile
url	string	URL esterno selezionato dalla navigazione, se applicabile

Valori attuali di action:

Valore	Significato
click_play	L'utente clicca una CTA per giocare o aprire un gioco
click_archive	L'utente clicca una CTA di archivio o cronologia
click_start	L'utente avvia un gioco dalla schermata intermedia
click_back	L'utente clicca una CTA di ritorno o navigazione
click_nav	L'utente clicca un link di navigazione esterno

Valori attuali di location:

Valore	Superficie
home_block_game	Card o blocco gioco nella home
home_block_dynamic_games	Blocco dinamico dei giochi nella home
historical_game_block	Blocco giochi storici o recenti
intermediate_game_screen	Schermata intermedia mostrata prima di entrare in un gioco
game_navigation	Header di navigazione dentro il gioco
site_nav	Menu di navigazione del sito
game_navigation_menu	Menu di navigazione dentro il gioco

window.addEventListener('mindtraining:user:action', function (event) {
  Analytics.track('mindtraining_user_action', event.detail)
})

---

mindtraining:share:requested

Si attiva quando: l'utente tenta di condividere contenuti dalla piattaforma.

Quando usarlo: usalo per analytics dell'intenzione di condivisione o per collegarlo al flusso di condivisione nativo dell'host.

event.detail

Campo	Tipo	Descrizione
gameType	string	Tipo di gioco
gameId	string	Identificativo del gioco
url	string	URL da condividere
title	string	Titolo da condividere

window.addEventListener('mindtraining:share:requested', function (event) {
  Analytics.track('mindtraining_share_requested', event.detail)
})

---

mindtraining:error

Si attiva quando: si verifica un errore di flusso, caricamento o interazione rilevante per l'host.

Quando usarlo: usalo per osservabilità, alerting o UI di fallback lato host.

event.detail

Campo	Tipo	Descrizione
scope	string	Ambito dell'errore (ad esempio game-load)
code	string	Codice errore (ad esempio GAME_DATA_FETCH_FAILED)
message	string	Messaggio leggibile
recoverable	boolean	Se l'utente può recuperare dall'errore

window.addEventListener('mindtraining:error', function (event) {
  Analytics.track('mindtraining_error', event.detail)
  if (!event.detail.recoverable) {
    ErrorUI.show(event.detail)
  }
})

---

Eventi consigliati per analytics

Un approccio pratico per l'analytics dell'host è ascoltare:

1. mindtraining:ready - per sapere quando l'inizializzazione è sicura
2. mindtraining:config - per tracciare le modifiche di configurazione
3. mindtraining:game:loaded - per misurare i caricamenti dei giochi
4. mindtraining:pageview - per tracciare le pageview
5. mindtraining:game:playing - per misurare l'attivazione
6. mindtraining:game:completed - per misurare i completamenti
7. mindtraining:access:blocked - per misurare la domanda bloccata
8. mindtraining:error - per monitorare gli errori

window.addEventListener('mindtraining:game:loaded', function (event) {
  Analytics.track('mindtraining_game_loaded', event.detail)
})
window.addEventListener('mindtraining:game:playing', function (event) {
  Analytics.track('mindtraining_game_playing', event.detail)
})
window.addEventListener('mindtraining:pageview', function (event) {
  Analytics.track('mindtraining_pageview', event.detail)
})
window.addEventListener('mindtraining:access:blocked', function (event) {
  Analytics.track('mindtraining_access_blocked', event.detail)
})