# @moonbase.sh/storefront Embeddable Moonbase storefront widget for browser apps. This package wraps auth, cart, checkout, voucher redemption, product downloads, activation, and subscription management behind one client-side API. Learn more about our embedded storefront in our official docs: https://moonbase.sh/docs/storefronts/embedded/ ## Install ```bash pnpm add @moonbase.sh/storefront ``` ## Quick start ```ts import Moonbase, { MoonbaseEvent } from '@moonbase.sh/storefront' Moonbase.setup('https://demo.moonbase.sh', { toolbar: { enabled: true, location: 'top-right', }, }) Moonbase.on(MoonbaseEvent.CheckoutCompleted, ({ order }) => { console.log('Order completed', order.id) }) ``` `setup` should be run once, client-side. When you load the widget via the CDN script tag: ```html ``` …you can call `Moonbase.setup(...)`, `Moonbase.on(...)`, and any intent method from anywhere on the page — including inline ` ``` ```ts // Hand Moonbase the same id so it can forward commerce/auth events to fbq: Moonbase.setup('https://demo.moonbase.sh', { integrations: { metaPixel: { pixelId: '1234567890' } }, }) ``` The same pattern applies to GA4 (`gtag`), GTM (`dataLayer`), Klaviyo (`klaviyo`), and TikTok (`ttq`): install the vendor snippet, then pass the matching id. For Klaviyo, both the modern onsite object (`klaviyo.identify()` / `klaviyo.track()`) and the legacy `klaviyo.push([...])` queue are supported automatically. The `googleTagManager.containerId` is informational/reserved — GTM reads from `window.dataLayer` regardless of which container loaded it, so it isn't used at runtime. ### Consent Forwarding is unconditional: Moonbase forwards to whatever SDK global is present, and relies on **that SDK's own consent state** (e.g. Google Consent Mode v2, or your CMP gating `fbq`/`ttq`). To suppress forwarding entirely until consent is granted, omit the provider from `setup()` and add it once consent lands: ```ts onConsentGranted(() => Moonbase.configure({ integrations: { metaPixel: { pixelId: '1234567890' } } })) ``` `configure({ integrations })` can add, change, or remove providers at any time. Merge semantics apply per provider: pass a provider to add or update it, pass it as `undefined` (or `null`) to remove it, and omit it to leave it unchanged — so granting one provider after consent never disturbs the others. ```ts // Stop forwarding to Meta Pixel, leave every other provider running: Moonbase.configure({ integrations: { metaPixel: undefined } }) ``` ### 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. ### Data conventions Forwarded order `value` is the amount the customer pays — `total.due`, post-discount and **tax-inclusive** (no separate tax field is sent). Per-item prices are the net (post-discount) unit price. `checkout-initiated` is the one exception: an order has no settled total until billing details are entered, so its `value` is the cart's own post-discount total and excludes tax. `checkout-completed` events carry the order id as a dedup key (Meta `eventID`, TikTok `event_id`, GA4/GTM `transaction_id`) so a completion isn't double-counted. ### Event mapping | Moonbase event | Meta Pixel | GA4 | GTM (`dataLayer`) | Klaviyo | TikTok Pixel | | -------------------- | ----------------------- | -------------------- | -------------------- | ------------------------ | --------------------- | | `added-to-cart` | `AddToCart` | `add_to_cart` | `add_to_cart` | `Added to Cart` | `AddToCart` | | `checkout-initiated` | `InitiateCheckout` | `begin_checkout` | `begin_checkout` | `Started Checkout` | `InitiateCheckout` | | `checkout-completed` | `Purchase` | `purchase` | `purchase` | `Placed Order` | `CompletePayment` | | `signed-in` | advanced match | `login` + `user_id` | `login` | `identify` | `identify` | | `signed-up` | `CompleteRegistration` | `sign_up` + `user_id`| `sign_up` | `identify` | `CompleteRegistration`| | `signed-out` | — | clears `user_id` | `logout` | — | — | For any event not listed (or a provider that isn't built in), use `Moonbase.on(...)` and forward by hand.