Skip to main content
Installing FairShare takes one script tag. Once the tag is on your page, the SDK bootstraps itself, resolves attribution, and makes the full JavaScript API available under window.FairShareSDK. Everything else — cart widgets, lead capture, media — activates as soon as you add the relevant HTML elements or call the API.
Building a Fluid theme? Your storefront already loads the SDK from a Global Embed that Fluid manages, so don’t add the script tag to your theme. See Common theme pitfalls. Add the script yourself only on sites Fluid doesn’t host.
Place the script tag inside your <head> element so attribution resolves before the rest of the page renders. This prevents a flash of un-attributed content and ensures cart widgets appear without delay.

​
Basic Installation

Add the following snippet to every page where you want FairShare to run. Replace your-shop-id with your company’s Fluid subdomain — acme for acme.fluid.app. Keep type="module": the script is an ES module and fails to load without it.
That’s the minimum required configuration. Keep id="fluid-cdn-script" on the tag — the SDK uses it to find its configuration.
Fluid-hosted storefronts already load the SDK through a global embed. Don’t add this tag to a Fluid theme — two copies can add items to the cart twice. Edit the embed instead. See FairShare SDK and the storefront.

​
Configuration Options

Customize SDK behavior by adding data-* attributes to the script tag. Only data-fluid-shop is required; all other attributes are optional.

​
Attribution Override

By default, FairShare reads attribution signals from the current URL and stored cookies. You can override this by setting one or more attribution attributes directly on the script tag. Use this pattern when:
  • You’re building a rep-specific landing page and want to hard-code credit to a known rep.
  • Your site runs outside the Fluid ecosystem and you’re passing rep identity from your own user session.
  • You need to test attribution for a specific rep without using a share link.
FairShare uses the first of these attributes that is present on the tag, in this order: share-guid → fluid-rep-id → email → username → external-id. It doesn’t check that the rep exists, so an attribute with an unknown value doesn’t fall through to the next one. The browser remembers an override: clear the site’s data after you remove one. Using data-share-guid (the older name for data-username — Fluid matches the value against rep usernames):
Using a numeric rep ID:
Using an email address:
Using a username:
Using an external ID (when you manage rep identifiers in your own system):

​
Enable real-time cart updates

Set data-realtime-enabled="true" to receive cart updates over Action Cable, Fluid’s WebSocket transport. Updates to the same cart from another tab, a droplet, or a support agent can reach your page without a refresh. It is also how a cart that Fluid fills in the background reaches the page. See Carts that fill in the background. The loader tag that Fluid injects on every storefront always sets this attribute, so a Fluid theme needs no change. Set it yourself only when you install the SDK by hand outside a Fluid theme. Without it, the attribute defaults to off.
The connection opens when the SDK has a cart token. If a visitor has no cart yet, the SDK connects when they create or adopt one. Switching to another cart reopens the connection for that cart. The SDK manages reconnection and queues incoming updates while cart operations are in flight.

​
Use a custom WebSocket endpoint

The default endpoint is wss://websockets.fluid.app/cable. For a non-production environment, add data-cable-url with that environment’s WebSocket endpoint:
Use an endpoint configured to serve Fluid cart updates. Setting data-fluid-api-base-url does not change the WebSocket endpoint; configure data-cable-url separately when you use a different host.

​
Migrate from Pusher

Replace data-pusher-enabled="true" with data-realtime-enabled="true" on your existing loader tag. The SDK still recognizes the Pusher option, but Fluid no longer publishes updates to Pusher, so that option alone does not deliver cart updates. If both options are enabled, Action Cable takes precedence.
Your loaded SDK bundle must include Action Cable support. On a tag you wrote, add data-realtime-enabled="true"; updating the SDK bundle alone does not enable real-time sync. The tag that Fluid manages already includes it.

​
Custom API Endpoint

Enterprise accounts may need to route SDK traffic to a dedicated API host. Set data-fluid-api-base-url to your custom endpoint and all SDK requests will use it instead of the default Fluid API.

​
Debug Mode

Set data-debug="true" to enable verbose logging in the browser console. Debug mode prints attribution resolution steps, API request details, and widget lifecycle events. Disable it before going to production.

​
Manual Initialization (SPA / React)

In single-page applications the <head> script tag may execute before your framework has mounted the component tree. If you need to initialize FairShare after a dynamic render, call initializeFluid() directly:
To enable real-time cart sync during manual initialization, pass realtimeEnabled: true. Fluid storefronts need no setting, because their loader always enables it. Use cableUrl only when you need to override the default WebSocket endpoint:
initializeFluid() initializes the full SDK, including cart and widget features. initializeFairshare() is a lower-level asynchronous initializer for tracking and attribution only. Use initializeFluid() for storefront integrations unless you intentionally need only the tracking layer. Call initializeFluid() once per session — typically in your root component’s mount lifecycle hook (useEffect with an empty dependency array in React, onMounted in Vue, ngOnInit in Angular). The script tag must still be present in the document, but you can omit the data-fluid-shop attribute and provide it here instead. To reset the SDK state — for example, when a user logs out — call:
reset() clears stored SDK data, the local cart, real-time connections, and initialization state. If you only need to clear tracking and attribution data, do not use resetFairshare() as a partial reset. FairShare and Fluid share browser storage, so that method also removes stored cart, settings, and authentication data.