@moonbase.sh/storefront 3.14.0 → 3.15.0

package/README.md

@@ -762,6 +762,21 @@ onConsentGranted(() => Moonbase.configure({ integrations: { metaPixel: { pixelId
 Moonbase.configure({ integrations: { metaPixel: undefined } })
 ```
 
+### Attribution
+
+The widget reads how a visitor arrived: the UTM tags and the referring site, and the ad click IDs Google Ads, Meta, Microsoft Advertising and TikTok add to their links (`gclid`, `gbraid`, `wbraid`, `fbclid`, `msclkid`, `ttclid`). It sends them with the cart, checkout and sign-up, so campaign revenue, UTM-targeted prices and traffic types work.
+
+A click ID identifies the visitor's click, so the widget keeps one, and records the arrival on a cart as the page loads (so a visitor who comes back later to buy is still put down to it), only with the visitor's consent to marketing cookies. Without it, it keeps only which platform the click came from, and the arrival for the tab only.
+
+Until your page says anything, the widget follows the store's setting in Moonbase, Account settings > Storefront > "Features" > "Ad and campaign tracking": "Ask where the law requires it" tracks visitors outside the EEA, the United Kingdom and Switzerland (by where Moonbase locates the visit) and waits for consent elsewhere, "Only with cookie consent" always waits, and "Always" never asks. Whatever your cookie banner reports wins over the setting:
+
+```ts
+onConsentGranted(() => Moonbase.configure({ attribution: { consent: true } }))
+onConsentWithdrawn(() => Moonbase.configure({ attribution: { consent: false } }))
+```
+
+Whether a setting fits your business is for your own legal advice; a business based in the EU may owe consent to every visitor.
+
 ### Identity
 
 `signed-in` / `signed-up` forward an identify call when an email/id is available (Meta advanced match, GA4 `user_id`, Klaviyo identify, TikTok identify). On `signed-out`, Moonbase clears what each SDK supports (GA4 `user_id` is reset, GTM gets a `logout` push); Meta, TikTok, and Klaviyo expose no per-user logout, so their profiles persist for the session.

package/dist/moonbase.d.ts

@@ -655,6 +655,18 @@ export declare interface MoonbaseOptions {
      * `dataLayer`, `klaviyo`, `ttq`). Pass a provider's config to turn it on.
      */
     integrations: IntegrationsConfig;
+    attribution: {
+        /**
+         * Whether the visitor has agreed to marketing cookies, the category your cookie banner files
+         * ad tracking under. `true` keeps the ad click IDs (`gclid`, `fbclid` and the rest) and
+         * remembers the arrival beyond the visit; `false` records only the UTM tags, referring site
+         * and the ad platform a click came from, for the visit. Left out (the default), the widget
+         * follows the store's setting in Moonbase (Account settings > Storefront > "Features"):
+         * always, per country, or only with cookie consent. Set it with `Moonbase.configure()` when
+         * the banner reports the visitor's choice.
+         */
+        consent: boolean | undefined;
+    };
 }
 
 /** Which surface a promotion was rendered on. */