Eventos

A plataforma emite CustomEvents do navegador em window. Todos os eventos usam o prefixo mindtraining: e o payload está sempre disponível em event.detail.

---

mindtraining:ready

Disparado quando: o script terminou de carregar e a API global MindtrainingPlatform está disponível em window.

Quando usar: este é o hook recomendado para chamar init. Ao escutar este evento, evita condições de corrida entre o carregamento do script e a execução do código de inicialização.

event.detail

Campo	Tipo	Descrição
api	object	Referência para window.MindtrainingPlatform

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

O script já carregou? Se o listener for registado depois de o script já ter sido executado, o evento não voltará a ser emitido. Use este padrão de guarda:

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

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

---

mindtraining:config

Disparado quando: a configuração da plataforma é atualizada, tanto após a chamada inicial a init() como depois de qualquer updateConfig() subsequente.

Quando usar: use este evento para reagir a alterações de configuração feitas fora da plataforma, por exemplo para sincronizar o estado da sua própria UI.

event.detail

O objeto PlatformInitConfig normalizado completo no momento da alteração.

Campo	Tipo	Descrição
viewer	object	Configurações atuais do visualizador/utilizador
viewer.userId	string | null	ID do utilizador ativo
viewer.loggedIn	boolean	Se o utilizador está autenticado
viewer.subscribed	boolean	Se o utilizador tem uma subscrição ativa
ui	object	Configurações atuais de UI
ui.mode	'web' | 'app'	Modo de renderização
ui.actions	object	Callbacks de ações registadas
access	object	Regras atuais de acesso por tipo de jogo

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

  console.log('Utilizador autenticado:', config.viewer?.loggedIn)
  console.log('Utilizador subscritor:', config.viewer?.subscribed)
  console.log('Regras de acesso ativas:', config.access?.games)
})

---

Eventos de jogo e navegação

Os eventos seguintes são emitidos durante o gameplay e a navegação. Use-os para analytics, tracking, integrações do host e observabilidade.

---

mindtraining:game:loaded

Disparado quando: uma sessão ou ecrã de jogo está pronto para interação.

Quando usar: use este evento para acompanhar pageviews internas do jogo, medir que jogos são realmente carregados ou acionar lógica do host com base no tipo de jogo.

event.detail

Campo	Tipo	Descrição
gameType	string	Tipo de jogo (ex. crossword, sudoku)
gameId	string	Identificador único do jogo
variant	string	Variante do jogo (ex. default, mini)
route	string	Rota interna
source	string	Origem do jogo (ex. today, archive)

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

---

mindtraining:game:playing

Disparado quando: o utilizador começa a interagir realmente com o jogo (por exemplo, primeiro movimento ou primeira entrada).

Quando usar: use este evento para distinguir entre um jogo carregado e um jogo efetivamente jogado, medir ativação ou acompanhar engagement.

event.detail

Campo	Tipo	Descrição
gameType	string	Tipo de jogo
gameId	string	Identificador único do jogo
variant	string	Variante do jogo
startedAt	string	Timestamp ISO 8601 do início

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

---

mindtraining:game:completed

Disparado quando: o utilizador conclui um jogo com sucesso.

Quando usar: use este evento para funis completos, análise de dificuldade ou ranking/gamificação do lado host.

event.detail

Campo	Tipo	Descrição
gameType	string	Tipo de jogo
gameId	string	Identificador único do jogo
variant	string	Variante do jogo
completedAt	string	Timestamp ISO 8601 de conclusão
durationMs	number	Duração da sessão em milissegundos
score	number	Pontuação final (quando aplicável)

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

---

mindtraining:game:abandoned

Disparado quando: o utilizador abandona uma sessão de jogo depois de começar a jogar e antes de a concluir.

Quando usar: use este evento para detetar fricção, medir abandono por jogo ou variante, ou melhorar fluxos de retenção.

event.detail

Campo	Tipo	Descrição
gameType	string	Tipo de jogo
gameId	string	Identificador único do jogo
variant	string	Variante do jogo
durationMs	number	Tempo gasto antes do abandono
progress	number	Progresso (0–1) no momento do abandono

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

---

mindtraining:game:state:saved

Disparado quando: o estado do jogo é persistido (por exemplo, para a funcionalidade de “continuar a jogar”).

Quando usar: use este evento para acompanhar retenção, fluxos de continuação ou verificar se o estado guardado está a funcionar corretamente.

event.detail

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

---

mindtraining:access:blocked

Disparado quando: a plataforma deteta que uma superfície (jogo de hoje, arquivo, etc.) está bloqueada para o utilizador.

Quando usar: use este evento para acionar paywalls contextuais, medir procura não satisfeita ou personalizar mensagens do host com base no motivo do bloqueio.

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

Disparado quando: a rota interna da plataforma muda (por exemplo, navegação dentro da SPA).

Quando usar: use este evento para pageviews virtuais ou para sincronizar analytics com a navegação interna da plataforma.

event.detail

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

---

mindtraining:pageview

Disparado quando: a plataforma regista uma visualização navegável relevante para analytics.

Quando usar: use este evento para pageview tracking, relatórios por secção e tipo de jogo ou atribuição da navegação interna da SPA.

event.detail

Campo	Tipo	Descrição
pathname	string	Rota atual
title	string	Título da página
gameType	string	Tipo de jogo, se aplicável
gameId	string	Identificador do jogo, se aplicável
variant	string	Variante do jogo, se aplicável
source	string	Origem da vista (por exemplo, today, archive)

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

---

mindtraining:user:action

Disparado quando: o utilizador realiza uma interação importante (por exemplo, clica no arquivo ou seleciona um jogo).

Quando usar: use este evento para acompanhar cliques relevantes, executar experiências ou instrumentar a UI sem ligar cada botão a partir do host.

event.detail

Campo	Tipo	Descrição
action	string	Identificador da ação (por exemplo, click_archive)
location	string	Localização na UI (por exemplo, home_header)
gameType	string	Tipo de jogo, se aplicável
variant	string	Variante do jogo, se aplicável
index	number	Posição zero-based do bloco/item de jogo clicado na lista renderizada, se aplicável
url	string	URL externo selecionado na navegação, se aplicável

Valores atuais de action:

Valor	Significado
click_play	O utilizador clica numa CTA para jogar ou abrir um jogo
click_archive	O utilizador clica numa CTA de arquivo ou histórico
click_start	O utilizador inicia um jogo a partir do ecrã intermédio
click_back	O utilizador clica numa CTA de voltar ou navegação
click_nav	O utilizador clica num link de navegação externo

Valores atuais de location:

Valor	Superfície
home_block_game	Card ou bloco de jogo na home
home_block_dynamic_games	Bloco dinâmico de jogos na home
historical_game_block	Bloco de jogos históricos ou recentes
intermediate_game_screen	Ecrã intermédio apresentado antes de entrar num jogo
game_navigation	Cabeçalho de navegação dentro do jogo
site_nav	Menu de navegação do site
game_navigation_menu	Menu de navegação dentro do jogo

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

---

mindtraining:share:requested

Disparado quando: o utilizador tenta partilhar conteúdo da plataforma.

Quando usar: use este evento para analytics de intenção de partilha ou para ligar ao fluxo nativo de partilha do host.

event.detail

Campo	Tipo	Descrição
gameType	string	Tipo de jogo
gameId	string	Identificador do jogo
url	string	URL para partilhar
title	string	Título para partilhar

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

---

mindtraining:error

Disparado quando: ocorre um erro de fluxo, carregamento ou interação relevante para o host.

Quando usar: use este evento para observabilidade, alertas ou UI de fallback no host.

event.detail

Campo	Tipo	Descrição
scope	string	Âmbito do erro (por exemplo, game-load)
code	string	Código do erro (por exemplo, GAME_DATA_FETCH_FAILED)
message	string	Mensagem legível
recoverable	boolean	Se o utilizador pode recuperar do erro

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

---

Eventos recomendados para analytics

Uma abordagem prática para analytics do host é ouvir:

1. mindtraining:ready - para saber quando é seguro inicializar
2. mindtraining:config - para acompanhar mudanças de configuração
3. mindtraining:game:loaded - para medir carregamentos de jogos
4. mindtraining:pageview - para acompanhar pageviews
5. mindtraining:game:playing - para medir ativação
6. mindtraining:game:completed - para medir conclusões
7. mindtraining:access:blocked - para medir procura bloqueada
8. mindtraining:error - para monitorizar erros

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)
})