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.
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 the shop identifier from your Fluid dashboard.
That’s the minimum required configuration. The id="fluid-cdn-script" attribute must be present — the SDK uses it to read configuration at runtime.
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 resolves the first signal that matches a known rep and ignores the rest, following this priority order: share-guid → fluid-rep-id → email → username → external-id.
Using a share GUID (recommended for rep-specific share links):
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):
Enabling Real-Time Updates
Add data-pusher-enabled="true" to receive instant cart updates over a WebSocket connection. Without this attribute, cart state refreshes only on explicit API calls. With it, any change to the cart — whether triggered by this page or another tab — propagates immediately.
This is especially useful on cart pages or checkout flows where stale quantity counts would cause a poor experience.
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:
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. 