Skip to content

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;
}>;

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"

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.

domain (optional)

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

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.

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.

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