Proteside Docs

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.

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

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.

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>

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.

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.

Install the module from the Magento root:

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 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.

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 stores there is the official plugin @proteside/medusa. The source code, version history and downloadable package are in the public repository 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.

npm install @proteside/medusa

Register the plugin in medusa-config.ts:

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:

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>:

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 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.

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.
PlatformGuidance
ShopifyThe 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.
VTEXUse 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.
NuvemshopUse the checkout's custom scripts feature, if your plan offers it. Confirm with Nuvemshop support whether the code goes into the checkout's <head>.
YampiUse the checkout's custom scripts feature, if available. Confirm with Yampi support whether the code goes into the checkout's <head>.
WooCommerceUse the official plugin.
TrayUse the checkout's custom scripts feature, if available. Confirm with Tray support whether the code goes into the checkout's <head>.
WixUse 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>.
MedusaUse the official plugin.
Custom or headless checkoutUse 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

On this page