Proteside Docs

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:

  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:

Step 1 of the Payment protection screen: how the check works, recipients seen at checkout, trusted recipients and manual registration
Step and dashboard settingEffect on the SDK
Who can receive your money → Trusted recipientsThe store's Pix keys, accounts, crypto wallets and boleto banks. See Payment integrity and Pix.
How the SDK should react → Protection modeMonitor or Block. See below.
How the SDK should react → Options for the technical team → Developer modePauses the SDK. See Pause and developer mode.
How the SDK should react → Options for the technical team → SDK release channelInformational only for the SDK. The effective channel is the URL pasted in the snippet. See Channels.
What is normal at your checkout → Expected iframe originsHosts 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 containersWith 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 methodsRead-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.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:

DetectionAction in Block mode
SCRIPT_INJECTION of an unknown scriptRemoves the script tag after detecting it.
FORM_ACTION_HIJACKRestores the form's original action.
OVERLAY_DETECTEDRemoves 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 listReplaces the text it read with ⚠︎ and marks the element with data-proteside-blocked="untrusted_recipient".
CLIPBOARD_HIJACKWrites the original value back to the clipboard.
SERVICE_WORKER_BLOCKEDUnregisters 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.

Next steps

On this page