# Integration

> Learn how the Proteside SDK works on your checkout before you install it.

URL: https://docs.proteside.com/en/docs/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](https://docs.proteside.com/en/docs/guide). If you're still evaluating the product, start with
[How Proteside works](https://proteside.com/en/how-it-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:

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. The bootstrapper starts observing the page right
   away, before any other script, and stops scripts your rules forbid before they enter the page.
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 and starts the detection modules.
3. **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.
4. **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](https://docs.proteside.com/en/docs/integration/events).

## 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](https://docs.proteside.com/en/docs/integration/privacy).

## From the first pageview to the dashboard
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.
3. 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**.
4. Scripts the dashboard doesn't know yet show up in **Scripts** with the **Needs review** status.
5. From then on, any new script or suspicious behavior becomes a detection.
6. 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.

> **Note**
>
> The decision on each script in the inventory (authorize or block) is yours, on the [Scripts](https://docs.proteside.com/en/docs/guide/scripts)
> page.

## Next steps
- [Installing the snippet](https://docs.proteside.com/en/docs/integration/install): Where to get the snippet and where to paste it.
- [Installing by platform](https://docs.proteside.com/en/docs/integration/platforms): HTML, Next.js, Nuxt, WordPress and other platforms.
- [Verify the installation](https://docs.proteside.com/en/docs/integration/verify): Confirm the SDK is active.
- [Configuration](https://docs.proteside.com/en/docs/integration/configuration): Attributes, remote configuration and protection modes.
- [Payment integrity and Pix](https://docs.proteside.com/en/docs/integration/payment-integrity): Trusted recipients and payment validation.
- [JavaScript API](https://docs.proteside.com/en/docs/integration/javascript-api): Methods on window.Proteside.
- [Events and detections](https://docs.proteside.com/en/docs/integration/events): Event types, severity and alerts.
- [CSP and headers](https://docs.proteside.com/en/docs/integration/csp): Content Security Policy and how it relates to PCI DSS.
- [Privacy and LGPD](https://docs.proteside.com/en/docs/integration/privacy): What is collected and what never is.
- [Performance and compatibility](https://docs.proteside.com/en/docs/integration/performance): Size, loading and browsers.
- [Proteside badge](https://docs.proteside.com/en/docs/integration/badge): Optional static badge for your checkout.
- [Troubleshooting](https://docs.proteside.com/en/docs/integration/troubleshooting): Common errors and how to fix them.
