ai-search-widget

v0.0.11

Published

9 months ago

AI Search Widget

Downloads

0High
0Medium
0Low

labzz

Documentação AI Search

1. Título

Componente Web <ai-search> para Busca com Inteligência Artificial

2. Objetivo

Este manual tem como objetivo apresentar a especificação técnica, orientações de uso, instalação e integração do Web Component <ai-search>, desenvolvido com encapsulamento via Shadow DOM e suporte à inteligência artificial para aplicações web.

3. Descrição Geral

O <ai-search> é um componente web personalizado, baseado nos padrões modernos da Web (Web Components e ES Modules), que provê um campo de busca com inteligência artificial. O componente foi desenvolvido com isolamento de estilos via Shadow DOM, garantindo compatibilidade com qualquer aplicação frontend, independente do framework utilizado.

4. Requisitos Técnicos

Navegador com suporte a Web Components (Shadow DOM v1).
Suporte a ES Modules (<script type="module">).
Chave pública válida fornecida pela Toolzz.
(Opcional) Google Tag Manager configurado para análise de dados.

5. Instalação

5.1 Inclusão do Script

O script do componente deve ser adicionado no cabeçalho (<head>) da aplicação HTML:

<script type="module" src="https://unpkg.com/ai-search-widget/dist/ai-search.umd.js"></script>

6. Utilização

Para utilizar o componente, insira a tag personalizada <ai-search> no local desejado da aplicação. O atributo public-key é obrigatório.

6.1 Exemplo Básico

<ai-search
  public-key="SUA_CHAVE_PUBLICA"
  organization-id="SUA_ORGANIZACAO"
  theme="light"
  placeholder="O que você deseja buscar?"
></ai-search>

6.2 Exemplo com Google Tag Manager

<ai-search
  public-key="SUA_CHAVE_PUBLICA"
  organization-id="SUA_ORGANIZACAO"
  gtm="GTM-XXXXXXX"
  theme="dark"
  placeholder="Buscar cursos e conteúdos..."
></ai-search>

7. Atributos Disponíveis

| Atributo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | public-key | string | Sim | Chave pública para autenticação na API. Fornecida pela Toolzz. | | organization-id | string | Sim | Identificador da organização na plataforma Toolzz. | | theme | string | Não | Tema visual do componente. Aceita valores: light ou dark (padrão: light). | | placeholder | string | Não | Texto de orientação exibido no campo de busca. | | gtm | string | Não | ID do Google Tag Manager para tracking de eventos (ex: GTM-XXXXXXX). |

8. Tracking e Análise com GTM

O componente oferece integração nativa com Google Tag Manager, permitindo análise detalhada do comportamento dos usuários. Quando o atributo gtm é fornecido, os seguintes eventos são automaticamente enviados:

8.1 Eventos Disponíveis

| Evento | Descrição | Dados Incluídos | | --- | --- | --- | | search_submitted | Busca enviada pelo usuário | search_query, query_length | | search_results_loaded | Resultados carregados com sucesso | search_query, results_count, has_clarification, has_ai_response | | course_selected | Curso selecionado pelo usuário | course_title, course_url, search_query, selected_index | | search_closed | Interface de busca fechada | method (escape/button_click) | | search_focus | Campo de busca recebeu foco | - | | clarification_submitted | Clarificação enviada | original_query, enhanced_query | | search_error | Erro durante a busca | error_message, search_query | | clarification_error | Erro na clarificação | error_message, original_query, enhanced_query |

8.2 Estrutura dos Eventos

Todos os eventos são enviados com a seguinte estrutura:

gtag('event', 'nome_do_evento', {
  event_category: 'ai_search',
  event_label: 'GTM-XXXXXXX',
  // ... dados específicos do evento
});

9. Encapsulamento e Estilo

O componente faz uso de Shadow DOM, o que proporciona:

Isolamento completo de estilos entre o componente e a aplicação hospedeira.
Nenhum estilo externo afeta o <ai-search>, e os estilos internos também não interferem no DOM global.

Esta abordagem permite integração segura e previsível, independente do framework ou do stack CSS utilizado.

10. Exemplos de Integração

10.1 Integração Básica

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script
      type="module"
      src="https://unpkg.com/ai-search-widget/dist/ai-search.umd.js"
    ></script>
    <title>Integração - AI Search</title>
  </head>
  <body>
    <h1>Sistema de Busca</h1>
    <ai-search
      public-key="exemplo-chave-publica"
      organization-id="exemplo-org"
      theme="light"
      placeholder="O que você deseja buscar?"
    ></ai-search>
  </body>
</html>

10.2 Integração com Google Tag Manager

<!DOCTYPE html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    
    <!-- Google Tag Manager -->
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
    new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
    j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
    'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
    })(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
    <!-- End Google Tag Manager -->
    
    <script
      type="module"
      src="https://unpkg.com/ai-search-widget/dist/ai-search.umd.js"
    ></script>
    <title>Integração com GTM - AI Search</title>
  </head>
  <body>
    <!-- Google Tag Manager (noscript) -->
    <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
    height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <!-- End Google Tag Manager (noscript) -->
    
    <h1>Sistema de Busca com Analytics</h1>
    <ai-search
      public-key="exemplo-chave-publica"
      organization-id="exemplo-org"
      gtm="GTM-XXXXXXX"
      theme="dark"
      placeholder="Buscar cursos e conteúdos..."
    ></ai-search>
  </body>
</html>

10.3 Integração com React

import React from 'react';

function App() {
  return (
    <div className="App">
      <h1>Minha Aplicação React</h1>
      <ai-search
        public-key="exemplo-chave-publica"
        organization-id="exemplo-org"
        gtm="GTM-XXXXXXX"
        theme="light"
        placeholder="Buscar..."
      />
    </div>
  );
}

export default App;

10.4 Integração com Vue.js

<template>
  <div>
    <h1>Minha Aplicação Vue</h1>
    <ai-search
      public-key="exemplo-chave-publica"
      organization-id="exemplo-org"
      gtm="GTM-XXXXXXX"
      theme="dark"
      placeholder="Buscar..."
    />
  </div>
</template>

<script>
export default {
  name: 'App',
  mounted() {
    // O Web Component já está disponível globalmente
  }
}
</script>

11. Configuração Avançada do GTM

11.1 Configuração de Triggers

Para capturar os eventos do AI Search no GTM, configure triggers customizados:

Acesse o Google Tag Manager
Crie um novo Trigger
Selecione "Evento personalizado"
Configure o nome do evento (ex: search_submitted)
Adicione condições se necessário:
- event_category equals ai_search

11.2 Exemplo de Tag do Google Analytics

// Configuração de tag para Google Analytics 4
gtag('config', 'GA_MEASUREMENT_ID', {
  custom_map: {
    'custom_parameter_1': 'search_query',
    'custom_parameter_2': 'results_count'
  }
});

12. Compatibilidade entre Navegadores

| Navegador | Compatibilidade | | --- | --- | | Google Chrome | ✅ Completo | | Microsoft Edge | ✅ Completo | | Mozilla Firefox | ✅ Completo | | Safari | ✅ Completo | | Opera | ✅ Completo | | Internet Explorer | ❌ Incompatível¹ |

¹ O Internet Explorer não é compatível com Web Components nem com ES Modules.

13. Suporte e Troubleshooting

13.1 Problemas Comuns

Componente não aparece:

Verifique se o script está carregado corretamente
Confirme que public-key e organization-id estão definidos
Verifique o console do navegador para erros

GTM não está funcionando:

Confirme que o GTM está inicializado na página
Verifique se o ID do GTM está correto no atributo gtm
Abra o console e verifique se window.dataLayer existe

Estilos não aparecem corretamente:

O componente usa Shadow DOM - estilos externos não se aplicam
Utilize os atributos theme para personalização básica

13.2 Debug dos Eventos GTM

Para debugar os eventos GTM, abra o console do navegador e execute:

// Monitora todos os eventos enviados ao dataLayer
window.dataLayer.push(function() {
  console.log('GTM Event:', arguments);
});