Pular para o conteúdo principal

:::note Estado da versão O SDK npm publicado é 0.1.4; a versão atual do código-fonte do loader alojado é widget.js v16. São versões distintas: o pacote não fixa a versão do loader. O loader v16 suporta teardown através de remove() ou window.ChattyBox.destroy(); confirme a versão implementada antes de depender deste comportamento. O sendMessage() headless não tenta novamente automaticamente. :::

Integre com um assistente de programação com IA

Para o widget alojado, instrua o assistente a carregar a interface flutuante a partir de uma shell persistente do browser, não dentro do componente. A integração recomendada é o pacote npm @openstaticfish/chattybox: permite configurar a chave pública e o URL da API, carregar o widget gerido ou usar o cliente headless para uma interface totalmente personalizada.

O script independente widget.js é documentado por último como fallback sem build para sites que não podem instalar pacotes npm.

Antes de começar​

Conclua a configuração do chatbot antes de pedir a um assistente que edite a aplicação:

  • Verifique respostas e citações representativas em Testar chatbot.
  • Em Instalar → Chaves e domínios, consulte ou crie uma chave pública para o browser e verifique as respetivas definições de origem. Uma chave preparada para um site pode já estar limitada à origem desse site; as chaves sem restrições funcionam a partir de todas as origens. As restrições de origem são um reforço opcional da segurança, não uma forma de autenticação dos visitantes.
  • Em Instalar → Instalação no site, selecione uma chave adequada e copie o snippet. Utilize o respetivo data-api-url, se existir; caso contrário, obtenha o endpoint HTTP correto da API do widget na configuração de implementação.
  • Decida se um widget flutuante persistente se adequa à aplicação ou se precisa de uma interface personalizada, com posicionamento por rota e desmontagem.

Estas são credenciais públicas do browser. Ainda assim, evite incluir em commits valores específicos do ambiente. Nunca forneça um token de implementação da configuração, credenciais de administrador ou ficheiros de ambiente não relacionados.

Recomendado: monte a interface gerida a partir do npm​

Este é o prompt predefinido para React, Next.js, Vite e outras aplicações web baseadas em pacotes.

Instrução
Integre o pacote npm do ChattyBox

Integre o ChattyBox nesta aplicação usando o pacote npm @openstaticfish/chattybox.

Configuração pública do navegador:
- Chave da API: [PASTE PUBLIC WIDGET KEY]
- URL da API: [PASTE WIDGET API URL]

No dashboard, verifique as respostas em **Testar chatbot**, confirme a chave em **Instalar → Chaves e domínios** e selecione-a em **Instalar → Instalação no site** para copiar o snippet.

Utilize apenas a chave pública do widget e o respetivo URL da API. Uma chave preparada para um site pode já estar limitada à origem desse site. As restrições de origem são um reforço opcional da segurança, não uma forma de autenticação dos visitantes. Não inclua credenciais de administrador, tokens de implementação ou outros segredos em código executado no browser nem nos prompts.

Primeiro, inspecione o framework, o modelo de encaminhamento, o gestor de pacotes, as convenções de variáveis de ambiente e o layout persistente da aplicação. Indique que ficheiros tenciona alterar antes de editar. Se não for claro em que rotas o ChattyBox deve aparecer, peça-me esclarecimentos.

Requisitos:
1. Instale @openstaticfish/chattybox com o gestor de pacotes já utilizado neste repositório.
2. Guarde a chave pública da API e o URL da API segundo a convenção do framework para variáveis de ambiente expostas ao browser. Adicione nomes de placeholder a um ficheiro de exemplo de variáveis de ambiente, mas não inclua valores reais em commits.
3. Importe Chattybox de @openstaticfish/chattybox e crie um cliente com apiKey e baseUrl.
4. Chame client.mountWidget() apenas em código executado no browser, depois de document.body existir, a partir de uma shell persistente da aplicação. O widget flutuante é carregado sob document.body, não dentro do componente.
5. Mantenha o loader durante a navegação SPA permitida. O SDK publicado 0.1.4 só partilha referências entre mounts com opções idênticas: chame remove() em cada handle devolvido; remove() é idempotente e só o último handle inicia o teardown. O loader alojado v16 do código-fonte atual processa este sinal, remove a interface e os estilos que controla e cancela a inicialização, as tentativas de repetição e o chat em curso; window.ChattyBox.destroy() permite o mesmo teardown através do loader. Não carregue o widget antes do consentimento necessário nem em rotas privadas/sensíveis; faça o teardown quando uma rota for excluída ou o consentimento for retirado. Confirme que a versão implementada do loader suporta teardown: ocultar a interface ou remover apenas a etiqueta script não é suficiente. O teardown não pode anular um pedido já processado pelo servidor.
6. Não injete widget.js manualmente, não crie um proxy de backend nem introduza um segundo loader. mountWidget recusa alterações à chave, ao URL da API, ao URL do script, à locale ou às opções de depuração enquanto existirem handles; não mantém silenciosamente as opções antigas.
7. Preserve a navegação, os limites de renderização, a localização, o Analytics, o consentimento e os estilos existentes. A opção de locale do SDK está sujeita à política de substituição do script do projeto. O SDK publicado 0.1.4 não disponibiliza uma API reativa de atualização da locale nem uma ready promise. O widget alojado v16 no código-fonte atual pode atualizar as etiquetas próprias do produto quando muda a locale resolvida (por exemplo, após uma alteração de <html lang> ou data-locale), de acordo com a política de locale do projeto; confirme a versão implementada antes de depender desse comportamento. O widget alojado v16 faz até 10 tentativas de chat numa janela de 30 segundos em que as novas tentativas são agendadas; não se trata de um timeout rígido para um pedido em curso. O sendMessage() headless não tenta novamente automaticamente; o SDK 0.1.4 repete getWidgetConfig() apenas uma vez após HTTP 400, e as tentativas GET de arranque do loader são independentes. O SDK 0.1.4 valida baseUrl e trata corpos de resposta que não podem ser lidos.
8. Faça a alteração focada mais pequena possível e não faça o deployment.
9. Execute o build, o lint, a verificação de tipos e os testes relevantes do repositório.
10. Indique os ficheiros alterados, as variáveis de ambiente que devo definir, onde a interface é carregada e como a testar no site implementado.

O código seguinte é um exemplo de callback do ciclo de vida no browser, não uma chamada top-level durante a renderização no servidor. Chame a função a partir de um efeito apenas do lado do cliente, na shell persistente e depois de document.body existir; guarde o handle:

import { Chattybox } from '@openstaticfish/chattybox';

const client = new Chattybox({
  apiKey: PUBLIC_CHATTYBOX_API_KEY,
  baseUrl: PUBLIC_CHATTYBOX_API_URL,
});

function mountInBrowser() {
  if (typeof document === 'undefined' || !document.body) return;
  return client.mountWidget();
}

// Guarde o handle para navegação permitida e teardown intencional.

Crie uma interface personalizada​

Escolha esta opção quando a aplicação precisar de controlar a lista de mensagens, a entrada, os estados de carregamento, os erros, as citações e o posicionamento, em vez de montar a interface gerida.

Instrução
Crie uma interface headless do ChattyBox

Crie uma interface de chatbot personalizada usando o pacote npm @openstaticfish/chattybox e o respetivo cliente headless.

Configuração pública do navegador:
- Chave da API: [PASTE PUBLIC WIDGET KEY]
- URL da API: [PASTE WIDGET API URL]

No dashboard, verifique as respostas em **Testar chatbot** e confirme a chave em **Instalar → Chaves e domínios**; selecione-a em **Instalar → Instalação no site** quando obtiver o snippet.

Utilize apenas a chave pública do widget e o respetivo URL da API. As restrições de origem são opcionais e não autenticam visitantes. Não inclua credenciais de administrador, tokens de implementação ou outros segredos em código executado no browser nem nos prompts.

Primeiro, inspecione o framework da aplicação, o sistema de componentes, os padrões de estado, os estilos, as convenções de acessibilidade e a configuração de testes. Proponha os limites dos componentes e os ficheiros antes de editar.

Requisitos:
1. Instale @openstaticfish/chattybox com o gestor de pacotes existente no repositório.
2. Configure um cliente Chattybox com apiKey e baseUrl através de variáveis de ambiente expostas ao browser; não inclua valores reais em commits.
3. Use sendMessage() e guarde conversationId num estado associado ao visitante; limpe-o quando o utilizador ou a sessão mudar e nunca partilhe o ID entre visitantes sem relação. A chave pública, as restrições de origem e o conversationId não autenticam visitantes nem protegem conversas privadas. As mensagens podem ser guardadas e continuar visíveis para os proprietários do projeto; limpar o estado local não elimina os registos guardados. Evite dados sensíveis. Com o mesmo conversationId, o modelo recebe até 12 mensagens recentes guardadas, cada uma limitada a 2.000 caracteres; não recebe a transcrição completa nem memória permanente.
4. Apresente as respostas como texto ou Markdown sanitizado e as fontes HTTP(S) como ligações acessíveis, mantendo a ordem. Nunca insira HTML não fidedigno nem esquemas de ligação inseguros.
5. Implemente estados de espera, vazio, erro e nova tentativa. As respostas alternativas podem incluir um array sources vazio; não existe um campo geral wasAnswered. Se o backend fornecer providerError, restrinja o valor opcional de forma segura e apresente um erro genérico do fornecedor, não uma resposta normal. Não repita cegamente uma resposta com chave de idempotência já concluída. O SDK publicado 0.1.4 pode não declarar campos de resposta do código-fonte atual, como providerError ou productFallback; restrinja-os de forma segura e aceite que possam estar ausentes. Trate ChattyboxError e erros de rede não encapsulados; code é opcional.
6. Rejeite mensagens vazias ou com mais de 2.000 caracteres depois de aplicado trim, impeça envios duplicados e mantenha acessíveis os comportamentos de teclado e leitor de ecrã. O sendMessage() headless não tenta novamente automaticamente: use um idempotencyKey único por mensagem lógica e reutilize exatamente o mesmo input nas novas tentativas, incluindo conversationId; não repita cegamente todos os HTTP 409. O SDK 0.1.4 repete getWidgetConfig() apenas uma vez após HTTP 400. O widget alojado v16 faz até 10 tentativas de chat numa janela de 30 segundos em que as novas tentativas são agendadas; não se trata de um timeout rígido para um pedido em curso. As tentativas GET de arranque do loader são independentes.
7. Monte a interface apenas nas rotas ou no layout que eu indicar.
8. Siga os componentes e estilos existentes em vez de adicionar um novo sistema de design.
9. Não carregue widget.js nem chame mountWidget().
10. Execute o build, o lint, a verificação de tipos e os testes relevantes; depois indique os ficheiros alterados e um plano de verificação.

Observações sobre frameworks​

Forneça ao assistente uma frase adicional quando necessário:

  • Next.js App Router: “Mantenha o cliente Chattybox e a chamada a mountWidget() dentro de um pequeno Client Component renderizado pelo layout pretendido.”
  • React SPA: “Monte a partir do shell persistente da aplicação ou do layout da rota específica e faça a limpeza na função de retorno do efeito.”
  • Docusaurus: “Crie um componente de tema somente para o cliente e renderize-o a partir de src/theme/Root; preserve a navegação da documentação e as mudanças de localidade.”
  • Vue, Nuxt, Svelte ou outro framework: “Use o ciclo de vida de montagem somente no cliente do framework e o ciclo de limpeza correspondente.”

Revise uma integração existente do SDK​

Instrução
Revise minha integração do SDK do ChattyBox

Revise esta integração do ChattyBox sem fazer deploy nem alterar código não relacionado.

Verifique se:
1. @openstaticfish/chattybox está instalado e importado em vez de duplicar seu comportamento.
2. Um único cliente Chattybox recebe a chave pública da API e o URL da API pretendidos, selecionados em **Instalar → Chaves e domínios** e **Instalar → Instalação no site**; verifique as respostas em **Testar chatbot**.
3. As variáveis de ambiente do navegador seguem as regras de nomes de variáveis públicas deste framework sem expor credenciais privadas.
4. mountWidget() ou a interface personalizada aparece apenas nas rotas pretendidas e é limpa corretamente. Não carregue o widget antes do consentimento necessário nem em rotas privadas/sensíveis; em mudanças de rota SPA ou retirada do consentimento, faça teardown efetivo em vez de apenas ocultar a interface ou remover a etiqueta script. Confirme a versão implementada do loader.
5. A navegação do lado do cliente e as remontagens durante o desenvolvimento não criam instâncias duplicadas.
6. Os limites de renderização, a localização, o Analytics, o consentimento, a acessibilidade e o layout existentes permanecem intactos. As restrições de origem são opcionais, não autenticam visitantes; as chaves restritas exigem uma origem de pedido permitida e o fetch do Node não envia automaticamente os cabeçalhos do browser.
7. A implementação tem testes apropriados e nenhuma refatoração não relacionada.

Apresente os resultados por gravidade, com caminhos dos ficheiros e referências de linha. Proponha apenas as correções seguras mais pequenas e forneça os comandos exatos de verificação.

Não usa npm nem uma etapa de build?​

Use o guia de instalação do widget.js somente quando o site não puder usar o pacote npm, por exemplo, em HTML simples, um campo de código personalizado de um CMS ou o Google Tag Manager.

Instrução
Instale o script de fallback do widget

Instale o widget alojado do ChattyBox neste site usando o script exato gerado em **Instalar → Instalação no site** no meu projeto ChattyBox:

[PASTE COMPLETE WIDGET SCRIPT]

Inspecione primeiro o site e identifique o ponto de inserção mais seguro para as páginas públicas. Utilize apenas o script fornecido e credenciais públicas; não exponha credenciais privadas. Carregue o script inalterado uma única vez e só depois de obter o consentimento necessário; exclua rotas privadas, administrativas, de checkout ou outras rotas sensíveis. Em mudanças de rota SPA ou retirada do consentimento, faça teardown de qualquer widget já inicializado antes de entrar num estado excluído e volte a inicializá-lo apenas quando permitido. Confirme que a versão implementada do loader suporta teardown: ocultar a interface ou remover apenas a etiqueta script não é suficiente. O teardown não anula pedidos já processados. Preserve o comportamento CSP, não faça o deploy da alteração e indique a localização alterada e um plano de teste no browser.

Teste o resultado​

  1. Reveja o diff e confirme que nenhuma credencial real foi incluída num commit.
  2. Execute o build, o lint, a verificação de tipos e os testes normais do projeto.
  3. Faça a implementação através do processo normal de revisão.
  4. Verifique as rotas pretendidas numa janela privada do navegador, incluindo a navegação do lado do cliente.
  5. Faça uma pergunta suportada, siga uma citação e teste o comportamento de fallback.
  6. Verifique o layout para dispositivos móveis, a utilização do teclado e a consola do navegador.

Continue com a referência do SDK e o checklist de lançamento.