Configuration
Snippet attributes, remote configuration, monitor and block modes, pausing and channels.
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:
Prop
Type
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:
- Remote configuration (what's saved in the dashboard);
- Snippet (
data-*attributes and inline rules); - 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:

| 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. |
| 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. |
| 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. |
| 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.
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:
<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.comandapp.proteside.comare 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.
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.