Integration

Proteside is a client-side SDK that runs on your store's payment pages. It keeps an inventory of the scripts that run in your customer's browser, detects tampering (skimming, Pix key swaps, form hijacking, data exfiltration) and sends the evidence to the dashboard. This evidence supports the PCI DSS 4.0 controls, requirements 6.4.3 and 11.6.1.

This section covers installing the SDK on your checkout and how it behaves in the browser. To use the dashboard day to day, see the User guide.

How it worksCopy Anchor Link

You install it as a single block of code pasted into the checkout's <head>. Inside, it has two parts with different roles:

1. Bootstrapper (inline and synchronous). A small <script>, pasted directly into the HTML, that must be the first script in the <head>. It makes no network requests. It sets up observation points on fetch, XMLHttpRequest, navigator.sendBeacon, addEventListener, the clipboard, service workers and WebSocket. It also intercepts new <script src> insertions, so it can stop scripts your rules forbid before they enter the page. Everything that happens before the SDK loads is kept in memory.
2. The shield.js SDK (asynchronous, served from the CDN). Loaded from https://cdn.proteside.com/v1/shield.js with async, without blocking rendering. It reads the key from the data-key attribute, fetches the store's configuration, starts the detection modules and processes what the bootstrapper kept.
3. Remote configuration. On startup, the SDK fetches what you set in the dashboard from https://app.proteside.com/api/sdk/config: protection mode, rules, trusted recipients, expected iframe origins and fine-tuning settings. If the response doesn't arrive within 2 seconds, the SDK continues with its local defaults.
4. Event delivery. Detections and telemetry are sent in batches to https://app.proteside.com/api/sdk/events. The dashboard turns relevant events into alerts and updates the Scripts inventory and SDK Health.

What Proteside detectsCopy Anchor Link

• New or modified scripts after the page has loaded, classified as first-party, known third-party or unknown.
• Blocked scripts that match your rules, and Google Tag Manager containers that aren't on the allowed list.
• Keyloggers: scripts that start listening to keystrokes on card fields or other sensitive fields.
• Exfiltration: card numbers, CPF, CNPJ, email addresses or Pix keys sent to untrusted domains via fetch, XHR, beacon or image; WebSocket connections to unknown destinations.
• Payment tampering: swapping the Pix copy-and-paste code, a crypto address, a UPI VPA, the boleto bank or the amount; swapping content copied to the clipboard.
• Form and iframe hijacking: a change to a form's action, a swapped payment provider iframe, unexpected iframes and elements overlaid on payment fields.
• Unauthorized service workers.
• Security headers on the payment page (CSP, HSTS and others), to detect changes.

The full list, with severities, is in Events and detections.

What Proteside doesn't collectCopy Anchor Link

The SDK is designed not to carry payment data:

• it never reads values typed into form fields and never records keystrokes;
• it never sends card numbers, CVVs, Pix keys, copy-and-paste codes, crypto addresses or boleto digit lines;
• it never sends clipboard content, request bodies or script source code (only hashes, sizes and the names of patterns it found);
• it doesn't set cookies or write to localStorage.

There are a few points you should know about, such as the full page URL being sent. See Privacy and LGPD.

From the first pageview to the dashboardCopy Anchor Link

Here's what happens when a customer opens a checkout with the snippet installed:

1. The browser runs the bootstrapper (under 1 ms) and keeps loading the page as usual.
2. shield.js arrives from the CDN and fetches the store's configuration (up to 2 s).
3. The SDK sends a PAGEVIEW and starts calibration: for 30 seconds (adjustable from 10 to 120 s), it learns the scripts, the sensitive-field listeners and the legitimate network domains on that page.
4. Right away, the SDK sends the page's script inventory, with a content hash when the content is readable. Scripts the dashboard doesn't know yet show up in Scripts with the Needs review status.
5. Once calibration ends, any new script or suspicious behavior becomes a detection.
6. Events are sent in batches roughly every 5 seconds and when the customer leaves the page. The Proteside Active indicator at the top of the dashboard and the SDK Health page start reflecting real traffic.

Next stepsCopy Anchor Link