# Wallet SDK Configuration

# 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:

```ts twoslash
// [!include ~/snippets/types/FrakWalletSdkConfig.ts]
```

```js
/**
 * @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](/developers/concepts/backend-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:

```ts twoslash
// @noErrors
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:

```tsx twoslash
// @noErrors
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:

```ts twoslash
// @noErrors
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](/developers/concepts/backend-configuration) — Learn how the SDK dynamically resolves settings from the Frak backend.
- [Placements](/developers/concepts/placements) — Customize component behavior for different sections of your website.
- [Tracking User Interactions](/developers/concepts/interactions) — Learn about interaction tracking.