Configuration

Proper configuration is crucial for the Wallet SDK to function correctly in your application. This guide will walk you through the configuration options and how to set them up.

Configuration Object

The Wallet SDK uses a configuration object to set up its behavior. Here’s the structure of the FrakWalletSdkConfig object:

TypeScript

type Currency = "eur" | "usd" | "gbp";
type Language = "fr" | "en";
// biome-ignore lint/correctness/noUnusedVariables: Documentation snippet for user reference
type FrakWalletSdkConfig = Readonly<{
    /**
     * The Frak wallet url
     * @defaultValue "https://wallet.frak.id"
     */
    walletUrl?: string;
    /**
     * Some metadata about your implementation of the Frak SDK
     */
    metadata: {
        /**
         * Your application name (will be displayed in a few modals and in SSO)
         */
        name?: string;
        /**
         * Your merchant ID from the Frak dashboard (UUID format)
         * Used for referral tracking and analytics
         * If not provided, will be auto-fetched from the backend using your domain
         */
        merchantId?: string;
        /**
         * Language to display in the modal
         * If undefined, will default to the browser language
         */
        lang?: Language;
        /**
         * The currency to display in the modal
         * @defaultValue `"eur"`
         */
        currency?: Currency;
        /**
         * The logo URL that will be displayed in a few components
         */
        logoUrl?: string;
        /**
         * The homepage link that could be displayed in a few components
         */
        homepageLink?: string;
    };
    /**
     * Some customization for the modal
     */
    customizations?: {
        /**
         * Custom CSS styles to apply to the modals and components
         */
        css?: `${string}.css`;
        /**
         * Custom i18n configuration for the modal
         *  See [i18next json format](https://www.i18next.com/misc/json-format#i18next-json-v4)
         *
         * Available context variables
         *  - `{{ productName }}` : The name of your website (`metadata.name`)
         *  - `{{ productOrigin }}` : The origin url of your website
         *  - `{{ estimatedReward }}` : The estimated reward for the user
         *
         * Can be a single language config or a multi-language config
         *
         * @example
         * // Multi-language config
         * {
         *  fr: {
         *      "sdk.modal.title": "Titre de modal",
         *      "sdk.modal.description": "Description avec {{ estimatedReward }} de gains",
         *  },
         *  en: {
         *      "sdk.modal.title": "Modal title",
         *  }
         * }
         *
         * @example
         * // Single-language config
         * {
         *      "sdk.modal.title": "Modal title",
         *      "sdk.modal.description": "Description with {{ estimatedReward }} of earnings",
         * }
         */
        i18n?:
            | Record<Language, { [key: string]: string }>
            | { [key: string]: string };
    };
    /**
     * The domain name of your application
     * @defaultValue window.location.host
     */
    domain?: string;
    /**
     * Wait for backend config before rendering components.
     * When true (default), components show a spinner until backend config is resolved.
     * When false, components render immediately with SDK static config / HTML attributes.
     * @defaultValue true
     */
    waitForBackendConfig?: boolean;
    /**
     * Default attribution params (UTM / via / ref) appended to outbound sharing URLs.
     * Per-call `displaySharingPage` overrides win, then backend config, then this default.
     * `utmContent` is intentionally excluded (it is per-content, never a merchant-wide default).
     */
    attribution?: {
        utmSource?: string;
        utmMedium?: string;
        utmCampaign?: string;
        utmTerm?: string;
        via?: string;
        ref?: string;
    };
    /**
     * Preload specific UI views inside the listener iframe for better UX.
     * @defaultValue ["sharing"]
     */
    preload?: ("modal" | "sharing")[];
}>;

JavaScript

/**
 * @typedef {Object} FrakWalletSdkConfig
 * @property {string} [walletUrl] - The URL of the Frak Wallet service
 * @property {Object} metadata - Metadata about your application
 * @property {string} [metadata.name] - The name of your application
 * @property {string} [metadata.merchantId] - Your merchant ID (UUID) from the Frak dashboard
 * @property {string} [metadata.lang] - The default language ("en" | "fr")
 * @property {string} [metadata.currency] - The default currency ("eur" | "usd" | "gbp")
 * @property {string} [metadata.logoUrl] - Logo URL displayed in modals and components
 * @property {string} [metadata.homepageLink] - Link to your homepage
 * @property {Object} [customizations] - Customization options
 * @property {string} [customizations.css] - URL to a CSS file for styling
 * @property {Object} [customizations.i18n] - Translation overrides for SDK components
 * @property {string} [domain] - The domain of your application
 * @property {boolean} [waitForBackendConfig] - Wait for backend config before rendering (default: true)
 * @property {Object} [attribution] - Default attribution params (UTM / via / ref) appended to outbound sharing URLs
 * @property {string[]} [preload] - UI views to preload in the listener iframe ("modal" | "sharing", default: ["sharing"])
 */

Let’s break down each property:

walletUrl (optional)

This is the URL of the Frak Wallet service. Use one of the following values:

• Production: "https://wallet.frak.id"
• Development: "https://wallet-dev.frak.id"

Tip

This property is optional. If not provided, it defaults to the production URL ("https://wallet.frak.id").

metadata

This object contains metadata about your application:

• name (optional): The name of your application. Displayed in modals and SSO pages.
• merchantId (optional): Your merchant ID from the Frak dashboard (UUID format). Used for referral tracking and analytics. If not provided, it will be auto-fetched from the backend using your domain.
• lang (optional): The display language ("en" or "fr"). Defaults to the browser language.
• currency (optional): The display currency ("eur", "usd", or "gbp"). Defaults to "eur".
• logoUrl (optional): Logo URL displayed in modals and a few components.
• homepageLink (optional): Link to your homepage, used in SSO pages and some components.

customizations

This object contains customization options for the displayed Frak elements:

• css (optional): A URL to a CSS file (must end with .css) that styles the Frak Wallet interface when displayed in your application.
• i18n (optional): An object containing text overrides for SDK components. Can be a single-language config or a multi-language config keyed by language code.

Caution

URL-based i18n configuration has been removed. Only inline objects are supported.

domain (optional)

The domain of your application. This is used to identify your application in the Frak ecosystem.

Tip

This property is optional. If not provided, it will be automatically retrieved during initialization.

waitForBackendConfig (optional)

Controls whether components wait for the backend-driven configuration to be resolved before rendering.

• true (default): Components show a loading spinner until backend config is resolved.
• false: Components render immediately with local config and HTML attributes.

attribution (optional)

Default attribution parameters (utmSource, utmMedium, utmCampaign, utmTerm, via, ref) appended to outbound sharing URLs. Per-call displaySharingPage overrides take precedence, then backend config, then this SDK-level default. utmContent is intentionally excluded, as it is per-content rather than a merchant-wide default.

preload (optional)

UI views to preload inside the listener iframe for a snappier first display. Accepts an array of "modal" and/or "sharing".

Tip

Defaults to ["sharing"].

Example Configuration

Here’s an example of a complete configuration object:

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

const frakConfig: FrakWalletSdkConfig = {
  walletUrl: "https://wallet.frak.id",
  metadata: {
    name: "My Awesome dApp",
    lang: "en",
    currency: "usd",
    logoUrl: "https://my-app.com/logo.png",
    homepageLink: "https://my-app.com",
  },
  customizations: {
    css: "https://my-app.com/frak-styles.css",
    i18n: {
      en: {
        "sdk.modal.title": "Welcome!",
      },
      fr: {
        "sdk.modal.title": "Bienvenue !",
        "sharing.title": "Partage ce produit!",
      }
    }
  },
  domain: "my-app.com",
};

Using the Configuration

How you use this configuration depends on whether you’re using React or vanilla JavaScript:

React

In a React application, use the FrakConfigProvider to provide this configuration to your app:

import { FrakConfigProvider, FrakIFrameClientProvider } from '@frak-labs/react-sdk';

const frakConfig = {
  metadata: {
    name: "My Awesome dApp",
  },
};

function App() {
  return (
    <FrakConfigProvider config={frakConfig}>
      <FrakIFrameClientProvider>
        {/* Your app components */}
      </FrakIFrameClientProvider>
    </FrakConfigProvider>
  );
}

Vanilla JavaScript

In a vanilla JavaScript application, pass this configuration when creating a Frak client:

import { createIFrameFrakClient, createIframe } from '@frak-labs/core-sdk';

const frakConfig = {
  metadata: {
    name: "My Awesome dApp",
  },
};

const iframe = createIframe({ config: frakConfig });
const client = await createIFrameFrakClient({ config: frakConfig, iframe });

Best Practices

1. Environment-based Configuration: Consider using different configurations for development and production environments. This allows you to use the development Frak Wallet during testing.

2. Secure CSS: If you’re providing a custom CSS file, ensure it’s served over HTTPS to prevent security issues.

3. Domain Consistency: If you provide a domain, make sure it matches the actual domain where your application is hosted. Mismatches can lead to authentication issues.

4. Iframe Creation: Always use the createIframe helper function provided by the SDK to create the iframe. This ensures proper setup and compatibility.

Caution

Remember to handle any potential errors when creating the iframe or initializing the client.

By properly configuring the Wallet SDK, you ensure that it can communicate effectively with the Frak Wallet and provide a seamless experience for your users.

Next Steps

• Backend-Driven Configuration — Learn how the SDK dynamically resolves settings from the Frak backend.
• Placements — Customize component behavior for different sections of your website.
• Tracking User Interactions — Learn about interaction tracking.