> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatmode.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Guia de Implementação

Este guia cobre técnicas para implementar o embed do Chatmode usando o snippet padrão **Código da Bolha** em diferentes plataformas e frameworks.

## Recapitulação da Implementação Básica

O método padrão envolve adicionar a tag de script, copiada das configurações do seu Ambiente, ao HTML do seu site.

1. Navegue até as configurações do seu Ambiente `EMBED` no Chatmode.
2. Encontre a seção **Implementação** / **Compartilhar**.
3. Copie o snippet **"Código da Bolha"**.
4. Cole o snippet no seu HTML, geralmente antes da tag de fechamento `</body>`.

```html theme={"system"}
<!-- Exemplo da Estrutura do Snippet - Copie o código exato da UI do Chatmode! -->
<script type="module">
  import Chatmode from "https://cdn.jsdelivr.net/npm/@chatmode/embed/+esm";

  // Armazene o valor de retorno se precisar de controle programático
  const chat = Chatmode.initBubble({
    // Obrigatório - Copiado da UI
    environmentId: "SEU_ID_DE_AMBIENTE",

    // Opcional - Copiado da UI se definido
    // iconKey: "SUA_CHAVE_DE_ICONE",
    // updatedAt: TIMESTAMP,

    // Opcional - Pode ser adicionado/modificado manualmente
    theme: "automatic",
  });

  // Exemplo: Abrir chat via botão personalizado
  // document.getElementById('meu-botao-ajuda')?.addEventListener('click', () => chat.open());
</script>
```

Este script adiciona a bolha de chat flutuante à sua página.

## Implementações Específicas de Plataforma

Veja como você pode adicionar o snippet de script copiado em configurações comuns:

### WordPress

#### Usando um Plugin (Recomendado)

1. Instale e ative um plugin que permita adicionar snippets de código a cabeçalhos/rodapés (por exemplo, "WPCode", "Header Footer Code Manager", "Insert Headers and Footers").
2. Vá para a página de configurações do plugin.
3. Crie um novo snippet.
4. **Cole o snippet do Código da Bolha do Chatmode copiado** na área de código.
5. Configure a localização do snippet para estar no **Rodapé (Footer)**.
6. Certifique-se de que o snippet esteja ativo e salve.

#### Integração com Arquivo do Tema (Avançado)

Se estiver usando um tema filho, você pode editar seu arquivo `footer.php` e colar o snippet de script diretamente antes da chamada `<?php wp_footer(); ?>` ou da tag de fechamento `</body>`.

### Aplicações React / Next.js (Recomendado)

Para frameworks JavaScript modernos como React ou Next.js, a abordagem recomendada é importar dinamicamente o pacote `@chatmode/embed` dentro de um componente do lado do cliente. Isso garante que o código do embed seja carregado apenas quando necessário e se integra bem ao ciclo de vida e processo de build do framework.

**Passos:**

1. **Instale o pacote:**
   ```bash theme={"system"}
   npm install @chatmode/embed
   # ou
   yarn add @chatmode/embed
   # ou
   pnpm add @chatmode/embed
   ```
2. **Crie um Componente Cliente:** Crie um componente que cuidará do carregamento do embed. Certifique-se de que ele esteja marcado como um componente cliente (ex: usando `"use client";` no Next.js App Router).
3. **Use `useEffect` para Inicialização:** Dentro do componente, use um hook `useEffect` para importar dinamicamente e inicializar a bolha. Implemente também uma função de limpeza para remover o embed quando o componente for desmontado.

```jsx theme={"system"}
// Exemplo de Componente Cliente (ex: components/ChatEmbedLoader.tsx)
"use client";

import { useEffect } from "react";
import { useTheme } from "next-themes"; // Exemplo usando next-themes

import type { BubbleControls } from "@chatmode/embed";

export function ChatEmbedLoader() {
  const { resolvedTheme } = useTheme(); // Use sua lógica de detecção de tema

  useEffect(() => {
    let chatmodeBubble: BubbleControls | null = null;

    const loadEmbed = async () => {
      try {
        // Importa dinamicamente o pacote do embed
        const { default: Chatmode } = await import("@chatmode/embed");

        // Inicializa usando seu ID de Ambiente da UI do Chatmode
        // Passe o tema com base na lógica do seu aplicativo
        chatmodeBubble = Chatmode.initBubble({
          environmentId: "SEU_ID_AMBIENTE_DA_UI", // <-- Substitua isso!
          theme: resolvedTheme === 'dark' ? 'dark' : 'light',
          // iconKey e updatedAt podem ser necessários se usar um ícone personalizado
          // iconKey: "SUA_CHAVE_ICONE_DA_UI",
          // updatedAt: SEU_TIMESTAMP_DA_UI,
        });
      } catch (error) {
        console.error("Falha ao carregar o embed do Chatmode:", error);
        // Opcionalmente, reporte o erro a um serviço de rastreamento
      }
    };

    // Carrega o embed quando o componente é montado
    loadEmbed();

    // Função de limpeza: Remove o embed quando o componente é desmontado
    return () => {
      if (chatmodeBubble) {
        chatmodeBubble.remove();
        chatmodeBubble = null;
      }
    };
    // Executa novamente o efeito se o tema mudar
  }, [resolvedTheme]);

  return null; // Este componente não renderiza nada por si só
}

// Então, importe e use <ChatEmbedLoader /> no seu layout raiz ou componente App principal.
```

<Note>
  Substitua `"SEU_ID_AMBIENTE_DA_UI"` pelo ID de Ambiente real copiado das
  configurações do seu Ambiente Chatmode. Adicione `iconKey` e `updatedAt` se
  estiver usando um ícone personalizado carregado via UI.
</Note>

## Considerações Avançadas

### Carregamento Condicional

Para carregar a bolha de chat apenas sob certas condições, execute condicionalmente o código JavaScript que anexa a tag de script. Em frameworks como React/Vue/Angular, envolva a lógica de anexação de script dentro da lógica de renderização condicional do seu componente.

### Otimização de Performance

* **Importação Dinâmica (Avançado):** Em vez de colar o conteúdo do script diretamente, você poderia importar dinamicamente o módulo `@chatmode/embed` apenas quando necessário (por exemplo, após interação do usuário ou conclusão do carregamento da página), embora isso exija uma configuração mais complexa.
* **Localização do Script:** Colocar a tag de script logo antes de `</body>` é geralmente uma boa prática.

### Interação com a Página Pai

A interação direta (chamar funções como `identify`, `setContext` conforme descrito na documentação mais antiga) **não** é suportada pelo método padrão `Chatmode.initBubble`.

No entanto, você **pode** controlar programaticamente o estado do modal de chat (abrir, fechar, alternar) usando o objeto retornado por `Chatmode.initBubble`. Veja o [Guia de Personalização](/pt-br/embeds/customization#controle-programatico) para detalhes.

Se precisar ocultar a própria bolha com base na lógica da página, pode ser necessário recorrer ao carregamento condicional (não adicionando o script) ou a substituições de CSS (`display: none !important;`) visando os elementos da bolha (não recomendado).

## Checklist de Implementação

* [ ] Snippet do **Código da Bolha copiado** das configurações do Ambiente Chatmode.
* [ ] Snippet colado na(s) página(s) HTML relevante(s) ou carregado via lógica de componente do framework.
* [ ] Bolha aparece corretamente em dispositivos desktop e móveis.
* [ ] Funcionalidade do chat testada clicando na bolha e interagindo.

## Solução de Problemas

* **Bolha Não Aparecendo**: Verifique se o snippet de script foi copiado correta e completamente. Verifique erros de JavaScript no console do navegador. Certifique-se de que o ID do Ambiente no snippet esteja correto.
* **Problemas de Estilo**: Verifique conflitos gerais de CSS em sua página. Substituir os estilos internos da bolha diretamente não é recomendado.
* **Problemas de Z-index**: Se a bolha estiver oculta atrás de outros elementos, tente aumentar o z-index de um contêiner pai em sua página.
* **Múltiplas Bolhas**: Certifique-se de que o script seja carregado/inicializado apenas uma vez por carregamento de página, especialmente em Aplicações de Página Única (SPAs).

## Próximos Passos

* Teste minuciosamente em diferentes navegadores e dispositivos.
* Ajuste as configurações do Ambiente no Chatmode para configuração da interface de chat (Nome de Exibição, Imagem, Cores, Mensagem Inicial).