## 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

1. Acesse o painel de **administração da plataforma** e abra a área de **Custom Scripts**.
2. Crie um novo script informando: **superfície** (dashboard, portal ou widget), **tipo** (JS ou
   CSS) e quando deve rodar (**run on**).
3. 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.
4. **Limpeza (teardown)**: scripts que adicionam elementos/ouvintes devem removê-los quando
   solicitado, para não acumular efeitos colaterais em navegação SPA.
5. 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.

## Veja também

- [Whitelabel (marca própria)](/hc/ajuda/articles/administration-whitelabel-pt-br)
- [Integrações](/hc/ajuda/articles/administration-integracoes-pt-br)
- [Visão geral de Administração](/hc/ajuda/articles/administration-overview-pt-br)
- [Tours guiados (Guided Tours)](/hc/ajuda/articles/administration-guided-tours-pt-br)