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.
<!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.
| Platform | Where to get it | Repository |
|---|---|---|
| WooCommerce | WordPress.org | proteside-woocommerce |
| Magento / Adobe Commerce | Latest release download | proteside-magento |
| OpenCart | Latest release download | proteside-opencart |
| PrestaShop | Latest release download | proteside-prestashop |
| Medusa | npm | 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.
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:flushEnable 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/medusaRegister the plugin in 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:migrateActivate 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>:
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:
- 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.
- Whether you can insert code into the checkout's
<head>, not just into the rest of the store. - 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. |
| 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. |
| 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.