Integration
Learn how the Proteside SDK works on your checkout before you install it.
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. If you're still evaluating the product, start with How Proteside works.
How it works
You install it as a single block of code pasted into the checkout's <head>. Inside, it has two parts with different
roles:
- 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. The bootstrapper starts observing the page right away, before any other script, and stops scripts your rules forbid before they enter the page. - The
shield.jsSDK (asynchronous, served from the CDN). Loaded fromhttps://cdn.proteside.com/v1/shield.jswithasync, without blocking rendering. It reads the key from thedata-keyattribute, fetches the store's configuration and starts the detection modules. - Remote configuration. On startup, the SDK fetches what you set in the dashboard from
app.proteside.com: protection mode, rules, trusted recipients, expected iframe origins and fine-tuning settings. Changes reach the checkout within a few minutes. - Event delivery. Detections and telemetry are sent in small batches to
app.proteside.com. The dashboard turns relevant events into alerts and updates the Scripts inventory and SDK Health.
Why two parts?
A script loaded with async runs after other scripts on the page. Only an inline, synchronous snippet placed before
all of them guarantees full coverage from the start of the page load. That's why you should never replace the
bootstrapper with an external <script src>.
What Proteside detects
- 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: a script starts capturing what is typed into a sensitive field.
- Exfiltration: sensitive customer data is sent to an untrusted destination.
- 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 collect
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 dashboard
Here's what happens when a customer opens a checkout with the snippet installed:
- The browser runs the bootstrapper (under 1 ms) and keeps loading the page as usual.
shield.jsarrives from the CDN and fetches the store's configuration.- The SDK sends a
PAGEVIEW. Right after the page loads, the SDK establishes the page baseline. Scripts present at that moment go into the inventory and need your review in Scripts. - Scripts the dashboard doesn't know yet show up in Scripts with the Needs review status.
- From then on, any new script or suspicious behavior becomes a detection.
- Events are sent in small batches 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.
The decision on each script in the inventory (authorize or block) is yours, on the Scripts page.
Next steps
Installing the snippet
Where to get the snippet and where to paste it.
Installing by platform
HTML, Next.js, Nuxt, WordPress and other platforms.
Verify the installation
Confirm the SDK is active.
Configuration
Attributes, remote configuration and protection modes.
Payment integrity and Pix
Trusted recipients and payment validation.
JavaScript API
Methods on window.Proteside.
Events and detections
Event types, severity and alerts.
CSP and headers
Content Security Policy and how it relates to PCI DSS.
Privacy and LGPD
What is collected and what never is.
Performance and compatibility
Size, loading and browsers.
Proteside badge
Optional static badge for your checkout.
Troubleshooting
Common errors and how to fix them.