Download the PHP package betocampoy/champs-onboarding without Composer

betocampoy/champs-onboarding

Onboarding guiado (tours de interface) para projetos Symfony 7.4, integrado ao champs-frontend.

O pacote traz as próprias entidades e tabelas (champs_onboarding_*). O projeto consumidor não precisa adaptar nenhuma entidade: o progresso é gravado pelo userIdentifier do usuário logado (UserInterface::getUserIdentifier()).

Estrutura

Instalação durante o desenvolvimento (repositório path)

No composer.json do projeto (ex.: MEMOD):

Quando estabilizar, troque o path por vcs apontando para o GitHub e use tags de versão.

Registro do bundle

config/bundles.php:

config/packages/champs_onboarding.yaml (opcional):

Exige betocampoy/champs-frontend ^1.7.

Banco de dados

O mapeamento Doctrine é registrado pelo próprio bundle. Basta gerar e rodar a migration:

Leia a migration gerada. Ela deve criar só champs_onboarding_tour, champs_onboarding_step e champs_onboarding_progress. Se o banco do projeto já tiver drift em relação ao mapeamento, o diff arrasta junto ALTER/DROP de tabelas do projeto: nesse caso, limpe à mão.

Rotas

config/routes/champs_onboarding.yaml:

No next, step é o passo em que o usuário estava ao clicar. No último passo, next conclui o tour. Erros de regra voltam como JSON {error} em português (401 sem login, 404 tour inexistente, 403 sem acesso, 422 ação/passo/corpo inválido, 409 tour não iniciado).

• Sem login os endpoints respondem 401 em JSON (não redirecionam). Se o access_control do projeto exigir login em /onboarding, o firewall redireciona antes.
• CSRF: o POST /progress exige o cabeçalho X-Champs-Ajax (o mesmo do AjaxForm do champs-frontend) e recusa Sec-Fetch-Site: cross-site (403). Outro site não consegue enviar cabeçalho customizado sem preflight CORS.

As rotas só existem pelo import acima. O config/routes.yaml padrão do Symfony 7.4 (resource: routing.controllers) importaria todo controller com #[Route], inclusive os do bundle e sem prefixo; o ExcludeFromRoutingControllersPass tira os controllers do bundle dessa descoberta.

Quem vê cada tour (elegibilidade)

Tour::requiredAttribute é um atributo de segurança (null = qualquer usuário logado). A regra fica num único serviço, TourEligibilityCheckerInterface, usado tanto nos endpoints quanto no monitoramento (worker/comando, sem sessão).

O padrão (AuthorizationEligibilityChecker) chama isGrantedForUser($user, $atributo, $tour):

• ROLE_X funciona sem configuração e respeita a role_hierarchy
• qualquer outro atributo é respondido pelos voters do projeto (o Tour vai como subject). Ex.: perm:fatura.listar, modulo:financeiro. Os voters não podem depender da sessão.

Para outra regra (ex.: excluir usuários desativados), implemente a interface no projeto (pode receber o AuthorizationEligibilityChecker e complementar) e aponte o alias:

Segmento (estatísticas por tenant, unidade, plano...)

Os tours são globais. Para filtrar e agrupar as estatísticas, implemente UserSegmentResolverInterface (resolve($user): ?string e label($segment): string) e aponte o alias do mesmo jeito. O segmento é gravado em champs_onboarding_progress.segment: quando o usuário usa o tour, quando muda um dos watch_fields e em cada champs:onboarding:sync (que também corrige segmentos desatualizados). Sem implementação, fica tudo sem segmento.

Tour obrigatório

Marque mandatory = true no tour. A partir daí:

• skip é recusado no backend (HTTP 422) e o front esconde o botão "Pular"
• o MandatoryOnboardingSubscriber redireciona qualquer navegação GET para a página do tour até ele ser concluído (AJAX, JSON, rotas do onboarding e rotas isentas passam livres)
• a rota inicial do tour obrigatório não pode ter parâmetros obrigatórios

Quando o usuário não tem pendência, isso fica guardado na sessão por cache_seconds. Um tour obrigatório criado depois leva até esse tempo para começar a ser cobrado de quem já está logado.

Tours monitorados

Marque monitored = true no tour. O bundle cria uma linha não iniciado (pending) para cada usuário elegível e vai atualizando conforme o usuário abre, conclui ou pula. Assim o dashboard mostra também quem nunca abriu o tour.

Sem user_class, o monitoramento fica desligado e o resto do bundle funciona normalmente.

Elegível = o TourEligibilityCheckerInterface diz que sim (ver acima).

watch_fields: campos, associações to-one ou coleções (ManyToMany/OneToMany) do User. Mudança em qualquer um ressincroniza o usuário. Inclua tudo de que a elegibilidade e o segmento dependem (ex.: [tenant, authRoles, status]).

Carga inicial: ao salvar um tour monitorado (ou mudar monitored, active ou requiredAttribute), o TourMonitoringListener despacha SyncMonitoredTour no Messenger.

Mudanças fora do User (ex.: o tenant contratou um módulo): despache SyncMonitoredUsers($segmento) para ressincronizar os usuários daquele segmento (ou null para todos).

Roteie as duas mensagens para um transport assíncrono:

Sem roteamento, a mensagem é processada na hora (síncrona).

Ciclo de vida do usuário (listener do Doctrine na user_class, sem código no projeto):

Histórico de quem já abriu o tour nunca é apagado por mudança de acesso. Uma falha no monitoramento só é registrada no log: nunca impede salvar o usuário.

Comando (para ressincronizar ou depois de importar usuários direto no banco):

Estatísticas

OnboardingStats entrega os dados do dashboard:

• overview(?segment): por tour — não iniciados, iniciados, em andamento, concluídos, pulados, taxa de conclusão (sobre quem abriu), cobertura (sobre todos os elegíveis, só em monitorados), tempo médio e reaberturas
• forTour($tour, ?segment): o resumo acima + funil por passo + atividade recente + lista de quem não abriu
• bySegment($tour): o resumo do tour por segmento (com o label), do maior para o menor

segment = null nos dois primeiros = todos os segmentos.

Front (champs-frontend ≥ 1.8)

O módulo Onboarding.js do champs-core-js já vem no initCore(). No layout das páginas logadas:

Âncoras dos passos (o valor é o campo anchor do TourStep):

Textos traduzidos, atributos e eventos: ver o README do champs-core-js (seção Onboarding).

Cadastro de tours (admin)

Telas em /onboarding/admin/tours (prefixo do import de rotas), só para admin_role: lista com busca e números de uso, cadastro do tour, passos (criar, editar, subir/descer, excluir) e Testar tour (modo teste do Onboarding.js: nada é gravado, funciona com tour inativo).

• Toda rota GET aparece como tela de tour, inclusive as de um registro (/remessas/{id}): o tour dispara pelo nome da rota, então aparece quando o usuário abre qualquer registro daquela tela e ensina em cima do dado real. O front não consegue levar o usuário até uma tela de registro (não sabe qual), então o passo seguinte numa tela dessas avisa "continua em outra tela".
• URL de exemplo (Tour::sampleUrl): URL de um registro real da tela do 1º passo, usada só pelo admin no Testar/Testar como/Apontar dessas telas. O cadastro confere se ela abre a tela certa (RouteCatalog::routeOfUrl()). Tour obrigatório não pode começar em tela de registro.
• As âncoras data-champs-tour já usadas nos templates são sugeridas no cadastro do passo; âncora digitada que não existe em nenhum template aparece com aviso.
• Telas e textos (champs_onboarding.*.yaml, pt_BR/en/es) podem ser sobrescritos pelo mecanismo padrão do Symfony (templates/bundles/ChampsOnboardingBundle/, translations/).
• Âncora do passo: nome do data-champs-tour ou seletor CSS (até 255 caracteres; regra em TourStep::isSelectorAnchor()). Os componentes do champs-frontend ≥ 1.9 já geram âncoras (field-<id>, page-title, list-content…), então a maioria dos tours não exige mexer em template.
• Apontar na tela (cadastro do passo): abre a tela do passo numa aba nova em modo apontar (clique normal usa a tela, Ctrl+clique escolhe; avisa se o elemento foi escolhido em outra tela); o clique no elemento devolve a âncora para o campo (a mais estável disponível; caminho no DOM aparece como frágil).
• Opções do passo:
  • Avança ao clicar no elemento — o próprio elemento destacado avança (ex.: botão que abre um modal).
  • Exige digitar no campo (+ texto esperado, opcional) — o "Próximo" só libera com o campo preenchido; Enter avança e deixa o formulário seguir (ex.: tour de pesquisa). Precisa de âncora; não combina com "avança ao clicar".
  • Fechar modal aberto ao chegar neste passo — para seguir com um elemento fora do modal.
• Testar como… / Apontar como…: com admin.switch_user_parameter (ex.: _switch_user) e monitoring.user_class, a tela abre personificando um usuário escolhido entre os que podem ver o tour (/onboarding/admin/tours/{id}/usuarios?q=). É o caminho para telas que o admin não acessa. O "Apontar como…" sai da personificação sozinho ao terminar; o "Testar como…" volta pelo "sair da personificação" do projeto.
• Testar tour abre ?champs_onboarding_preview=<slug> na tela do 1º passo. O tour é lido por /onboarding/admin/tours/preview/{slug}, liberado para o admin e para um admin que esteja personificando um usuário (switch_user): é o caminho para testar tours de telas que o admin não acessa. A tela do tour mostra o link de teste para copiar.

Próximas etapas

• Dashboard de estatísticas (OnboardingStats) nas telas do admin