Documentação Técnica: MSPA Script

Guia rigoroso de implementação para garantir sincronia de consentimento, injeção limpa e conformidade LGPD/GDPR sem perda de dados.

1. Hierarquia de Execução: O Primeiro da Fila

O script do MSPA Trust Center não é apenas um utilitário, ele é o Orquestrador de Privacidade. Para que o Google Consent Mode (GCM) e o bloqueio de cookies funcionem, ele precisa ser carregado antes de absolutamente qualquer outra coisa.

🚨 REQUISITO CRÍTICO DE PERFORMANCE

O script DEVE ser a primeira tag dentro do seu <head>.

• PROIBIDO: O uso de atributos async ou defer no script principal.
• OBRIGATÓRIO: Carregamento SINCRONO para garantir o bloqueio preventivo.

<!-- A PRIMEIRA TAG DO HEAD SEMPRE -->
    <script src="https://edge.mspa.com.br/script/v1.js?client_id=SEU_ID"></script>
    <!-- APENAS DEPOIS DISSO VEM O RESTANTE -->
    <meta charset="UTF-8">

2. Convenção do Identificador do Cliente

O mesmo identificador aparece em camadas diferentes do produto, mas com formatos diferentes por convenção técnica. Não tente padronizar o mesmo nome em tudo.

Camada	Nome correto	Exemplo
URL / Query Param	`client_id`	`?client_id=mspa_tc_ABC12345`
JavaScript / JSON	`clientId`	`window.MSPA_CONFIG.clientId`
HTML do componente	`client-id`	`<mspa-consent-guard client-id="mspa_tc_ABC12345">`

⚠️ Migração de Legado

O atributo legado clientid ainda é aceito por compatibilidade retroativa, mas o formato oficial para novas instalações e atualizações é client-id.

<!-- Script de borda -->
    <script src="https://edge.mspa.com.br/script/v1.js?client_id=SEU_ID"></script>

    <!-- Componente visual opcional -->
    <mspa-consent-guard client-id="SEU_ID"></mspa-consent-guard>

3. Limpeza de Scripts Legados (Clean State)

O script do MSPA Trust Center já define o estado padrão do Google Consent Mode (GCM) como negado no carregamento inicial. Para rastreadores opcionais, a execução só deve acontecer depois do consentimento.

⚠️ REMOVA O LIXO TECNOLÓGICO

Você DEVE REMOVER qualquer script antigo que dispare rastreadores opcionais antes do consentimento, inclusive chamadas manuais de gtag('consent', ...) ou pixels carregados fora do fluxo de bloqueio.

Por que remover? Se o seu código antigo rodar antes do nosso script síncrono, os cookies serão disparados antes do consentimento ser verificado, resultando em infração de privacidade e possível duplicação de eventos.

4. Gerenciamento de Scripts de Terceiros

Para scripts opcionais de terceiros (Facebook Pixel, Hotjar, TikTok, GTM customizado, etc), o navegador precisa ser impedido de executá-los nativamente até que o MSPA dê a ordem.

Atributos Obrigatórios para Terceiros:

Atributo	Valor Necessário	Descrição Técnica
`type`	`"text/plain"`	Neutraliza o script. O navegador ignora a execução automática.
`data-mspa-tracking`	(vazio)	Flag que sinaliza ao nosso injetor que este script está sob nossa custódia.
`data-categories`	`"analytics", "marketing", "functional"`	Define em qual categoria de consentimento este script se encaixa. Se houver mais de uma categoria, todas precisam estar concedidas.

<!-- Exemplo de Script do Facebook Pixel Protegido -->
    <script 
       type="text/plain"
       data-mspa-tracking
       data-categories="marketing"
       src="https://connect.facebook.net/en_US/fbevents.js"></script>

🔒 Revogação de Consentimento

Se o usuário revogar uma categoria opcional depois de já ter aceitado, o banner salva o novo estado, registra a auditoria e recarrega a página para garantir que apenas as categorias ainda permitidas continuem ativas.

5. Frameworks Modernos (Next.js / Astro / Remix)

Ao utilizar SSR (Server Side Rendering), a injeção dinâmica da UI do banner pode causar conflitos de hidratação.

💎 BOAS PRÁTICAS

Garanta que os componentes que dependem do estado de consentimento sejam renderizados apenas no lado do cliente (Client-Only). Se você criar o componente manualmente, use client-id no atributo HTML.