# Configuration

> Snippet attributes, remote configuration, monitor and block modes, pausing and channels.

URL: https://docs.proteside.com/en/docs/integration/configuration

Almost all SDK configuration happens in the dashboard and reaches the browser through the remote configuration. The
snippet only carries the store's key and, when there are any, the inline rules. This page shows where each setting
comes from and what it actually does on the checkout.

## Snippet attributes
`shield.js` reads the `data-*` attributes on its own `<script>` tag:

- `data-key` (`string`), required: The store's SDK key (starts with pk_live_). Without it, the SDK doesn't initialize and shows no warning.
- `data-api` (`string`), default: `https://app.proteside.com/api/sdk`: Base address of the Proteside API, including the /api/sdk path. The dashboard always fills in the default value; don't change it.

There are no other attributes. The protection mode and the channel are **not** set by attribute: the mode comes from
the dashboard, and the channel is the `shield.js` URL itself. The `data-safe-url` attribute, from older versions of the
snippet, is ignored.

## Remote configuration
On startup, the SDK fetches the store's configuration from `app.proteside.com`. When the layers disagree, this order
of precedence applies:

1. **Remote configuration** (what's saved in the dashboard);
2. **Snippet** (`data-*` attributes and inline rules);
3. **SDK defaults.**

An invalid key, an error or a network outage never breaks the page. Changes reach the checkout within a few minutes.
To check a change, wait a few minutes and reload the checkout.

### What comes from the dashboard
Most of it is in **Settings → Payment protection**, organized in four steps:

*Image: Step 1 of the Payment protection screen: how the check works, recipients seen at checkout, trusted recipients and manual registration*

| Step and dashboard setting                                                                  | Effect on the SDK                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Who can receive your money** → **Trusted recipients**                                     | The store's Pix keys, accounts, crypto wallets and boleto banks. See [Payment integrity and Pix](https://docs.proteside.com/en/docs/integration/payment-integrity).                                                                      |
| **How the SDK should react** → **Protection mode**                                          | **Monitor** or **Block**. See below.                                                                                                                                                            |
| **How the SDK should react** → **Options for the technical team** → **Developer mode**      | Pauses the SDK. See [Pause and developer mode](#pausa-e-modo-desenvolvedor).                                                                                                                    |
| **How the SDK should react** → **Options for the technical team** → **SDK release channel** | Informational only for the SDK. The effective channel is the URL pasted in the snippet. See [Channels](https://docs.proteside.com/en/docs/integration/install#canais-stable-e-latest).                                                   |
| **What is normal at your checkout** → **Expected iframe origins**                           | Hosts of legitimate payment iframes. With the list filled in, the SDK alerts on provider iframes outside it, iframes overlaid on the expected ones and typeable card fields outside the iframe. |
| **What is normal at your checkout** → **Allowed GTM containers**                            | With the list filled in, containers outside it are stopped. See the warning below.                                                                                                              |
| **What is normal at your checkout** → **Allowed service workers (advanced)**                | With the list filled in, service workers outside it are reported and, in **Block** mode, removed.                                                                                               |
| **Detected payment methods**                                                                | Read-only. The SDK recognizes the page's payment methods on its own; there's nothing to select.                                                                                                 |
| **Extra fields to watch** → **Extra selectors (optional)**                                  | Sensitive fields with non-standard names. The selectors add to the automatic detection; nothing is turned off.                                                                                  |

The installation order warning is no longer configured on this screen. The `INSTALLATION_ORDER_WARNING` alert itself
offers **Stop warning for this store**. See [Troubleshooting](https://docs.proteside.com/en/docs/integration/troubleshooting#ordem-de-instalacao).

The rules in **Rules** (block or allow by **Domain** or **Script URL**) also arrive through the remote configuration.

> **Blocking by address**
>
> In-browser blocking applies to scripts loaded by address; inline scripts must be removed at the source. To stop a
> script, use a **Domain** or **Script URL** rule.

### Sensitive fields
The SDK recognizes the most common card fields; mark others with `data-proteside-sensitive` or configure them in
Payment protection.

To include a field of your own without touching the dashboard, mark it with the `data-proteside-sensitive`
attribute:

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

In the dashboard, use **Extra fields to watch** → **Extra selectors (optional)**, with one CSS selector per line.
Whatever you add is added to the automatic detection: the list doesn't replace the fields the SDK already
recognizes.

## Monitor mode and block mode
The mode is chosen in **Payment protection → How the SDK should react → Protection mode** and reaches the SDK through
the remote configuration.

### What happens in either mode
> **Rules and the GTM list also block in Monitor mode**
>
> **Blocking rules** (by domain or URL) and the **Allowed GTM containers** list block scripts **in both modes**. The
> mode only decides the SDK's automatic reactions to what has no rule. If you only want to observe, don't create
> blocking rules and leave the GTM list empty.

* A script that matches a blocking rule is stopped before it enters the page, and the SDK sends `SCRIPT_BLOCKED`.
  Scripts written in the page's HTML must be removed at the source.
* With the GTM list filled in, containers outside it are stopped. The SDK sends `GTM_CONTAINER_BLOCKED`.
* An **Allow** rule that matches the script overrides the blocking rules.
* `cdn.proteside.com` and `app.proteside.com` are never blocked.

> **The GTM list can also stop GA4 and Google Ads**
>
> The list only accepts IDs in the `GTM-XXXXXXX` format. With it filled in, Google Analytics 4 (`G-…`) and Google Ads
> (`AW-…`) tags can also be stopped, including when fired by GTM itself, and there's no way to add those IDs to the
> list. Before turning the list on, check whether the store uses those tags and test the checkout.

### What changes in Block mode
On top of alerting, the SDK tries to neutralize the tampering:

| Detection                                                                                              | Action in **Block** mode                                                                                       |
| ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- |
| `SCRIPT_INJECTION` of an unknown script                                                                | Removes the script tag after detecting it.                                                                     |
| `FORM_ACTION_HIJACK`                                                                                   | Restores the form's original `action`.                                                                         |
| `OVERLAY_DETECTED`                                                                                     | Removes the overlaid element.                                                                                  |
| `PIX_TAMPERED`, `UPI_TAMPERED`, `QR_TAMPERED`, `BOLETO_TAMPERED`, `CRYPTO_ADDRESS_SWAP` (altered text) | Rewrites the text with the original captured value.                                                            |
| Recipient not on the trusted list                                                                      | Replaces the text it read with `⚠︎` and marks the element with `data-proteside-blocked="untrusted_recipient"`. |
| `CLIPBOARD_HIJACK`                                                                                     | Writes the original value back to the clipboard.                                                               |
| `SERVICE_WORKER_BLOCKED`                                                                               | Unregisters the service worker.                                                                                |

For an unwanted script, also create a blocking rule in **Rules**. Data-sending detections require immediate action
from the alert.

> **Warning**
>
> In **Block** mode, a wrong rule can break the checkout. Start in **Monitor**, review alerts for a few weeks and test
> **Block** mode on a low-traffic page before turning it on for the whole store.

## Pause and developer mode
The SDK is paused when:

* **Developer mode** is on in **Payment protection → How the SDK should react → Options for the technical team**;
* the subscription isn't current or the store isn't active.

While paused, the SDK doesn't run protections, and **SDK Health** shows **SDK paused (developer mode)**.

> **Inline rules still apply in developer mode**
>
> The rules written into the snippet still apply with developer mode on: scripts that match them stay blocked, but
> without any event in the dashboard. If you need to turn off a block during integration, remove the rule and paste the
> snippet again.

## Channels
The release channel (`stable` or `latest`) is set by the `shield.js` URL in the snippet. See
[Stable and latest channels](https://docs.proteside.com/en/docs/integration/install#canais-stable-e-latest).

## Next steps
* [Payment integrity and Pix](https://docs.proteside.com/en/docs/integration/payment-integrity)
* [Events and detections](https://docs.proteside.com/en/docs/integration/events)
* [Payment protection in the dashboard](https://docs.proteside.com/en/docs/guide/settings/payment-protection)
