Settings
/
Overview
Last updated

Settings

The Settings section provides tools for managing shop configuration and locale preferences. The FairShare SDK uses a layered configuration system where API settings provide defaults that can be overwritten by your UI code.

What's Included

FunctionDescription
fetchSettingsFetch fresh settings from the API
getSettingsGet cached settings (no API call)
getOrFetchSettingsGet from cache or fetch if needed
updateLocaleSettingsUpdate language and country settings
lookupAffiliateLook up affiliate by various identifiers

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:

PropertyContents
shopname, primary_color, secondary_color, logo_url, icon_url, countries, languages
carttoken
scriptsArray of { id, src, data }
affiliatename, email, image_url, username, share_guid, external_id, fluid_rep_id
attributionUnion type: email, username, share_guid, fluid_rep_id, or external_id
// These settings come from your shop's API configuration
const settings = await window.FairShareSDK.fetchSettings();
console.log(settings.shop.name);           // Shop name
console.log(settings.shop.countries);      // Available countries
console.log(settings.affiliate?.name);     // Affiliate name
console.log(settings.attribution);         // Attribution data

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

Locale Detection Priority

The SDK automatically determines the user's locale using the following priority order:

┌─────────────────────────────────────────────────────────┐
│           1. Explicit User Setting (Highest)            │
│              (via updateLocaleSettings)                 │
├─────────────────────────────────────────────────────────┤
│              2. IP Geolocation                          │
│       (automatic detection on first visit)              │
├─────────────────────────────────────────────────────────┤
│           3. Company Default Locale                     │
│         (configured in shop settings)                   │
├─────────────────────────────────────────────────────────┤
│           4. Alphabetical Fallback (Lowest)             │
│        (first available country by ISO code)            │
└─────────────────────────────────────────────────────────┘

How It Works

  1. First Visit (No Stored Locale)

    • SDK calls the settings API without a locale
    • Server detects the user's country via IP geolocation
    • Returns locale combining shop's default language + detected country
    • Example: User in Canada → "en_CA"

  2. Subsequent Visits

    • SDK sends the stored locale to the server
    • Server uses the provided locale
    • Locale persists until explicitly changed

  3. User Changes Locale

    • Call updateLocaleSettings() to set explicit preference
    • This takes highest priority on all future requests

Example Flow

// First visit from Canada (no stored locale)
// → Server detects IP → Returns "en_CA"
// → SDK stores "en_CA"

// User browses site...
// → All requests use "en_CA"

// User manually changes to Mexico
await window.FairShareSDK.updateLocaleSettings({
  language: "es",
  country: "MX"
});
// → SDK stores "es_MX"
// → All future requests use "es_MX"

Important: Locale Updates Are Partial

When you update locale settings, only the properties you specify are changed.

// First visit from Canada (no stored locale)
// → Server detects IP → Returns "en_CA"
// → SDK stores "en_CA"

// User browses site...
// → All requests use "en_CA"

// User manually changes to Mexico
await window.FairShareSDK.updateLocaleSettings({
  language: "es",
  country: "MX"
});
// → SDK stores "es_MX"
// → All future requests use "es_MX"

Important: Locale Updates Are Partial

When you update locale settings, only the properties you specify are changed.

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

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

When to Use Each Approach

ScenarioRecommended Approach
Automatic locale detectionLet the SDK handle it (IP geolocation)
Default shop settingsConfigure in API/admin dashboard
Affiliate-specific overridesScript tag data-* attributes
User-selected preferencesUI code via updateLocaleSettings()
Dynamic runtime changesUI code via SDK functions
Previous page
Next page