@moonbase.sh/storefront 3.14.0 → 3.16.0

package/README.md

@@ -706,6 +706,21 @@ const { payload } = await jwtVerify(token, jwks, {
 
 Don't read the widget's `localStorage` entry yourself: it holds the refresh token as well, which must never leave the browser.
 
+## Saving the customer's address
+
+`Moonbase.updateAddress(address)` saves the signed-in customer's address and resolves to the customer as saved. Their next checkout starts from it; a checkout they have already entered billing details in keeps those. It rejects when nobody is signed in, and for an address the store can't use: it needs a known country, a street address, a city or a region, and in the US a postal code.
+
+```ts
+const user = await Moonbase.updateAddress({
+  countryCode: 'AU',
+  streetAddress1: '1 George Street',
+  streetAddress2: null,
+  locality: 'Sydney',
+  region: 'NSW',
+  postCode: '2000',
+})
+```
+
 ## Integrations
 
 The widget can forward its commerce and auth events to common marketing/analytics SDKs without any extra glue code. Enable a provider by passing its config in `integrations`:
@@ -762,6 +777,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

@@ -1,4 +1,5 @@
 import { ActivationRequestFulfillmentType } from '@moonbase.sh/vue';
+import { Address } from '@moonbase.sh/vue';
 import { CartItem } from '@moonbase.sh/vue';
 import { CheckoutBackdropColor } from '@moonbase.sh/vue';
 import { CheckoutBackdropOpacity } from '@moonbase.sh/vue';
@@ -288,6 +289,7 @@ declare class MoonbaseImpl implements MoonbaseInstance {
     configure(options: DeepPartial<MoonbaseOptions>): void;
     on<TEvent extends MoonbaseEvent>(eventType: TEvent, callback: (event: MoonbaseEventArgs[TEvent]) => void): void;
     getAccessToken(): Promise<string | null>;
+    updateAddress(address: Address): Promise<User>;
     private handleLocationIntent;
     sign_in(parameters?: MoonbaseIntentArgs['sign_in']): void;
     sign_up(parameters?: MoonbaseIntentArgs['sign_up']): void;
@@ -330,6 +332,14 @@ export declare type MoonbaseInstance = MoonbaseInstanceIntents & {
      * account's public key, at `/api/key/jwks` on your Moonbase address.
      */
     getAccessToken: () => Promise<string | null>;
+    /**
+     * Saves the signed-in customer's address, which their next checkout starts from, and
+     * resolves to the customer as saved. A checkout they have already entered billing details
+     * in keeps those. Rejects when nobody is signed in, and for an address the store can't
+     * use: it needs a known country, a street address, a city or a region, and in the US a
+     * postal code.
+     */
+    updateAddress: (address: Address) => Promise<User>;
 };
 
 declare type MoonbaseInstanceIntents = {
@@ -655,6 +665,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. */