# Instalação do snippet

> Copie o snippet do dashboard e cole como primeiro script do head das páginas de pagamento.

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

A instalação é um bloco de código que você copia do dashboard e cola no `<head>` das páginas de checkout. Não há
pacote npm nem app de loja: o mesmo snippet funciona em qualquer site em que você controle o HTML do checkout.

## Onde obter o snippet
O snippet fica em **Configurações → Páginas e Domínios**, no card **Instalação do SDK**:

* **Chave do SDK:** a chave da loja, que começa com `pk_live_`. É uma chave
  **pública**: ela vai no HTML da loja e só identifica a loja para o SDK.
* **Snippet:** o bloco pronto, já com a sua chave, o canal de release e as regras de bloqueio ativas. Há uma aba para
  cada plataforma: **HTML**, **Next.js**, **Nuxt** e **WordPress**.

*Imagem: O card Instalação do SDK mostra a chave e o snippet pronto para cada plataforma.*

O assistente de criação da loja também mostra o snippet, no passo de instalação. Aquele snippet sai sempre no canal
`stable` e sem as suas regras. Se você já configurou regras ou containers do Google Tag Manager, copie o snippet de
**Páginas e Domínios**.

## Instalar
### Abra Páginas e Domínios
No dashboard, vá em **Configurações → Páginas e Domínios**.

### Copie o snippet da sua plataforma
Escolha a aba **HTML**, **Next.js**, **Nuxt** ou **WordPress** e clique em **Copiar**. Para outras plataformas, use a
aba **HTML** e siga [Instalação por plataforma](https://docs.proteside.com/pt-BR/docs/integration/platforms).

### Cole como primeiro item do head
Cole o bloco inteiro logo depois da abertura do `<head>`, **antes** do Google Tag Manager, do Stripe.js, de analytics
e de qualquer outro script, em todas as páginas de checkout e pagamento.

### Publique e abra o checkout
Publique a alteração e abra a página de checkout no navegador. Depois, siga
[Verificar a instalação](https://docs.proteside.com/pt-BR/docs/integration/verify).

## O que tem no snippet
Este é o formato do snippet HTML gerado pelo dashboard. O conteúdo do bootstrapper foi abreviado aqui: ele tem cerca
de 4,3 KB de JavaScript minificado e muda entre versões. Copie sempre o bloco completo do dashboard.

```html title="Snippet HTML (canal stable)"
<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>/* bootstrapper: conteúdo completo copiado do dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_SUA_CHAVE"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->
```

| Parte                                | Função                                                                          |
| ------------------------------------ | ------------------------------------------------------------------------------- |
| `<script>` inline                    | O bootstrapper. Executa na hora, sem rede, e começa a observar a página.        |
| `<script async src=".../shield.js">` | O SDK. Carrega da CDN sem bloquear a página.                                    |
| `data-key`                           | A chave do SDK da loja. Obrigatória.                                            |
| `data-api`                           | O endereço da API do Proteside. O dashboard sempre preenche com o valor padrão. |

Os comentários dentro do snippet ficam em inglês em qualquer idioma do dashboard. É o comportamento normal.

### Snippet com regras inline
Se a loja tem regras de bloqueio ativas por domínio ou por URL, ou uma lista de containers do Google Tag Manager
permitidos, o dashboard grava essa configuração no início do próprio `<script>` do bootstrapper:

```html title="Snippet HTML com configuração inline"
<!-- Proteside Start -->
<!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
<script>/* bootstrapper com as regras inline: conteúdo completo copiado do dashboard */</script>
<script async src="https://cdn.proteside.com/v1/shield.js"
        data-key="pk_live_SUA_CHAVE"
        data-api="https://app.proteside.com/api/sdk"></script>
<!-- Proteside End -->
```

Esse trecho permite que o bootstrapper bloqueie scripts desde o primeiro byte da página, sem esperar a configuração
remota.

> **As regras inline ficam congeladas no HTML**
>
> A configuração inline guarda as regras do momento em que você copiou o snippet. Depois que o SDK inicia,
> a configuração remota passa a valer, mas até lá a página usa a versão colada. Uma regra removida no dashboard
> continua bloqueando nesse intervalo, e uma regra nova só bloqueia desde o primeiro byte depois que você recolar o
> snippet. Recole o snippet sempre que mudar regras de bloqueio ou containers do Google Tag Manager.

> **Não altere o snippet**
>
> * Não separe o bootstrapper do `shield.js` nem inverta a ordem.
> * Não troque o bootstrapper inline por um `<script src>` externo. Ele precisa executar de forma síncrona.
> * Não acrescente `async`, `defer` ou `type="module"`. Com `type="module"`, o SDK não inicializa.
> * Exclua o snippet de plugins de otimização que combinam, adiam ou carregam JavaScript de forma assíncrona.

## Por que o primeiro script do head
O snippet deve ser o primeiro script do `<head>` para cobertura completa.

Se houver qualquer script antes do snippet, o SDK marca a instalação como fora de ordem: envia o evento
`INSTALLATION_ORDER_WARNING`, que vira alerta no dashboard, e `Proteside.getStatus().installationOrderValid` fica
`false`. A proteção continua, mas com cobertura parcial. Para corrigir, mova o snippet para o topo do `<head>` e
publique de novo. Veja [Solução de problemas](https://docs.proteside.com/pt-BR/docs/integration/troubleshooting#ordem-de-instalacao).

Para bloquear um script escrito no HTML da página, remova a tag do HTML ou do tema. Scripts inseridos depois,
inclusive tags disparadas pelo Google Tag Manager, são barrados pelas suas regras antes de executar.

> **Nota**
>
> Snippets antigos traziam a configuração inline numa tag `<script>` separada, antes do bootstrapper. Se você usa um
> snippet antigo, copie o snippet atual em **Páginas e Domínios** e substitua o bloco inteiro.

## Em quais páginas instalar
Instale o snippet nas páginas em que o cliente informa ou recebe dados de pagamento:

* o checkout, incluindo as etapas de entrega e pagamento, quando forem páginas separadas;
* as páginas que exibem o QR code ou o código Pix copia e cola, o boleto ou o endereço cripto;
* a página de confirmação do pedido, se você aceita cartão. O SDK usa essa página para confirmar o pagamento com
  cartão.

Se o checkout é uma aplicação de página única (SPA), instale o snippet uma vez no HTML base e avise o SDK sobre as
trocas de rota com [`Proteside.pageChanged()`](https://docs.proteside.com/pt-BR/docs/integration/javascript-api#pagechangedpath).

### Instalar no site inteiro
É possível colar o snippet no layout global do site. Saiba o que muda:

* O SDK roda igual em todas as páginas em que estiver. Não há configuração por página que chegue ao navegador.
* Todas as páginas aparecem em **Páginas e Domínios** e entram no inventário de **Scripts**, o que aumenta o volume
  de scripts para revisar.
* Cada pageview faz as requisições extras do SDK (configuração, eventos e uma leitura dos headers da própria página).
  Veja [Desempenho e compatibilidade](https://docs.proteside.com/pt-BR/docs/integration/performance).
* Enquanto a loja não tiver páginas de pagamento cadastradas, **todas** as pageviews com o SDK contam como pageviews de
  páginas de pagamento no uso do plano. As páginas de pagamento são cadastradas pela [API](https://docs.proteside.com/pt-BR/docs/api), não pelo
  dashboard.

Para o PCI DSS 4.0, requisitos 6.4.3 e 11.6.1, o que importa são as páginas de pagamento. Prefira instalar só nelas.

## Canais stable e latest
O canal de release define qual build do `shield.js` o snippet carrega. Ele é escolhido em
**Configurações → Proteção do pagamento → Como o SDK deve reagir → Opções para a equipe técnica → Canal de release
do SDK**.

| Canal             | URL do `shield.js`                              | Quando é atualizado    |
| ----------------- | ----------------------------------------------- | ---------------------- |
| `stable` (padrão) | `https://cdn.proteside.com/v1/shield.js`        | a cada versão validada |
| `latest`          | `https://cdn.proteside.com/v1/latest/shield.js` | a cada publicação      |

> **Trocar o canal exige recolar o snippet**
>
> A tela de Proteção do pagamento diz que não é preciso reinstalar ao trocar o canal. Mas a URL do `shield.js` está
> escrita no snippet: o que já está colado continua carregando o canal antigo. Depois de trocar o canal, copie o
> snippet de novo em **Páginas e Domínios** e publique. Quando a loja usa `latest`, o snippet mostra o selo
> **canal latest**.

O `shield.js` se atualiza sozinho pela CDN. O bootstrapper, por ser inline, só muda quando você recola o snippet.

## Trocar a chave do SDK
Se precisar de uma chave nova, use **Trocar chave** em **Páginas e Domínios** e digite `TROCAR` para confirmar. Só
proprietários e administradores conseguem concluir a troca. A chave antiga continua funcionando por **24 horas**.
Nesse prazo, cole o snippet atualizado em todas as páginas: depois dele, a chave antiga deixa de ser aceita e os
eventos dessas páginas se perdem sem aviso.

## Próximos passos
* [Instalação por plataforma](https://docs.proteside.com/pt-BR/docs/integration/platforms)
* [Verificar a instalação](https://docs.proteside.com/pt-BR/docs/integration/verify)
* [Configuração](https://docs.proteside.com/pt-BR/docs/integration/configuration)
