Pular para conteúdo

API JavaScript

Interface completa de programação JavaScript para controlar consentimento, políticas e identificação de usuários na plataforma Complyr.

🎯 Visão Geral

A API JavaScript do Complyr fornece um conjunto de métodos globais acessíveis via window.complyr para controle programático de:

  • ✅ Consentimento de usuários: Aceitar, revogar, consultar
  • ✅ Identificação de usuários: Advanced Matching para GTM e Facebook Pixel
  • ✅ Gerenciamento de políticas: Carregar, aceitar, exibir políticas
  • ✅ Controle de preferências: Abrir modal de preferências programaticamente
  • ✅ Eventos personalizados: Reagir a mudanças de consentimento

Disponibilidade: 

// Verificar se API está disponível
if (window.complyr) {
  console.log('Complyr API disponível');
} else {
  console.log('Aguardando carregamento...');
}

🚀 Início Rápido

Instalação do Script

<script
  src="https://app.complyr.com.br/tag/js"
  data-workspace-id="SEU_WORKSPACE_ID"
  data-complyr-script
  async
  defer>
</script>

Primeiro Uso

// Aguardar carregamento completo
document.addEventListener('DOMContentLoaded', function() {
  if (window.complyr) {
    // API pronta para uso
    window.complyr.identify('email', 'usuario@example.com');
  }
});

// Ou usar evento customizado
window.addEventListener('complyr:loaded', function() {
  console.log('Complyr carregado!');
  window.complyr.identify('email', 'usuario@example.com');
});

📋 Métodos Disponíveis

A API Complyr expõe 5 métodos principais via window.complyr:

1. loadPolicy()

Carrega e exibe uma política em elemento HTML específico.

window.complyr.loadPolicy('privacy-policy', '#policy-container');

Casos de uso: - Exibir Política de Privacidade em página dedicada - Mostrar Termos de Uso em formulário de cadastro - Renderizar Política de Cookies em modal

Documentação completa →

2. identify()

Identifica o usuário para Advanced Matching em GTM e Facebook Pixel.

window.complyr.identify('email', 'usuario@example.com');

Casos de uso: - Melhorar match rate de Facebook Pixel - Ativar Advanced Matching após login - Rastreamento cross-device - Enhanced Conversions no Google Ads

Documentação completa →

3. revokeConsent()

Revoga o consentimento do usuário, bloqueando scripts de rastreamento.

window.complyr.revokeConsent('Usuário solicitou exclusão de dados');

Casos de uso: - Implementar botão "Excluir meus dados" - Conformidade com LGPD Art. 18, VI (direito à exclusão) - Resetar consentimento para novos testes - Responder a solicitações DSAR

Documentação completa →

4. acceptPolicy()

Registra aceitação de uma política específica por um usuário identificado.

await window.complyr.acceptPolicy('terms-of-service', 'usuario@example.com');

Casos de uso: - Registrar aceite de Termos de Uso no cadastro - Auditar aceitação de Política de Privacidade - Conformidade com LGPD Art. 8º (consentimento) - Histórico legal de aceitações

Documentação completa →

5. openPreferences()

Abre o modal de preferências de consentimento programaticamente.

window.complyr.openPreferences();

Casos de uso: - Botão "Gerenciar Preferências de Cookies" no footer - Link na Política de Privacidade - Menu de configurações de privacidade - Reabrir preferências após mudanças no site

Documentação completa →

🔔 Eventos JavaScript

A API Complyr dispara eventos customizados que você pode escutar:

Eventos Disponíveis

Evento Descrição Dados
complyr:loaded Script Complyr carregou completamente { version: string }
complyr:consent-updated Consentimento foi atualizado { purposes: {...}, status: string }
complyr:consent-revoked Consentimento foi revogado { reason: string }
complyr:user-identified Usuário foi identificado { type: string }
complyr:policy-accepted Política foi aceita { policyType: string, user: string }

Exemplo de Uso

// Escutar mudanças de consentimento
window.addEventListener('complyr:consent-updated', function(event) {
  const consent = event.detail;
  console.log('Consentimento atualizado:', consent);

  if (consent.purposes.marketing) {
    console.log('Marketing habilitado - carregar scripts de ads');
  }
});

// Escutar identificação de usuário
window.addEventListener('complyr:user-identified', function(event) {
  console.log('Usuário identificado:', event.detail);
});

Documentação completa de eventos →

📖 Referência Completa

TypeScript Definitions

interface ComplyrAPI {
  /**
   * Carrega e exibe uma política em um elemento HTML
   * @param policyType - Tipo da política ('privacy-policy', 'terms-of-service', etc.)
   * @param selector - Seletor CSS do elemento alvo
   */
  loadPolicy(policyType: string, selector: string): void;

  /**
   * Identifica usuário para Advanced Matching
   * @param identificationType - Tipo de identificação ('email', 'phone', 'name')
   * @param userIdentifier - Valor do identificador (hasheado automaticamente)
   */
  identify(identificationType: string, userIdentifier: string): void;

  /**
   * Revoga consentimento do usuário
   * @param reason - Motivo da revogação (opcional)
   */
  revokeConsent(reason?: string): void;

  /**
   * Registra aceitação de política
   * @param policyType - Tipo da política
   * @param userIdentifier - Email ou identificador do usuário
   * @returns Promise<void>
   */
  acceptPolicy(policyType: string, userIdentifier: string): Promise<void>;

  /**
   * Abre modal de preferências de consentimento
   */
  openPreferences(): void;
}

declare global {
  interface Window {
    complyr: ComplyrAPI;
  }
}

Documentação do objeto window.complyr →

🎓 Exemplos Práticos

Exemplo 1: Identificação Após Login

// Em sua função de login
async function handleLogin(email, password) {
  try {
    // 1. Autenticar usuário
    const user = await authService.login(email, password);

    // 2. Identificar no Complyr (para Advanced Matching)
    if (window.complyr) {
      window.complyr.identify('email', user.email);
    }

    // 3. Redirecionar
    window.location.href = '/dashboard';
  } catch (error) {
    console.error('Login failed:', error);
  }
}

Exemplo 2: Aceitar Termos no Cadastro

// Formulário de cadastro
async function handleRegister(formData) {
  try {
    // 1. Criar conta
    const user = await api.register({
      name: formData.name,
      email: formData.email,
      password: formData.password
    });

    // 2. Registrar aceitação de Termos de Uso
    if (formData.acceptedTerms && window.complyr) {
      await window.complyr.acceptPolicy('terms-of-service', user.email);
    }

    // 3. Identificar para rastreamento
    if (window.complyr) {
      window.complyr.identify('email', user.email);
    }

    // 4. Sucesso
    showSuccess('Conta criada com sucesso!');
  } catch (error) {
    console.error('Registration failed:', error);
  }
}

Exemplo 3: Botão "Excluir Meus Dados"

// Página de configurações de privacidade
function handleDeleteAccount() {
  if (confirm('Tem certeza que deseja excluir sua conta e dados?')) {
    // 1. Revogar consentimento
    if (window.complyr) {
      window.complyr.revokeConsent('Usuário solicitou exclusão de conta');
    }

    // 2. Chamar API de exclusão
    api.deleteAccount()
      .then(() => {
        alert('Conta excluída com sucesso.');
        window.location.href = '/';
      })
      .catch(error => {
        console.error('Delete failed:', error);
      });
  }
}

Exemplo 4: Carregar Política em Modal

// Abrir modal com Política de Privacidade
function showPrivacyPolicy() {
  // 1. Criar modal
  const modal = document.createElement('div');
  modal.id = 'privacy-modal';
  modal.innerHTML = `
    <div class="modal-overlay">
      <div class="modal-content">
        <button class="close-btn" onclick="closePrivacyModal()">×</button>
        <div id="policy-content"></div>
      </div>
    </div>
  `;
  document.body.appendChild(modal);

  // 2. Carregar política via Complyr
  if (window.complyr) {
    window.complyr.loadPolicy('privacy-policy', '#policy-content');
  }
}

function closePrivacyModal() {
  document.getElementById('privacy-modal')?.remove();
}

Exemplo 5: React Hook para Identificação

// hooks/useComplyrIdentify.ts
import { useEffect } from 'react';
import { useAuth } from '@/contexts/auth-context';

export function useComplyrIdentify() {
  const { user } = useAuth();

  useEffect(() => {
    if (user?.email && window.complyr) {
      // Identificar automaticamente quando usuário autenticado
      window.complyr.identify('email', user.email);
    }
  }, [user]);
}

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }) {
  useComplyrIdentify();  // Auto-identify usuário logado

  return <div>{children}</div>;
}

Mais exemplos práticos →

🔐 Segurança e Privacidade

Hashing Automático

Todos os dados identificáveis são automaticamente hasheados com SHA-256 antes de enviar ao servidor:

// Você envia:
window.complyr.identify('email', 'usuario@example.com');

// Complyr envia ao servidor:
{
  identificationType: 'email',
  hashedValue: '5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8'
  // SHA-256 hash - impossível reverter
}

Benefícios: - ✅ Email original nunca exposto em rede - ✅ Conformidade com LGPD Art. 46 (segurança) - ✅ Impossível decodificar o hash - ✅ Apenas matching é possível (Facebook, Google)

Validação de Consentimento

Métodos que requerem consentimento verificam automaticamente:

// Se usuário NÃO aceitou marketing:
window.complyr.identify('email', 'usuario@example.com');
// → Bloqueado silenciosamente, nada enviado

// Se usuário ACEITOU marketing:
window.complyr.identify('email', 'usuario@example.com');
// → Email hasheado e enviado para Advanced Matching

⚙️ Configuração Avançada

Aguardar Carregamento da API

// Método 1: Polling
function waitForComplyr(callback) {
  if (window.complyr) {
    callback();
  } else {
    setTimeout(() => waitForComplyr(callback), 100);
  }
}

waitForComplyr(() => {
  window.complyr.identify('email', 'usuario@example.com');
});

// Método 2: Promise
function whenComplyrReady() {
  return new Promise((resolve) => {
    if (window.complyr) {
      resolve(window.complyr);
    } else {
      window.addEventListener('complyr:loaded', () => {
        resolve(window.complyr);
      }, { once: true });
    }
  });
}

// Uso
whenComplyrReady().then((complyr) => {
  complyr.identify('email', 'usuario@example.com');
});

Debug Mode

Ative logs detalhados no console:

// Ativar debug
localStorage.setItem('complyr_debug', 'true');

// Recarregar página
location.reload();

// Verá logs como:
// [Complyr] API loaded
// [Complyr] User identified: email
// [Complyr] Consent status: GRANTED
// [Complyr] Advanced Matching enabled

Para desativar: 

localStorage.removeItem('complyr_debug');

📚 Documentação Completa

Objeto Principal: - window.complyr - Referência completa do objeto global

Métodos: - loadPolicy() - Carregar e exibir políticas - identify() - Identificação de usuários - revokeConsent() - Revogar consentimento - acceptPolicy() - Aceitar políticas - openPreferences() - Abrir modal de preferências

Recursos: - Eventos - Lista completa de eventos JavaScript - Exemplos - Casos de uso práticos completos

❓ Perguntas Frequentes

P: A API funciona em todos os navegadores?

R: Sim! Compatível com todos os navegadores modernos (Chrome, Firefox, Safari, Edge) e IE11+.

P: Posso usar a API antes do script carregar?

R: Não. Aguarde o evento complyr:loaded ou verifique typeof window.complyr !== 'undefined'.

P: Os métodos são síncronos ou assíncronos?

R: - Síncronos: loadPolicy(), identify(), revokeConsent(), openPreferences() - Assíncrono: acceptPolicy() (retorna Promise)

P: Preciso de permissão do usuário para usar identify()?

R: Sim. identify() só funciona se usuário aceitou consentimento de Marketing ou Personalização.

P: Como saber se identify() foi executado?

R: Escute o evento complyr:user-identified:

window.addEventListener('complyr:user-identified', function(event) {
  console.log('Usuário identificado:', event.detail);
});

🔗 Próximos Passos

Comece explorando os métodos mais comuns:

  1. identify() - Identificar usuários após login
  2. openPreferences() - Adicionar botão de preferências
  3. Eventos - Reagir a mudanças de consentimento
  4. Exemplos - Ver implementações completas

📞 Suporte

Dúvidas sobre a API JavaScript?