Manual do Sistema D'Vision
Guia completo de arquitetura, instalação e rastreamento Omnichannel.
1
Visão Geral da Arquitetura
O ecossistema é dividido em duas grandes peças que conversam entre si:
1. Lead Vision (O Cérebro)
Um plugin de WordPress (Backend). Ele fica instalado no Site Principal do Cliente e é responsável por receber os webhooks do CRM/Omnichannel, registrar os cliques e calcular o ROAS. Ele possui um banco de dados próprio para guardar os leads.
2. D'Vision (A Dashboard)
Um arquivo HTML único (Frontend). É a interface elegante onde o cliente visualiza os dados em tempo real e gera relatórios em PDF. Ela consome as informações diretamente do Site Principal via API.
2
Instalação do Plugin & Webhooks
Passo 1: Instalar o Plugin
- Pegue a pasta
lead-visione compacte para.zip. - No WordPress Principal, vá em Plugins > Adicionar Novo > Enviar Plugin.
- Faça o upload do ZIP e clique em Ativar.
Passo 2: Configurar o Painel
- No menu lateral do WordPress, aparecerá a aba Integração Omnichannel.
- Gatilhos do Funil: Defina os nomes exatos das etiquetas que os atendentes vão usar no CRM (Ex: "Venda Fechada"). O plugin usará isso para contabilizar as vendas.
- Senha da Dashboard: Crie a senha Mestra para proteger os dados.
Como integrar qualquer Omnichannel via Webhook
Para que a plataforma Omnichannel avise o plugin sobre novas mensagens, você deve cadastrar a URL de Webhook no painel deles:
https://SEUSITE.com.br/wp-json/atn/v1/omnichannel-webhook
Adaptando o Código (Para Desenvolvedores):
Cada Omnichannel envia o JSON com nomes de campos diferentes. No arquivo lead-vision.php, na função atn_handle_webhook, você adapta 3 variáveis simples para ler o formato deles:
// 1. Onde fica o Telefone do Lead no JSON deles?
$phone_raw = $payload['chat'] ?? $payload['cliente']['telefone'] ?? '';
// 2. Onde fica o Nome da Etiqueta/Tag que o atendente aplicou?
$tag_name = $payload['data']['name'] ?? $payload['tag'] ?? '';
// Pronto! O plugin já fará a mágica de casar o telefone com o clique.
3
Rastreamento em Landing Pages Secundárias
Se o cliente possui Landing Pages ou sites secundários, NÃO instale o plugin do WordPress lá. Use a inteligência de API invisível.
Por que não injetamos as UTMs no texto do WhatsApp?
Não colocamos as UTMs na mensagem padrão do WhatsApp porque o cliente pode apagar o texto antes de enviar, quebrando o rastreamento. Usamos um script que envia os dados pro Servidor silenciosamente no momento do clique, antes de abrir o WhatsApp!
Instalação via Elementor (Site Secundário)
No site secundário, vá em Elementor > Custom Code, crie um novo e defina a Location como <body> - End. Cole o código:
<!-- Script de Rastreamento API Invisível -->
<script>
document.addEventListener("DOMContentLoaded", function() {
const urlParams = new URLSearchParams(window.location.search);
let savedUtms = JSON.parse(localStorage.getItem('dvision_utms')) || {};
let hasNewUtms = false;
['utm_source', 'utm_campaign'].forEach(utm => {
if (urlParams.has(utm)) { savedUtms[utm] = urlParams.get(utm); hasNewUtms = true; }
});
if (hasNewUtms) localStorage.setItem('dvision_utms', JSON.stringify(savedUtms));
document.querySelectorAll('a[href*="wa.me"], a[href*="api.whatsapp.com"]').forEach(link => {
link.addEventListener('click', function(e) {
e.preventDefault();
let validUrl = this.getAttribute('href').startsWith('http') ? this.getAttribute('href') : 'https://' + this.getAttribute('href').replace(/^\/\//, '');
// Defina aqui o nome da Landing Page
let origemRica = "Landing Page 01";
if (savedUtms.utm_source) origemRica += " | Fonte: " + savedUtms.utm_source;
if (savedUtms.utm_campaign) origemRica += " | Camp: " + savedUtms.utm_campaign;
// Altere para a URL do Site Principal onde está o Plugin
fetch('https://SEU-SITE-PRINCIPAL.com.br/wp-json/atn/v1/lead-click', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ origem: origemRica })
}).catch(err => console.log(err));
window.open(validUrl, '_blank');
});
});
});
</script>
4
Como Gerar Tokens que NÃO Expiram
Atenção Crítica aos Tokens
Tokens padrão (OAuth normal) gerados por vias rápidas expiram em 60 dias (Meta) ou 7 dias (Google Teste). Se expirarem, a Dashboard ficará zerada. Para entregar o projeto ao cliente, você obrigatoriamente deve gerar Tokens Permanentes usando as rotas corporativas abaixo.
Google Ads (Refresh Token Vitalício)
1. Publique a Tela de Consentimento OAuth
No Google Cloud Console (GCP), vá em "APIs e Serviços" > "Tela de Consentimento OAuth". Altere o status de "Testando" para "Produção / Publicado". Enquanto estiver em Teste, o Refresh Token morre em 7 dias.
2. Gere o Refresh Token Oficial
Com o Client ID e Secret em mãos, vá ao Google OAuth 2.0 Playground. Autorize as APIs do Google Ads e clique em "Exchange authorization code for tokens". O Refresh Token gerado aqui (em status de Produção) será Vitalício.
Meta Ads (System User Token)
Por que o Token Expirou?
Tokens gerados no painel de ferramentas do "Facebook for Developers" expiram em 60 dias.
A Solução: Usuário de Sistema (Vitalício)
1. Acesse o Gerenciador de Negócios (Business Manager) do Cliente.
2. Vá em Configurações do Negócio > Usuários > Usuários do Sistema.
3. Clique em Adicionar (Ex: Nome: Integrador DVision, Função: Administrador).
4. Atribua os Ativos (A conta de anúncios e a página) a esse Usuário de Sistema.
5. Clique em "Gerar Novo Token". Selecione as permissões ads_read e read_insights.
Este token gerado NUNCA EXPIRA.
5
Injeção de UTMs e Pixel
UTMs no Google Ads
Nas Opções de URL da campanha, use o "Modelo de Acompanhamento":
{lpurl}?utm_source=google&utm_medium=cpc&utm_campaign={campaignid}
Pixel do Meta (Boas Práticas)
Para garantir que PageView dispare 100% das vezes sem atrasos:
Vá em Elementor > Custom Code > Novo. Selecione <head> e cole a tag padrão fornecida pelo Gerenciador de Eventos.