Pular para conteúdo

window.complyr

Referência completa do objeto global window.complyr disponibilizado pelo script Complyr para controle programático de consentimento e políticas.

📋 Visão Geral

O objeto window.complyr é criado automaticamente quando o script Complyr carrega no navegador. Ele expõe uma API JavaScript pública para interagir com o sistema de consentimento, políticas e identificação de usuários.

Características: - ✅ Global: Acessível em qualquer lugar via window.complyr - ✅ Read-Only: Métodos públicos apenas (não modificável) - ✅ Assíncrono: Carrega após DOM ready - ✅ Type-Safe: Suporta TypeScript

🚀 Disponibilidade

Quando o Objeto Está Disponível

O objeto window.complyr é criado após o script Complyr carregar completamente:

// ❌ PODE NÃO ESTAR DISPONÍVEL
console.log(window.complyr);  // undefined (se script não carregou)

// ✅ ESPERAR CARREGAMENTO
document.addEventListener('DOMContentLoaded', function() {
  if (window.complyr) {
    console.log('Complyr API disponível');
  }
});

// ✅ USAR EVENTO CUSTOMIZADO
window.addEventListener('complyr:loaded', function() {
  console.log('Complyr carregado:', window.complyr);
});

Verificação de Disponibilidade

// Método 1: Verificação simples
if (typeof window.complyr !== 'undefined') {
  window.complyr.identify('email', 'user@example.com');
}

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

// Método 3: 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', 'user@example.com');
});

📚 Métodos Disponíveis

O objeto window.complyr expõe exatamente 5 métodos públicos:

Resumo dos Métodos

Método Tipo Descrição Uso Comum
loadPolicy() Sync Carrega e exibe política Páginas de termos/privacidade
identify() Sync Identifica usuário Após login
revokeConsent() Sync Revoga consentimento Botão "Excluir dados"
acceptPolicy() Async Aceita política Formulários de cadastro
openPreferences() Sync Abre modal de preferências Links de configuração

loadPolicy()

Carrega o conteúdo de uma política e exibe em elemento HTML.

Assinatura: 

loadPolicy(policyType: string, selector: string): void

Parâmetros: - policyType (string): Tipo da política - 'privacy-policy' - Política de Privacidade - 'terms-of-service' - Termos de Uso - 'cookie-policy' - Política de Cookies - 'data-processing' - Acordo de Processamento - selector (string): Seletor CSS do elemento alvo

Retorno: void (síncrono)

Exemplo: 

// Carregar Política de Privacidade no elemento #policy-container
window.complyr.loadPolicy('privacy-policy', '#policy-container');

Documentação completa →

identify()

Identifica o usuário para Advanced Matching (GTM, Facebook Pixel).

Assinatura: 

identify(identificationType: string, userIdentifier: string): void

Parâmetros: - identificationType (string): Tipo de identificação - 'email' - Email do usuário (recomendado) - 'phone' - Telefone (formato internacional: +5511...) - 'name' - Nome completo - userIdentifier (string): Valor do identificador

Retorno: void (síncrono)

Hashing Automático: O valor é automaticamente hasheado com SHA-256 antes de enviar.

Exemplo: 

// Identificar usuário por email após login
window.complyr.identify('email', 'usuario@example.com');

// Múltiplos identificadores (melhor match rate)
window.complyr.identify('email', 'usuario@example.com');
window.complyr.identify('phone', '+5511987654321');
window.complyr.identify('name', 'João Silva');

Documentação completa →

revokeConsent()

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

Assinatura: 

revokeConsent(reason?: string): void

Parâmetros: - reason (string, opcional): Motivo da revogação (para auditoria)

Retorno: void (síncrono)

Efeitos: - Limpa localStorage.complyr_consent - Bloqueia GTM e Facebook Pixel imediatamente - Remove cookies de rastreamento - Registra evento no backend

Exemplo: 

// Simples
window.complyr.revokeConsent();

// Com motivo (boas práticas)
window.complyr.revokeConsent('Usuário solicitou exclusão de dados - LGPD Art. 18');

Documentação completa →

acceptPolicy()

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

Assinatura: 

acceptPolicy(policyType: string, userIdentifier: string): Promise<void>

Parâmetros: - policyType (string): Tipo da política (mesmo de loadPolicy()) - userIdentifier (string): Email ou identificador único do usuário

Retorno: Promise<void> (assíncrono)

Exemplo: 

// Registrar aceitação de Termos de Uso
try {
  await window.complyr.acceptPolicy('terms-of-service', 'usuario@example.com');
  console.log('Aceite registrado com sucesso');
} catch (error) {
  console.error('Erro ao registrar aceite:', error);
}

Documentação completa →

openPreferences()

Abre o modal de preferências de consentimento programaticamente.

Assinatura: 

openPreferences(): void

Parâmetros: Nenhum

Retorno: void (síncrono)

Exemplo: 

// Abrir modal via botão
document.getElementById('manage-cookies-btn').addEventListener('click', () => {
  window.complyr.openPreferences();
});

Documentação completa →

🔍 Propriedades e Metadados

Além dos métodos, window.complyr pode expor propriedades informativas:

version

Versão do script Complyr carregado.

console.log(window.complyr.version);  // "1.2.3"

workspaceId

ID do workspace configurado no script.

console.log(window.complyr.workspaceId);  // "a1b2c3d4-5e6f-..."

isLoaded

Indica se o script carregou completamente.

if (window.complyr && window.complyr.isLoaded) {
  console.log('Complyr pronto para uso');
}

📐 TypeScript Definitions

Interface Completa

/**
 * API JavaScript do Complyr
 */
interface ComplyrAPI {
  /**
   * Versão do script Complyr
   */
  version: string;

  /**
   * ID do workspace configurado
   */
  workspaceId: string;

  /**
   * Indica se o script foi carregado completamente
   */
  isLoaded: boolean;

  /**
   * Carrega e exibe uma política em um elemento HTML
   * @param policyType - Tipo da política ('privacy-policy', 'terms-of-service', 'cookie-policy', 'data-processing')
   * @param selector - Seletor CSS do elemento onde a política será renderizada
   * @throws {Error} Se o seletor não encontrar nenhum elemento
   * @throws {Error} Se o policyType for inválido
   */
  loadPolicy(policyType: string, selector: string): void;

  /**
   * Identifica o usuário para Advanced Matching (GTM, Facebook Pixel)
   * @param identificationType - Tipo de identificação ('email', 'phone', 'name')
   * @param userIdentifier - Valor do identificador (será hasheado com SHA-256)
   * @throws {Error} Se identificationType for inválido
   * @remarks
   * - Requer consentimento de marketing ou personalização
   * - Email é automaticamente normalizado (lowercase, trim)
   * - Telefone deve estar em formato internacional (+5511...)
   */
  identify(identificationType: string, userIdentifier: string): void;

  /**
   * Revoga o consentimento do usuário
   * @param reason - Motivo da revogação (opcional, para auditoria)
   * @remarks
   * - Limpa localStorage
   * - Bloqueia scripts de rastreamento (GTM, Facebook Pixel)
   * - Remove cookies de terceiros
   * - Registra evento no backend para conformidade LGPD
   */
  revokeConsent(reason?: string): void;

  /**
   * Registra aceitação de uma política específica
   * @param policyType - Tipo da política
   * @param userIdentifier - Email ou identificador único do usuário
   * @returns Promise que resolve quando aceitação for registrada
   * @throws {Error} Se policyType for inválido
   * @throws {Error} Se userIdentifier estiver vazio
   * @remarks
   * - Aceite é registrado no backend com timestamp
   * - Importante para conformidade com LGPD Art. 8º
   */
  acceptPolicy(policyType: string, userIdentifier: string): Promise<void>;

  /**
   * Abre o modal de preferências de consentimento
   * @remarks
   * - Permite ao usuário modificar suas preferências
   * - Útil para links "Gerenciar Cookies" no footer
   */
  openPreferences(): void;
}

/**
 * Extensão do objeto Window
 */
declare global {
  interface Window {
    /**
     * API JavaScript do Complyr
     * Disponível após carregamento do script
     */
    complyr?: ComplyrAPI;
  }
}

export {};

Uso com TypeScript

// app.ts
function handleLogin(email: string) {
  // TypeScript reconhece os tipos automaticamente
  if (window.complyr) {
    window.complyr.identify('email', email);  // ✅ Type-safe
  }
}

// Exemplo com verificação de tipo
function safeComplyrCall(callback: (api: ComplyrAPI) => void) {
  if (window.complyr && typeof window.complyr.identify === 'function') {
    callback(window.complyr);
  } else {
    console.warn('Complyr API não disponível');
  }
}

safeComplyrCall((complyr) => {
  complyr.identify('email', 'user@example.com');
});

🌐 Compatibilidade de Navegadores

Navegador Versão Mínima Suporte
Chrome 60+ ✅ Completo
Firefox 55+ ✅ Completo
Safari 11+ ✅ Completo
Edge 79+ (Chromium) ✅ Completo
Opera 47+ ✅ Completo
Samsung Internet 8+ ✅ Completo
IE 11 - ⚠️ Limitado (polyfills necessários)

Detecção de Recursos

// Verificar suporte básico
const isSupported = (
  typeof window !== 'undefined' &&
  typeof document !== 'undefined' &&
  typeof localStorage !== 'undefined' &&
  typeof Promise !== 'undefined'
);

if (!isSupported) {
  console.warn('Navegador não suportado pelo Complyr');
}

⚠️ Tratamento de Erros

Erros Comuns

Erro: "Complyr is not defined"

// ❌ PROBLEMA
window.complyr.identify('email', 'user@example.com');
// ReferenceError: complyr is not defined

// ✅ SOLUÇÃO
if (window.complyr) {
  window.complyr.identify('email', 'user@example.com');
} else {
  console.warn('Aguardando Complyr carregar...');
}

Erro: "Invalid policy type"

// ❌ PROBLEMA
window.complyr.loadPolicy('invalid-policy', '#container');
// Error: Invalid policy type

// ✅ SOLUÇÃO
const validTypes = ['privacy-policy', 'terms-of-service', 'cookie-policy', 'data-processing'];
const policyType = 'privacy-policy';

if (validTypes.includes(policyType)) {
  window.complyr.loadPolicy(policyType, '#container');
}

Erro: "Element not found"

// ❌ PROBLEMA
window.complyr.loadPolicy('privacy-policy', '#nonexistent');
// Error: Element with selector '#nonexistent' not found

// ✅ SOLUÇÃO
const element = document.querySelector('#policy-container');
if (element) {
  window.complyr.loadPolicy('privacy-policy', '#policy-container');
} else {
  console.error('Elemento não encontrado');
}

Try/Catch Recomendado

// Para métodos síncronos
try {
  window.complyr.identify('email', userEmail);
} catch (error) {
  console.error('Erro ao identificar usuário:', error);
  // Enviar para sistema de logging
}

// Para métodos assíncronos
try {
  await window.complyr.acceptPolicy('terms-of-service', userEmail);
} catch (error) {
  console.error('Erro ao aceitar política:', error);
  // Exibir mensagem ao usuário
}

🔒 Segurança

Dados Sensíveis

SHA-256 Automático: 

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

// Complyr hasheia antes de enviar:
// '5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8'

Nunca exposto: - ❌ Email nunca enviado em texto plano - ❌ Telefone nunca exposto sem hash - ✅ Apenas hash SHA-256 é transmitido

Content Security Policy (CSP)

Se seu site usa CSP, adicione:

<meta http-equiv="Content-Security-Policy"
      content="script-src 'self' https://app.complyr.com.br;">

📊 Debug e Logs

Modo Debug

Ative logs detalhados:

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

// Verá logs como:
// [Complyr] API loaded v1.2.3
// [Complyr] User identified: email
// [Complyr] Consent status: GRANTED
// [Complyr] Policy loaded: privacy-policy

Inspecionar Estado

// Ver versão
console.log('Complyr version:', window.complyr.version);

// Ver workspace ID
console.log('Workspace:', window.complyr.workspaceId);

// Ver consentimento atual
const consent = JSON.parse(localStorage.getItem('complyr_consent'));
console.log('Consent:', consent);

🔗 Recursos Relacionados

Métodos Individuais: - 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 JavaScript - Lista completa de eventos - Exemplos Práticos - Casos de uso completos - API Overview - Visão geral da API

📞 Suporte

Dúvidas sobre o objeto window.complyr?