Benson install guide for developers

Someone asked you to add Benson to their store. Here's the short version, with links to the detail.

The snippet#

The store owner's snippet (with their site key) is in the email that sent you here, or in Benson under Settings → Install:

<script async src="https://cdn.trybenson.com/benson.js" data-site="pk_live_YOUR_SITE_KEY"></script>

Put it in <head> on every page. It's async, about 2.5KB compressed, loads its modules when the browser is idle, and never throws into the page.

Allow it in your CSP#

If the site sends a Content-Security-Policy, add:

script-src https://cdn.trybenson.com;
connect-src https://api.trybenson.com;

More in Content Security Policy.

Consent#

Benson reads the consent signal your site already has (Shopify, IAB TCF, Google Consent Mode) or waits for you to call Benson.consent(). Details and every storage key it can write are in Consent and storage.

SPAs, headless and custom carts#

• Call Benson.page() after client-side navigation.
• Call Benson.setCart({ currency, totalMinor, items, codes }) whenever the cart changes, so stretch goals and targeting know the basket.
• On custom checkouts, register how codes are applied with Benson.registerApplyHandler().

Reacting to coupon-extension shoppers#

• Benson.state() says whether this session has a coupon extension, and Benson.on("ext_detected") hears every detection, including ones from before you subscribed. See Extension shoppers.
• For CSS-only changes, turn on the page flag: <html data-benson-ext="honey">.
• In Google Tag Manager, the benson_state event carries the answer on every page. See dataLayer and GA4 events.
• On WooCommerce, the plugin adds PHP hooks such as benson_coupon_denied. See WooCommerce developer hooks.

The full reference is in the JavaScript API.

Verify#

Load any page with ?benson_debug=1 to see what Benson is doing in the console. The site's setup wizard turns green on the first page view.