# Configuração

> Atributos do snippet, configuração remota, modos monitor e bloqueio, pausa e canais.

URL: https://docs.proteside.com/pt-BR/docs/integration/configuration

Quase toda a configuração do SDK é feita no dashboard e chega ao navegador pela configuração remota. O snippet só
carrega a chave da loja e, quando há, as regras inline. Esta página mostra de onde vem cada ajuste e o que ele faz de
fato no checkout.

## Atributos do snippet
O `shield.js` lê os atributos `data-*` da própria tag `<script>`:

- `data-key` (`string`), obrigatório: Chave do SDK da loja (começa com pk_live_). Sem ela, o SDK não inicializa e não mostra aviso.
- `data-api` (`string`), padrão: `https://app.proteside.com/api/sdk`: Endereço base da API do Proteside, incluindo o caminho /api/sdk. O dashboard sempre preenche com o valor padrão; não altere.

Não existem outros atributos. O modo de proteção e o canal **não** são definidos por atributo: o modo vem do
dashboard e o canal é a própria URL do `shield.js`. O atributo `data-safe-url`, de versões antigas do snippet, é
ignorado.

## Configuração remota
Ao iniciar, o SDK busca a configuração da loja em `app.proteside.com`. Quando as camadas divergem, vale esta ordem de
prioridade:

1. **Configuração remota** (o que está salvo no dashboard);
2. **Snippet** (atributos `data-*` e regras inline);
3. **Padrões do SDK.**

Chave inválida, erro ou falta de rede nunca quebram a página. As alterações chegam ao checkout em poucos minutos. Para
conferir uma mudança, aguarde alguns minutos e recarregue o checkout.

### O que vem do dashboard
A maior parte fica em **Configurações → Proteção do pagamento**, organizada em quatro passos:

*Imagem: Passo 1 da tela Proteção do pagamento: como a verificação funciona, recebedores vistos no checkout, recebedores confiáveis e cadastro manual*

| Passo e ajuste no dashboard                                                                 | Efeito no SDK                                                                                                                                                                                   |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Quem pode receber o seu dinheiro** → **Recebedores confiáveis**                           | Chaves Pix, contas, carteiras cripto e bancos de boleto da loja. Veja [Integridade de pagamento e Pix](https://docs.proteside.com/pt-BR/docs/integration/payment-integrity).                                                                |
| **Como o SDK deve reagir** → **Modo de proteção**                                           | **Monitorar** ou **Bloquear**. Veja abaixo.                                                                                                                                                     |
| **Como o SDK deve reagir** → **Opções para a equipe técnica** → **Modo desenvolvedor**      | Pausa o SDK. Veja [Pausa e modo desenvolvedor](#pausa-e-modo-desenvolvedor).                                                                                                                    |
| **Como o SDK deve reagir** → **Opções para a equipe técnica** → **Canal de release do SDK** | Só informativo para o SDK. O canal efetivo é a URL colada no snippet. Veja [Canais](https://docs.proteside.com/pt-BR/docs/integration/install#canais-stable-e-latest).                                                                      |
| **O que é normal no seu checkout** → **Origens de iframe esperadas**                        | Hosts dos iframes legítimos de pagamento. Com a lista preenchida, o SDK alerta iframes de provedores fora dela, iframes sobrepostos aos esperados e campos de cartão digitáveis fora do iframe. |
| **O que é normal no seu checkout** → **Containers GTM permitidos**                          | Com a lista preenchida, containers fora dela são barrados. Veja o aviso abaixo.                                                                                                                 |
| **O que é normal no seu checkout** → **Service workers permitidos (avançado)**              | Com a lista preenchida, service workers fora dela são reportados e, no modo **Bloquear**, removidos.                                                                                            |
| **Meios de pagamento detectados**                                                           | Só leitura. O SDK reconhece sozinho os meios de pagamento da página; não há nada para marcar.                                                                                                   |
| **Campos extras para vigiar** → **Seletores extras (opcional)**                             | Campos sensíveis com nome fora do padrão. Os seletores somam à detecção automática; nada é desligado.                                                                                           |

O aviso de ordem de instalação não é mais configurado nesta tela. O próprio alerta `INSTALLATION_ORDER_WARNING`
oferece a opção **Não avisar mais nesta loja**. Veja [Solução de problemas](https://docs.proteside.com/pt-BR/docs/integration/troubleshooting#ordem-de-instalacao).

As regras de **Regras** (bloquear ou permitir por **Domínio** ou **URL do script**) também chegam pela configuração
remota.

> **Bloqueio por endereço**
>
> O bloqueio no navegador vale para scripts carregados por endereço; scripts inline devem ser removidos na origem. Para
> impedir um script, use uma regra por **Domínio** ou **URL do script**.

### Campos sensíveis
O SDK reconhece os campos de cartão mais comuns; marque outros com `data-proteside-sensitive` ou configure em
Proteção do pagamento.

Para incluir um campo próprio sem mexer no dashboard, marque-o com o atributo `data-proteside-sensitive`:

```html
<input id="cpf" name="cpf" data-proteside-sensitive />
```

No dashboard, use **Campos extras para vigiar** → **Seletores extras (opcional)**, com um seletor CSS por linha. O que
você adicionar soma à detecção automática: a lista não substitui os campos que o SDK já reconhece.

## Modo monitor e modo bloqueio
O modo é escolhido em **Proteção do pagamento → Como o SDK deve reagir → Modo de proteção** e chega ao SDK pela
configuração remota.

### O que acontece em qualquer modo
> **Regras e lista de GTM bloqueiam também no modo Monitorar**
>
> As **regras de bloqueio** (por domínio ou URL) e a lista de **Containers GTM permitidos** bloqueiam scripts **nos
> dois modos**. O modo decide só as reações automáticas do SDK ao que não tem regra. Se você quer só observar, não crie
> regras de bloqueio e deixe a lista de GTM vazia.

* Um script que casa com uma regra de bloqueio é barrado antes de entrar na página, e o SDK envia `SCRIPT_BLOCKED`.
  Scripts escritos no HTML da página devem ser removidos na origem.
* Com a lista de GTM preenchida, containers fora dela são barrados. O SDK envia `GTM_CONTAINER_BLOCKED`.
* Uma regra **Permitir** que case com o script anula as regras de bloqueio.
* `cdn.proteside.com` e `app.proteside.com` nunca são bloqueados.

> **A lista de GTM também pode barrar GA4 e Google Ads**
>
> A lista aceita só IDs no formato `GTM-XXXXXXX`. Com ela preenchida, tags do Google Analytics 4 (`G-…`) e do Google
> Ads (`AW-…`) também podem ser barradas, inclusive quando disparadas pelo próprio GTM, e não há como incluir esses IDs
> na lista. Antes de ativar a lista, confirme se a loja usa essas tags e teste o checkout.

### O que muda no modo Bloquear
Além de alertar, o SDK tenta neutralizar a adulteração:

| Detecção                                                                                                 | Ação no modo **Bloquear**                                                                          |
| -------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `SCRIPT_INJECTION` de script desconhecido                                                                | Remove a tag do script depois de detectar.                                                         |
| `FORM_ACTION_HIJACK`                                                                                     | Restaura o `action` original do formulário.                                                        |
| `OVERLAY_DETECTED`                                                                                       | Remove o elemento sobreposto.                                                                      |
| `PIX_TAMPERED`, `UPI_TAMPERED`, `QR_TAMPERED`, `BOLETO_TAMPERED`, `CRYPTO_ADDRESS_SWAP` (texto alterado) | Reescreve o texto com o valor original capturado.                                                  |
| Recebedor fora da lista de confiáveis                                                                    | Troca o texto lido por `⚠︎` e marca o elemento com `data-proteside-blocked="untrusted_recipient"`. |
| `CLIPBOARD_HIJACK`                                                                                       | Regrava a área de transferência com o valor original.                                              |
| `SERVICE_WORKER_BLOCKED`                                                                                 | Remove o registro do service worker.                                                               |

Para um script indesejado, crie também uma regra de bloqueio em **Regras**. Detecções de envio de dados exigem ação
imediata a partir do alerta.

> **Atenção**
>
> No modo **Bloquear**, uma regra errada pode quebrar o checkout. Comece em **Monitorar**, revise os alertas por
> algumas semanas e teste o modo **Bloquear** em uma página de baixo tráfego antes de ativar em toda a loja.

## Pausa e modo desenvolvedor
O SDK fica pausado quando:

* o **Modo desenvolvedor** está ligado em **Proteção do pagamento → Como o SDK deve reagir → Opções para a equipe
  técnica**;
* a assinatura não está vigente ou a loja não está ativa.

Pausado, o SDK não executa proteções e a **Saúde do SDK** mostra **SDK pausado (modo desenvolvedor)**.

> **Regras inline continuam valendo no modo desenvolvedor**
>
> As regras gravadas no snippet continuam valendo com o modo desenvolvedor ligado: os scripts que casam com elas
> continuam bloqueados, mas sem nenhum evento no dashboard. Se precisar desativar um bloqueio durante a integração,
> remova a regra e recole o snippet.

## Canais
O canal de release (`stable` ou `latest`) é definido pela URL do `shield.js` no snippet. Veja
[Canais stable e latest](https://docs.proteside.com/pt-BR/docs/integration/install#canais-stable-e-latest).

## Próximos passos
* [Integridade de pagamento e Pix](https://docs.proteside.com/pt-BR/docs/integration/payment-integrity)
* [Eventos e detecções](https://docs.proteside.com/pt-BR/docs/integration/events)
* [Proteção do pagamento no dashboard](https://docs.proteside.com/pt-BR/docs/guide/settings/payment-protection)
