Setup and Meta Tags

The Storefront SDK has no configuration file. It reads everything it needs (shop name, API and CDN endpoints, tracking values) from <meta> tags in the page <head>, then StorefrontSDK.Setup() builds the global window.$storefront object. This page explains both ways to load the SDK, every meta tag, the Setup() options, and what happens behind the scenes.

Loading the SDK

With npm (any framework)

npm install @selldone/sdk-storefront

import { StorefrontSDK } from "@selldone/sdk-storefront";

// ━━━ Storefront SDK (xapi,...) ━━━
StorefrontSDK.Setup(); // Set up the Shop SDK.

The package ships ES module (dist/index.esm.js) and CommonJS (dist/index.cjs) builds with type definitions. Besides StorefrontSDK, it exports namespace classes such as XapiProduct, XapiBasket, XapiUser, XapiShop, XapiCoupon, XapiOffer, XapiLottery, XapiVendor, XapiArticle, XapiAuthEmail, XapiAuthSMS and StorefrontDatabase, together with typed …Types namespaces (for example XapiProductListTypes, XapiProductGetTypes, XapiAuthSMSVerifyOtpTypes), so you can type your code:

import type { XapiProductListTypes } from "@selldone/sdk-storefront";

const options: XapiProductListTypes.IOptions = { sort: "cheapest", available: true };

With a `<script>` tag (CDN)

<script src="https://cdn.jsdelivr.net/npm/@selldone/sdk-storefront@{version}/dist/bundle.min.js"></script>
<script>
    // Use the global variable StorefrontSDK
    const sdk = storefront.StorefrontSDK;
    sdk.Setup()
</script>

Replace {version} with the version you want (see npm). Other options:

<!-- Always the latest version (jsDelivr alias) -->
<script src="https://cdn.jsdelivr.net/npm/@selldone/sdk-storefront@latest/dist/bundle.min.js"></script>

<!-- unpkg -->
<script src="https://unpkg.com/@selldone/sdk-storefront/dist/bundle.min.js"></script>

<!-- Pin to a major version (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/@selldone/sdk-storefront@1/dist/bundle.min.js"></script>

Warning

Using @latest can break your app when a new version introduces breaking changes. If stability matters, pin a fixed version or a major version such as @1.

The bundle is an IIFE that includes Selldone Core, so one script tag is enough. Everything is exposed under the global name storefront (for example storefront.StorefrontSDK).

Meta tags

Add these to <head> before Setup() runs:

<!-- 🏬 Shop Name -->
<meta name="shop-name" content="toysworld">

<!-- 🎗 Prefix address of app Ex./my-shop-path -->
<meta name="shop-prefix-address" content="">

<!-- 📰 Shop custom page -->
<meta name="custom-home" content="shop">


<!-- ―――――――――――――――― Start ❯ Business OS Configuration ―――――――――――――――― -->

<!-- 🪁 Service Origin -->
<meta content="https://selldone.com" name="service-url">


<!-- 🎯 APIs -->
<meta content="https://gapi.selldone.com" name="selldone-gapi">
<meta content="https://xapi.selldone.com" name="selldone-xapi">
<meta content="https://iframe.selldone.com" name="selldone-iframe">
<meta content="https://capi.selldone.com" name="selldone-capi">

<!-- 🌍 CDNs -->
<meta content="https://selldone.com/cdn-shop-images-1" name="selldone-cdn-images">
<meta content="https://selldone.com/cdn-shop-jsons-1" name="selldone-cdn-jsons">
<meta content="https://selldone.com/cdn-videos" name="selldone-cdn-videos">
<meta content="https://selldone.com/cdn-shop-temp-files" name="selldone-cdn-temp-files">
<meta content="https://selldone.com/cdn-ar" name="selldone-cdn-ar">
<meta content="https://selldone.com/cdn-id" name="selldone-cdn-id">
<meta content="true" name="storage-redirect">
<meta content="https://cdn.selldone.com" name="storage-redirect-host">
<meta content="true" name="storage-redirect-thumbnails">

Shop tags

Tag	Required	Purpose
`shop-name`	Yes (unless passed to `Setup()`)	Shop handle used in every XAPI call (`/shops/@{shop}/…`). `Setup()` throws if it is missing.
`shop-prefix-address`	No (default `""`)	Path prefix when the storefront is served under a sub-path, for example `/my-shop-path`. Exposed as `window.$storefront.prefix_url` and used as the cookie path of the access token.
`custom-home`	No	What the home route shows. Exposed as `window.$storefront.home`. The official Storefront understands `shop` (product listing), `blog`, `avocado`, `hyper`, `community`, `map`, or a Page Builder page ID.

Platform tags (read by Selldone Core)

Tag	Required	Purpose
`service-url`	Yes	Main Selldone origin. Selldone Core throws `The service url is not defined in [service-url] meta tag!` without it.
`selldone-xapi`	Yes	Base URL of the storefront API. All `window.$storefront` calls use it.
`selldone-gapi`	Recommended	Base URL of the general API used by `window.GAPI` / `window.$selldone.gapi`.
`selldone-iframe`	Yes	Embed/AR origin used by `window.URLS`; Selldone Core throws without it.
`selldone-capi`	For community features	Base URL of the community API used by the Community SDK.
`selldone-cdn-images`, `selldone-cdn-jsons`, `selldone-cdn-ar`	Yes	CDN bases for images, JSON/Lottie files and AR/3D models used by `window.CDN`.
`selldone-cdn-videos`, `selldone-cdn-temp-files`, `selldone-cdn-id`	No	Videos, temporary files and ID-based icons. A console warning is printed if missing.
`storage-redirect`, `storage-redirect-host`, `storage-redirect-thumbnails`	No	When `true`, image URLs point directly to cloud storage at `storage-redirect-host`.

Optional tags

These are usually injected by Selldone when your Layout is hosted on the platform:

Tag	Effect
`csrf-token`	Sent as the `X-CSRF-TOKEN` header. Without it the console shows `CSRF token not found!` (harmless for most custom front ends).
`default-currency`	Fallback currency code when the customer has not selected one. If absent, `USD` is used.
`campaign_id`, `link_id`, `email_id`, `affiliate_id`	Marketing attribution, sent as `S-Campaign-Id`, `S-Link-Id`, `S-Email-Id`, `S-Affiliate-Id` headers.
`temp_access_key`	Sent as `S-Temp-Access` (lets admins preview inactive shops).
`http-referer`	Original referrer, sent as `S-Referrer`.

Configuring without meta tags

Every value is read with SetupService.GetMetaValue(name) from Selldone Core. If no <meta> tag with that name exists, it falls back to window.selldone_config[name]. This is useful for embedded widgets where you cannot edit <head>:

<script>
  window.selldone_config = {
    "shop-name": "toysworld",
    "service-url": "https://selldone.com",
    "selldone-xapi": "https://xapi.selldone.com",
    "selldone-gapi": "https://gapi.selldone.com",
    "selldone-iframe": "https://iframe.selldone.com",
    "selldone-cdn-images": "https://selldone.com/cdn-shop-images-1",
    "selldone-cdn-jsons": "https://selldone.com/cdn-shop-jsons-1",
    "selldone-cdn-ar": "https://selldone.com/cdn-ar",
  };
</script>
<script src="https://cdn.jsdelivr.net/npm/@selldone/sdk-storefront@1/dist/bundle.min.js"></script>
<script>
  storefront.StorefrontSDK.Setup();
</script>

`StorefrontSDK.Setup()`

StorefrontSDK.Setup(
  _shop_name?: string,
  options: { cookie_key_access_token?: string } = { cookie_key_access_token: "access_token" },
): void

Argument	Description
`_shop_name`	Optional. Overrides the `shop-name` meta tag. Required when the SDK runs inside a Backoffice SDK environment (when `window.$backoffice` exists), for example to preview storefront data in an admin dashboard.
`options.cookie_key_access_token`	Name of the cookie that holds the customer access token. Default `access_token`.

What `Setup()` does

Prints the SDK banner and runs Selldone Core's SelldoneCore.Setup() if window.CDN does not exist yet.
Reads shop-name, shop-prefix-address and custom-home.
Configures window.axios default headers (see below) and the customer Authorization header.
Creates window.CDN, window.XAPI (the XAPI URL builder) and window.URLS.
Creates window.$storefront with all namespaces, bound to your shop name.
Restores the customer's selected currency from local storage.

In a Backoffice environment, steps 3 and the CDN/URLS part of step 4 are skipped because the Backoffice SDK already configured them.

`window.$storefront` contents

Property	Type	Description
`name`	`string`	Shop name.
`prefix_url`	`string`	Path prefix, for example `''` or `'/@pajuhaan'`.
`local_storage_path`	`string`	Local storage base path, `shop/@{name}/`.
`home`	`Shop.Home \| null`	Value of `custom-home`.
`USER`	`User \| null`	Current customer, set by `user.fetchMyInfo()` and cleared by `auth.logout()`.
`currency`	`ICurrency`	Selected currency. Assign an `ICurrency` or a code such as `"EUR"` to change it; it is saved per shop.
`database`	`StorefrontDatabase`	Local storage helpers: `coupon`, `currency`, `language`.
`products`, `basket`, `auth`, `user`, `shop`, `coupon`, `offer`, `cashback`, `lottery`, `vendor`, `avocado`, `article`	API namespaces	See the API Reference.
`routes`	`StorefrontRoutesName`	Route names used by the official Storefront router (from `@selldone/core-js/enums/route/StorefrontRoutesName`).

Request headers

Setup() sets these on window.axios.defaults.headers.common, so every SDK request carries them:

Header	Source
`Authorization: Bearer …`	`window.SelldoneUser.access_token` if the server preloaded it, otherwise the `access_token` cookie.
`X-CSRF-TOKEN`	`csrf-token` meta tag.
`S-Referrer`	Original referrer (or the landing URL when it carries `utm_source`), remembered for 24 hours.
`S-Location`	Current `window.location.href` at start-up.
`S-Temp-Access`	`temp_access_key` meta tag.
`S-Pops`	Popups the customer has already seen (local storage).
`S-Campaign-Id`, `S-Link-Id`, `S-Email-Id`, `S-Affiliate-Id`	Attribution meta tags.
`S-Guest`	Guest code from local storage, used for guest baskets. See Basket and Checkout.

window.SelldoneUser is an optional object { access_token, expires_in, refresh_token? } that a server-rendered page can set before Setup() to sign the customer in. The SDK then also writes the token to the access-token cookie.

Next steps

Getting Started
Authentication: put a token in place after login.
API Reference
Selldone Core wiki: SetupService, CDN, URLS and GAPI in depth.

_{Selldone® Business OS · Open-source ecosystem · storefront-sdk repository · Report an issue · Security}

Storefront SDK

Guides

Ecosystem

Links

Navigation Menu

Repository navigation

Setup and Meta Tags

Setup and Meta Tags

Loading the SDK

With npm (any framework)

With a `<script>` tag (CDN)

Meta tags

Shop tags

Platform tags (read by Selldone Core)

Optional tags

Configuring without meta tags

`StorefrontSDK.Setup()`

What `Setup()` does

`window.$storefront` contents

Request headers

Next steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Storefront SDK

Clone this wiki locally

Setup and Meta Tags

Setup and Meta Tags

Loading the SDK

With npm (any framework)

With a <script> tag (CDN)

Meta tags

Shop tags

Platform tags (read by Selldone Core)

Optional tags

Configuring without meta tags

StorefrontSDK.Setup()

What Setup() does

window.$storefront contents

Request headers

Next steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Storefront SDK

Clone this wiki locally

With a `<script>` tag (CDN)

`StorefrontSDK.Setup()`

What `Setup()` does

`window.$storefront` contents