Visão geral
Os Custom Scripts permitem injetar JavaScript e CSS personalizados em três superfícies da plataforma:
- Dashboard: o painel usado pela sua equipe de atendimento.
- Portal: o site público da Central de Ajuda.
- Widget: o chat embutido no seu site.
Com isso você adiciona comportamentos (ex.: rastrear eventos, mostrar um aviso) ou ajustes de estilo (ex.: esconder/realçar elementos) sem precisar alterar o código da plataforma. É um recurso poderoso e, por isso, fica na administração da plataforma.
Pré-requisitos
- Acesso de operador/super administração da plataforma.
- Conhecimento de JavaScript/CSS (o script roda no navegador de quem usa a superfície escolhida).
- Um ambiente para testar antes de publicar (idealmente fora de produção).
Passo a passo
- Acesse o painel de administração da plataforma e abra a área de Custom Scripts.
- Crie um novo script informando: superfície (dashboard, portal ou widget), tipo (JS ou CSS) e quando deve rodar (run on).
- Cole o seu código. Em scripts JS, use o objeto de contexto (
ctx) disponibilizado pela plataforma para interagir de forma segura com a superfície. - Limpeza (teardown): scripts que adicionam elementos/ouvintes devem removê-los quando solicitado, para não acumular efeitos colaterais em navegação SPA.
- Salve, ative e teste na superfície correspondente antes de liberar para todos.
Configurações & opções
- Superfície: escolha em qual ambiente o script roda (dashboard, portal ou widget).
- Tipo: JavaScript (comportamento) ou CSS (estilo).
- Quando rodar (run on): controla o momento/contexto de execução.
- Ativo/Inativo: ligue ou desligue um script sem apagá-lo.
Fundo do login e scripts públicos
As páginas de login, cadastro e solicitação de redefinição de senha executam Custom Scripts de dashboard ativos que correspondem à rota. O fundo gerenciado do login usa ctx.dom.css; ctx.log e os helpers de limpeza também funcionam. Nessas páginas públicas, ctx.store, ctx.api e ctx.storage não estão disponíveis, scripts limitados a contas são excluídos e o status de execução não é enviado às APIs de conta. Scripts continuam sendo JavaScript de confiança do operador, sem sandbox.
Use run_on: route_change com /app/login* para estilos exclusivos do login; os recursos gerenciados são removidos ao sair da rota. A edição de senha continua excluída, inclusive na navegação SPA. Se a primeira página for a edição de senha, recarregue uma página permitida para carregar seus scripts. Após aplicar a identidade visual, recarregue o login; páginas públicas não recebem o hot reload autenticado.
Casos de uso
- Adicionar um aviso/banner temporário no dashboard da equipe.
- Esconder ou reestilizar um elemento do portal para combinar com a sua marca.
- Disparar um evento de analytics quando o widget é aberto.
Dicas, limites e boas práticas
- Mantenha os scripts pequenos e idempotentes; sempre implemente o teardown.
- Evite dependências externas pesadas — elas afetam o desempenho da superfície.
- Versione o seu código fora da plataforma e documente o que cada script faz.
- Por ser injeção de código, trate como alto impacto: revise antes de publicar.
Solução de problemas
- O script não roda: confira a superfície escolhida, se está ativo e o momento de execução (run on).
- Algo quebrou na tela: desative o script e use o console do navegador para ver erros.
- O efeito duplica em navegação: faltou o teardown — remova elementos/ouvintes adicionados.
- Não encontro a área de Custom Scripts: ela fica na administração da plataforma — peça acesso ao responsável pela instalação.
Relatos de execução
Os relatos de erro do navegador enviam apenas o estado da execução e a mensagem de erro, sem stack trace, URL bruta da página ou metadados do momento de execução. Incidentes de rajada reproduzidos mantêm o caminho saneado da página; scripts de marca gerenciados continuam isentos da desativação automática. Revise as mensagens antes de compartilhá-las: um script pode incluir dados próprios na mensagem de erro.