Backend-Driven Configuration

The Frak SDK supports dynamic configuration resolved from the backend. When your application initializes, the SDK fetches your merchant configuration from the Frak backend based on your domain. This means you can manage branding, translations, component settings, and placements directly from the business dashboard without redeploying your application.

How It Works

1. SDK Initialization — When the SDK starts, it calls the Frak backend’s resolve endpoint with your domain.
2. Merchant Resolution — The backend identifies your merchant account and returns the associated configuration.
3. Config Merging — The resolved backend config is merged with your local SDK config. Backend values take priority over local values.
4. Reactive Updates — Components automatically re-render when the backend configuration is resolved.

Your Website                    Frak Backend
    |                               |
    |  GET /resolve?domain=...      |
    |------------------------------>|
    |                               |
    |  { merchantId, sdkConfig }    |
    |<------------------------------|
    |                               |
    | Components update reactively  |
    |                               |

Configuration Priority

The SDK merges configuration from multiple sources. When the same setting exists at multiple levels, the highest-priority source wins:

1. Backend config (highest priority) — Set in the business dashboard
2. SDK static config — Passed in your FrakWalletSdkConfig object
3. Defaults — Built-in SDK defaults

This means you can set sensible defaults in your code and override them from the dashboard without touching your codebase.

Resolved Configuration

The backend returns the following fields when available:

Field	Description
name	Your application display name
logoUrl	Logo URL displayed in modals and components
homepageLink	Link to your homepage (used in some components)
currency	Display currency ("eur", "usd", "gbp")
lang	Language override ("en", "fr")
hidden	When true, all SDK components are hidden
css	Global CSS applied to modals and components
translations	Global translation overrides
placements	Named placement configurations (see Placements)
components	Global component defaults

Controlling Loading Behavior

By default, the SDK waits for the backend configuration to be resolved before rendering components. This ensures components display the correct branding and settings from the start.

You can control this behavior with the waitForBackendConfig option:

import type { FrakWalletSdkConfig } from '@frak-labs/core-sdk';

const config: FrakWalletSdkConfig = {
  metadata: {
    name: "My App",
  },
  // When true (default): components show a loading spinner until backend config is resolved
  // When false: components render immediately with local config / HTML attributes
  waitForBackendConfig: true,
};

Tip

Keep waitForBackendConfig: true (the default) if you rely on backend-managed settings like translations, custom CSS, or placements. Set it to false if you provide all configuration locally and want instant rendering.

Caching

The SDK caches the resolved configuration in localStorage with a 30-second TTL using a stale-while-revalidate strategy:

• Fresh cache (< 30 seconds): The cached config is used immediately, no network request.
• Stale cache (> 30 seconds): The cached config is used immediately for fast rendering, while a background fetch updates the cache.
• No cache: A network request is made and components wait for the response (or render immediately if waitForBackendConfig is false).

The cache is scoped per domain and language, so different subdomains or language settings maintain separate caches.

Managing Backend Configuration

Backend-driven configuration is managed from the business dashboard. Navigate to your merchant’s settings to configure:

• Branding — Name, logo, homepage link
• Display — Language, currency, visibility toggle
• Styling — Custom CSS for modals and components
• Translations — Override default text for any SDK component
• Placements — Create named configurations for different sections of your site (see Placements)

Changes made in the dashboard take effect on your website within 30 seconds (the cache TTL), without requiring any code changes or redeployment.