Settings

The FairShare SDK uses a layered configuration system where API settings provide defaults that can be overwritten by your UI code.

How Settings Work

┌─────────────────────────────────────────────────────────┐
│                    Your UI Code                         │
│         (highest priority - overrides everything)       │
├─────────────────────────────────────────────────────────┤
│                   Script Tag Attributes                 │
│            (data-fluid-shop, data-share-guid, etc.)     │
├─────────────────────────────────────────────────────────┤
│                    API Settings                         │
│             (defaults from your shop config)            │
└─────────────────────────────────────────────────────────┘

1. API Settings (Base Defaults)

When the SDK initializes, it fetches your shop's default configuration from the API. This includes:

Default language and country
Currency settings
Shop branding and display options
Available payment methods

// These settings come from your shop's API configuration
const settings = await window.FairShareSDK.fetchSettings();
console.log(settings.language);  // e.g., "en" (API default)
console.log(settings.country);   // e.g., "US" (API default)

2. Script Tag Overrides

Attributes on the SDK script tag can override API defaults:

<script
  id="fluid-cdn-script"
  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
  data-fluid-shop="your-shop-id"
  data-share-guid="specific-affiliate-id"
></script>

3. UI Code Overrides (Highest Priority)

Your JavaScript code has the highest priority and overwrites any previous settings:

// This overrides whatever the API returned
await window.FairShareSDK.updateLocaleSettings({
  language: "es",
  country: "MX"
});

// Now the SDK uses Spanish/Mexico regardless of API defaults

Important: Settings Are Overwritten, Not Merged

When you update settings via UI code, they replace the API values—they don't merge with them.

// API returns: { language: "en", country: "US", currency: "USD" }

// Your code updates:
await window.FairShareSDK.updateLocaleSettings({
  country: "CA"
});

// Result: country is now "CA", language stays "en"
// (language wasn't overwritten because you didn't specify it)

When to Use Each Approach

Scenario	Recommended Approach
Default shop settings	Configure in API/admin dashboard
Affiliate-specific overrides	Script tag `data-*` attributes
User-selected preferences	UI code via `updateLocaleSettings()`
Dynamic runtime changes	UI code via SDK functions

Settings Functions

Function	Description
fetchSettings	Fetch fresh settings from the API
getSettings	Get cached settings (no API call)
getOrFetchSettings	Get from cache or fetch if needed
updateLocaleSettings	Override language/country settings