Install WebDecoy on BigCommerce

BigCommerce has no WebDecoy app. You install the same browser detection script that works on any website, using BigCommerce’s Script Manager. A hidden decoy link goes in your theme instead, because Script Manager only accepts scripts.

Applies to

BigCommerce stores on a Stencil theme, and Catalyst storefronts that render Script Manager scripts. Blueprint (legacy) themes and other headless storefronts are not covered here: on those, add the line to your storefront’s shared page layout as described in the browser detection script guide.

Before you begin

• A Stencil theme or a Catalyst storefront. BigCommerce’s Script Manager article does not list a plan requirement, but it states that Script Manager is “only available to stores using Stencil themes”. Catalyst storefronts pick up Script Manager scripts as well: “After you save a script in Script Manager, Catalyst picks it up and includes it on your storefront at runtime” (BigCommerce: Manually installing scripts in Catalyst).
• Control panel access to Storefront settings.
• A WebDecoy account with this site added. Create a free account and add the store using the address your shoppers visit (for example https://www.example.com).

1. Copy your site’s line from WebDecoy

In the WebDecoy dashboard setup checklist, open Install the detection script and choose Copy. If the checklist is closed, open Detection Scripts for the selected site and choose Copy snippet. The line looks like this, with your own IDs:

<script
  async
  src="https://cdn.webdecoy.com/bot-detection/v1/bot-detection.min.js"
  data-aid="your-property-uuid"
  data-sid="your-scanner-uuid">
</script>

Always paste the copied line. data-aid is the site (property) ID and data-sid is the detection script ID; a hand-built line with the wrong ID can load fine and file its reports somewhere you are not looking.

2. Add it with Script Manager

These steps follow BigCommerce: Using Script Manager.

1. In the BigCommerce control panel, go to Storefront, then Script Manager, and create a script.
2. Script name: WebDecoy.
3. Placement: the page header (head), not the footer.
4. Location: Storefront pages. BigCommerce defines this as “all pages, except for checkout or order confirmation pages”.
5. Script category: choose the category that matches your privacy policy (Essential, Functional, Analytics, or Targeting and advertising). If your store uses BigCommerce’s cookie consent, scripts in non-essential categories wait for the shopper’s consent, so shoppers who decline are not observed.
6. Script type: enter the script code directly rather than linking a URL, and paste the WebDecoy line. Its data-aid and data-sid attributes only survive when you paste the whole tag.
7. Save.

Keep the script off checkout. BigCommerce asks for an integrity hash on payment pages, and WebDecoy updates the script in place at its v1 address, so a pinned hash would stop matching after an update.

Catalyst

Use Script Manager as above; Catalyst renders it without code changes. BigCommerce’s Scripts API documentation notes that Catalyst versions before 1.1 do not render scripts added through the Scripts API, so update an older Catalyst storefront first. You can also render the line from your Catalyst code with the Next.js Script component, as in the React and Next.js example, but BigCommerce points out that scripts added that way bypass its consent management.

3. Add a hidden decoy link (optional)

A decoy link is a URL that people never see and link-following crawlers do. When a client requests it, WebDecoy’s decoy server records the hit, whether or not that client runs JavaScript.

Script Manager entries must be scripts, so a plain link does not belong there. Put it in your theme’s footer instead.

1. In WebDecoy, open Decoys, choose Create Decoy, keep Honeypot Link and the shared domain, and set the action to Log while you test.
2. From the decoy’s menu, choose Copy URL.
3. In BigCommerce, open your theme’s files with Edit Theme Files. BigCommerce only allows this on a copied or uploaded theme: “You cannot edit the files of a base theme from the marketplace”, and a copy “do[es] not receive updates released to the original theme” (BigCommerce: Stencil themes).
4. Open templates/components/common/footer.html (the usual footer template in Stencil themes; your theme may differ), paste this line just before the closing tag of the footer, using your decoy URL, and save and apply the theme:

<a href="https://abc12345.d.webdecoy.com/admin/backup.zip" style="display:none" aria-hidden="true" tabindex="-1" rel="nofollow">Admin</a>

On Catalyst, add the same line to your storefront’s footer component in code.

If you would rather not copy your theme, skip this step. The detection script works without it.

To prove the decoy works, open its URL once yourself and find the record in Detections, as described in Decoy links. That is your own setup check, not an attack.

4. Verify the install

1. Open a storefront page in a browser. In developer tools, open Network, reload, and find bot-detection.min.js. It must return 200.
2. In the WebDecoy dashboard setup checklist, enter the page address in the install verifier and choose Check my page. WebDecoy fetches the page from outside your browser and tells you whether this site’s tag is there.
3. Open Sensors. After a page loads in a browser, the Detection Script row moves to Running, nothing automated seen or Reporting.

A browser script does not run for curl, so the WebDecoy-Test/1.0 user agent cannot prove this install. To prove the detection pipeline end to end, use Send a test detection on the dashboard. See Verify your installation for what each status means.

What this covers, and what it does not

• Covered: shoppers and clients whose browsers run JavaScript on storefront pages, including headless browsers, browser automation, AI browser agents and AI browser extensions, plus LLM referrals.
• Not covered by the script: crawlers that fetch HTML without running JavaScript, such as Googlebot’s crawl pass, GPTBot, ClaudeBot, CCBot and curl. They only show up if they follow the hidden decoy link. To see every request you need an edge sensor such as the Cloudflare edge sensor, which requires your domain’s traffic to pass through Cloudflare. Check BigCommerce’s own domain documentation before proxying a store domain.
• No order review. WebDecoy has no BigCommerce app, so it cannot read, tag or flag orders, and it does not see or block checkout. Detections appear in the WebDecoy dashboard only.
• No blocking from the script. The browser script detects and reports; it does not refuse requests. See Response actions for what you can do with detections.

Read Detection coverage for the full comparison.

Remove

Delete the WebDecoy entry in Storefront, then Script Manager, and remove the decoy line from your theme if you added one. Reporting stops on the next page load.