# Installing by platform

> Where to paste the snippet on HTML, Next.js, Nuxt and WordPress, and how to use the official plugins for WooCommerce, Magento, OpenCart, PrestaShop and Medusa.

URL: https://docs.proteside.com/en/docs/integration/platforms

The dashboard generates a ready-to-use snippet for four platforms: **HTML**, **Next.js**, **Nuxt** and **WordPress**.
The rule is the same on all of them: the inline bootstrapper must be the first script in the `<head>`, with
`shield.js` right after it.

In the examples below, the bootstrapper's content is abbreviated. Always copy the full code from
**Settings → Pages & Domains**, which already includes your key, your channel and your rules.

## Platforms with a snippet in the dashboard
  **HTML**

Paste the block once, as the first item in the `<head>`, on every page with a checkout. Also use this tab for static
sites, React or Vue apps without a server framework (in `index.html`), and any platform that lets you edit the
checkout HTML.

```html title="checkout.html"
<!doctype html>
<html lang="en">
  <head>
    <!-- Proteside Start -->
    <!-- Place first in <head>, before GTM, Stripe.js, analytics, or any other scripts. -->
    <script>/* bootstrapper: full content copied from the dashboard */</script>
    <script async src="https://cdn.proteside.com/v1/shield.js"
            data-key="pk_live_YOUR_KEY"
            data-api="https://app.proteside.com/api/sdk"></script>
    <!-- Proteside End -->

    <meta charset="utf-8" />
    <title>Checkout · My Store</title>
    <!-- GTM, analytics and other scripts come after -->
  </head>
  <body>
    <!-- ... -->
  </body>
</html>
```

  **Next.js**

For the App Router, add both `<Script strategy="beforeInteractive">` tags inside the `<head>` of the root layout
    (`app/layout.tsx`). Don't use a plain `<script>`: Next.js reorders the tags, and the SDK would start before the
    bootstrapper.

    This is the block the dashboard generates:

    ```tsx title="Next.js snippet generated by the dashboard"
    
    
    
    
    import Script from 'next/script'

    <Script
      id="proteside-bootstrapper"
      strategy="beforeInteractive"
      dangerouslySetInnerHTML={{ __html: `/* bootstrapper: full content copied from the dashboard */` }}
    />
    <Script
      src="https://cdn.proteside.com/v1/shield.js"
      data-key="pk_live_YOUR_KEY"
      data-api="https://app.proteside.com/api/sdk"
      strategy="beforeInteractive"
    />
    
    ```

    The block mixes an `import` with JSX. Move the `import` to the top of the file and paste the `<Script>` tags inside
    the `<head>`:

    ```tsx title="app/layout.tsx"
    import Script from 'next/script'

    export default function RootLayout({ children }: { children: React.ReactNode }) {
      return (
        <html lang="en">
          <head>
            
            <Script
              id="proteside-bootstrapper"
              strategy="beforeInteractive"
              dangerouslySetInnerHTML={{ __html: `/* bootstrapper: full content copied from the dashboard */` }}
            />
            <Script
              src="https://cdn.proteside.com/v1/shield.js"
              data-key="pk_live_YOUR_KEY"
              data-api="https://app.proteside.com/api/sdk"
              strategy="beforeInteractive"
            />
            
          </head>
          <body>{children}</body>
        </html>
      )
    }
    ```

    If the store has inline rules, they go at the start of the `<Script id="proteside-bootstrapper">` content, with no extra
    tag. Older snippets had a third tag before it, `<Script id="proteside-inline">`: keep the order in which it appears or
    paste the snippet again.

    > **Check the order after publishing**
>
> Next.js injects its own scripts into the `<head>`, and the final order depends on the framework version. After
> publishing, open the checkout and run `Proteside.getStatus().installationOrderValid` in the console. If the result is
> `false`, the bootstrapper didn't end up first and coverage is partial. See
> [Troubleshooting](https://docs.proteside.com/en/docs/integration/troubleshooting#ordem-de-instalacao).

    Client-side route navigations don't reload the page. Call
    [`Proteside.pageChanged()`](https://docs.proteside.com/en/docs/integration/javascript-api#pagechangedpath) when the route changes inside the checkout.

  **Nuxt**

Put both entries at the start of `app.head.script`, in `nuxt.config.ts`, in this order (bootstrapper first). Then
    build and publish the site.

    ```ts title="Nuxt snippet generated by the dashboard"
    // Proteside Start — nuxt.config.ts → app.head.script (keep this order)
    {
      children: `/* bootstrapper: full content copied from the dashboard */`,
      tagPosition: 'head',
    },
    {
      src: 'https://cdn.proteside.com/v1/shield.js',
      async: true,
      'data-key': 'pk_live_YOUR_KEY',
      'data-api': 'https://app.proteside.com/api/sdk',
    }
    // Proteside End
    ```

    Here's how it looks in the file:

    ```ts title="nuxt.config.ts"
    export default defineNuxtConfig({
      app: {
        head: {
          script: [
            // Proteside Start — nuxt.config.ts → app.head.script (keep this order)
            {
              children: `/* bootstrapper: full content copied from the dashboard */`,
              tagPosition: 'head',
            },
            {
              src: 'https://cdn.proteside.com/v1/shield.js',
              async: true,
              'data-key': 'pk_live_YOUR_KEY',
              'data-api': 'https://app.proteside.com/api/sdk',
            },
            // Proteside End
            // your other scripts come after
          ],
        },
      },
    })
    ```

    > **Note**
>
> After publishing, view the source of the checkout page and confirm that the first `<script>` tag in the `<head>`
> contains the bootstrapper code. If your Nuxt version generates an empty tag, replace `children` with `innerHTML`.

  **WordPress**

On WooCommerce stores, prefer the [official plugin](#woocommerce). To install with code, add it to the
`functions.php` of a **child theme** or to a snippets plugin (such as Code Snippets), so theme updates don't wipe it
out.

```php title="functions.php"
<?php
// Proteside Start — functions.php (bootstrapper first, SDK second)
add_action('wp_head', function() {
  echo '<script>/* bootstrapper: full content copied from the dashboard */</script>';
}, 1);
add_action('wp_head', function() {
  echo '<script async src="https://cdn.proteside.com/v1/shield.js" data-key="pk_live_YOUR_KEY" data-api="https://app.proteside.com/api/sdk"></script>';
}, 2);
// Proteside End
```

Priorities 1 and 2 put Proteside at the start of `wp_head`. If the store has inline rules, they go at the
start of the bootstrapper's `echo`. Older snippets had a third action, with priority 0, for those rules.

After publishing:

* clear the cache of your caching and optimization plugins;
* exclude the snippet from the options that combine, minify, defer (`defer`) or delay JavaScript;
* check that the theme doesn't print a `<script>` in `header.php` before calling `wp_head()`, and that no plugin uses
  priority 0 or 1 on `wp_head`. In those cases, the bootstrapper doesn't end up first.

## Platforms with an official plugin
On these platforms, a Proteside plugin installs the snippet for you: you paste your SDK key in the store admin,
choose the pages, and the plugin checks your subscription on its own. Each plugin has a public repository with the
source code, the notes for each version and the downloadable package.

| Platform                 | Where to get it                                                                                  | Repository                                                                      |
| ------------------------ | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| WooCommerce              | [WordPress.org](https://wordpress.org/plugins/proteside-for-woocommerce/)                        | [proteside-woocommerce](https://github.com/proteside-app/proteside-woocommerce) |
| Magento / Adobe Commerce | [Latest release download](https://github.com/proteside-app/proteside-magento/releases/latest)    | [proteside-magento](https://github.com/proteside-app/proteside-magento)         |
| OpenCart                 | [Latest release download](https://github.com/proteside-app/proteside-opencart/releases/latest)   | [proteside-opencart](https://github.com/proteside-app/proteside-opencart)       |
| PrestaShop               | [Latest release download](https://github.com/proteside-app/proteside-prestashop/releases/latest) | [proteside-prestashop](https://github.com/proteside-app/proteside-prestashop)   |
| Medusa                   | [npm](https://www.npmjs.com/package/@proteside/medusa)                                           | [proteside-medusa](https://github.com/proteside-app/proteside-medusa)           |

The menus below follow each platform's admin in English. After installing any of them, open the checkout and run
`Proteside.getStatus()` in the browser console to check.

### WooCommerce
Requirements: WordPress 6.7 or newer, PHP 7.4 or newer and WooCommerce active.

  **Install the plugin.** In WordPress, open **Plugins → Add New Plugin**, search for **Proteside for WooCommerce**,
click **Install Now** and then **Activate**.

  **Paste your key.** Open **WooCommerce → Proteside**, paste your SDK key (**Settings → Pages & Domains** in the
Proteside dashboard) and click **Save changes**. The plugin shows the connection status right away.

  **Check the pages.** By default, the protection loads on the checkout, the order payment page and the order
confirmation page. Adjust them if needed and save.

If a theme or plugin prints scripts before `wp_head`, turn on **Strict first position (output buffering)** under
**Advanced**. Don't use the plugin and the code from the **WordPress** tab at the same time.

### Magento
Requirements: Magento Open Source or Adobe Commerce 2.4.4 to 2.4.9, with the Magento cron running.

  **Download the package** `proteside-module-checkout-<version>.zip` from the
[latest release](https://github.com/proteside-app/proteside-magento/releases/latest).

  **Install the module** from the Magento root:

```bash
mkdir -p app/code/Proteside/Checkout
# replace 1.0.2 with the version you downloaded
unzip proteside-module-checkout-1.0.2.zip -d app/code/Proteside/Checkout
bin/magento module:enable Proteside_Checkout
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush
```

  **Enable it and paste your key.** Open **Stores → Configuration → Security → Proteside**, set **Enabled** to **Yes**,
paste your SDK key and save. When you save, the module checks the status and flushes the page cache.

By default, the protection loads on the checkout and the order confirmation page. The module already adds the
Proteside domains to Magento's Content Security Policy.

### OpenCart
Requirements: OpenCart 3.0.2 to 3.0.5.1, or 4.0.2 or newer (including 4.1). The release has one package per version:
`proteside-opencart-3.ocmod.zip` for OpenCart 3 and `proteside.ocmod.zip` for OpenCart 4.

  **Upload the package** from the [latest release](https://github.com/proteside-app/proteside-opencart/releases/latest)
in **Extensions → Installer → Upload**. On OpenCart 4, keep the name `proteside.ocmod.zip` and click **Install** in
the installed list.

  **Install the module.** In **Extensions → Extensions**, choose **Modules**, find **Proteside checkout protection**,
click **Install** (+) and then **Edit** (pencil).

  **Paste your SDK key** and click **Save**. The page reloads with the status returned by Proteside.

You don't need to add the module to a layout in **Design → Layouts**, and the `proteside` event in **Extensions →
Events** must stay on: it is what inserts the protection.

### PrestaShop
Requirements: PrestaShop 1.7.6 or newer, including 8 and 9.

  **Download the package** `proteside-<version>.zip` from the
[latest release](https://github.com/proteside-app/proteside-prestashop/releases/latest).

  **Upload the module** in **Modules → Module Manager → Upload a module**.

  **Paste your key.** Click **Configure** on the **Proteside checkout protection** card, paste your SDK key and click
**Save changes**.

Keep **Strict first position** on: it puts the protection as the first item of the `<head>`.

### Medusa
For [Medusa](https://medusajs.com) stores there is the official plugin
[`@proteside/medusa`](https://www.npmjs.com/package/@proteside/medusa). The source code, version history and
downloadable package are in the public repository
[github.com/proteside-app/proteside-medusa](https://github.com/proteside-app/proteside-medusa).

Medusa is headless: the storefront is an app separate from the server. That's why the plugin has two parts. On the
Medusa server, it adds a **Settings → Proteside** screen to the admin, where you paste your key and choose the pages,
and it checks your subscription on its own. On the storefront, you add a component that prints Proteside in the
`<head>`.

Requirements: Medusa 2.22 or newer, Node.js 22 and access to the storefront's root layout `<head>`.

  **Install the plugin on the Medusa server.**

```bash
npm install @proteside/medusa
```

  **Register the plugin** in `medusa-config.ts`:

```ts title="medusa-config.ts"
module.exports = defineConfig({
  // ...
  plugins: [
    {
      resolve: '@proteside/medusa',
      options: {
        // optional: storefront URL, used when the admin field is empty
        storefrontUrl: 'https://mystore.com',
      },
    },
  ],
})
```

  **Run the migration** and restart Medusa:

```bash
npx medusa db:migrate
```

  **Activate it in the admin.** Open **Settings → Proteside**, paste your SDK key (**Settings → Pages & Domains** in
the Proteside dashboard) and save. The status turns **Active** when the subscription is active. By default, the
protection loads on the checkout and the order confirmation page.

  **Add the component to the storefront.** In Medusa's Next.js starter, copy the file
`storefront/nextjs/proteside.tsx` from the package into the storefront (for example, `src/lib/proteside.tsx`) and put
`<ProtesideScript />` as the first item of the root layout's `<head>`:

```tsx title="src/app/layout.tsx"
import { ProtesideScript } from '@lib/proteside'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <head>
        <ProtesideScript />
      </head>
      <body>{children}</body>
    </html>
  )
}
```

The component uses the `MEDUSA_BACKEND_URL` and `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` variables the starter already
has, and it follows route changes on its own, so you don't need to call `Proteside.pageChanged()`. It uses a plain
`<script>` tag on purpose: the plugin generates a single script, unlike the two-tag snippet in the **Next.js** tab. On
other storefronts, fetch the script on the server with `GET /store/proteside/snippet` (with the Medusa publishable key
in the `x-publishable-api-key` header) and print the `html` field as the first item of the `<head>`. Full
instructions are in the [repository](https://github.com/proteside-app/proteside-medusa) README.

> **Installation order warning on Next.js storefronts**
>
> Next.js always places its own scripts before any inline script in the `<head>`. So, on a Next.js storefront,
> `Proteside.getStatus().installationOrderValid` is `false` and the dashboard shows the installation order alert even
> with the plugin installed correctly. To stop getting this alert, open it in **Alerts** and choose **Stop warning
> for this store**.

To check, open the storefront checkout and run `Proteside.getStatus()` in the browser console: `initialized` must be
`true`. See also [Verify the installation](https://docs.proteside.com/en/docs/integration/verify).

## Other platforms
For the platforms below, you install the snippet from the **HTML** tab, pasted into the `<head>` of your checkout
pages. What varies from one platform to another is **whether**
and **where** it lets you edit that `<head>`.

Before installing, confirm three things with your platform:

1. **Which domain the checkout runs on.** Many platforms host the checkout on their own domain or subdomain. The
   snippet must be on that domain's pages.
2. **Whether you can insert code into the checkout's `<head>`**, not just into the rest of the store.
3. **Whether the code goes in as the first item in the `<head>`**, inline and not deferred. If the platform only lets
   you add scripts after its own, the SDK works with partial coverage and raises the installation order warning.

| Platform                    | Guidance                                                                                                                                                                                                                                                                     |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Shopify                     | The platform itself controls the checkout. Check with Shopify support whether your plan lets you insert code into the `<head>` of checkout pages. Pixels and scripts that run in an isolated environment (sandbox) can't see the checkout page and won't work for Proteside. |
| VTEX                        | Use the platform's checkout customization feature, if it allows code in the `<head>` of checkout pages. Confirm with VTEX support where the code is inserted.                                                                                                                |
| Nuvemshop                   | Use the checkout's custom scripts feature, if your plan offers it. Confirm with Nuvemshop support whether the code goes into the checkout's `<head>`.                                                                                                                        |
| Yampi                       | Use the checkout's custom scripts feature, if available. Confirm with Yampi support whether the code goes into the checkout's `<head>`.                                                                                                                                      |
| WooCommerce                 | Use the [official plugin](#woocommerce).                                                                                                                                                                                                                                     |
| Tray                        | Use the checkout's custom scripts feature, if available. Confirm with Tray support whether the code goes into the checkout's `<head>`.                                                                                                                                       |
| Wix                         | Use the site's custom code feature, if it can be applied to checkout pages. Confirm with Wix support whether the checkout accepts code in the `<head>`.                                                                                                                      |
| Medusa                      | Use the [official plugin](#medusa).                                                                                                                                                                                                                                          |
| Custom or headless checkout | Use the **HTML** tab (or **Next.js** / **Nuxt**) in your payment page template.                                                                                                                                                                                              |

If the platform doesn't allow code in the checkout's `<head>`, Proteside can't protect that page. In that case,
install the snippet on the pages you control and confirm with the platform how it meets PCI DSS 4.0 requirements
6.4.3 and 11.6.1 on its own pages.

## Google Tag Manager
Don't install Proteside through Google Tag Manager. GTM loads tags asynchronously, after its own container, so:

* the bootstrapper is no longer the first script and is no longer synchronous, which is exactly what the
  architecture requires;
* protection only has partial coverage;
* blocking unauthorized containers and tags stops working, because GTM itself would be the one loading Proteside.

If you use GTM, paste the Proteside snippet **before** the GTM snippet in the `<head>`. That way, tags GTM inserts via
JavaScript go through the bootstrapper and can be blocked by your rules and by the **Allowed GTM containers** list.

## Next steps
* [Verify the installation](https://docs.proteside.com/en/docs/integration/verify)
* [Configuration](https://docs.proteside.com/en/docs/integration/configuration)
* [Content Security Policy and headers](https://docs.proteside.com/en/docs/integration/csp)
