Placements

Placements let you define named configurations that customize how SDK components behave on different sections of your website. Instead of using the same global settings everywhere, you can create placements like "homepage", "product-page", or "checkout" — each with its own text, styling, and behavior.

How Placements Work

Create placements in the Frak Ads Manager dashboard under your merchant's customization settings.
Assign a placement to any SDK component using the placement attribute or prop.
The component resolves its configuration from the backend-driven config, applying placement-specific overrides on top of global defaults.

Global Config (dashboard defaults)
    └── Placement: "homepage"
    │       └── buttonShare: { text: "Share this!", clickAction: "sharing-page" }
    │       └── banner: { referralTitle: "Join our community" }
    └── Placement: "checkout"
            └── postPurchase: { ctaText: "Share and earn {REWARD}!" }
            └── buttonShare: { text: "Tell your friends" }

Using Placements with Web Components

All Frak web components accept a placement attribute. When provided, the component looks up its configuration from the matching placement in the backend config.

Share Button

<!-- Homepage: opens a full sharing page -->
<frak-button-share placement="homepage"></frak-button-share>
 
<!-- Product page: opens the embedded wallet -->
<frak-button-share placement="product-page"></frak-button-share>

Post-Purchase

<!-- Checkout confirmation page -->
<frak-post-purchase
    placement="checkout"
    customerId="cust_123"
    orderId="order_456"
    token="tok_abc"
></frak-post-purchase>

Banner

<!-- Show referral banner on homepage -->
<frak-banner placement="homepage"></frak-banner>

Wallet Button

<!-- Wallet button positioned on the left for this section -->
<frak-button-wallet placement="sidebar"></frak-button-wallet>

Open in App

<!-- Mobile-only button to redirect to the native app -->
<frak-open-in-app placement="mobile-landing"></frak-open-in-app>

Using Placements with the Core SDK

When calling SDK actions directly (without web components), pass the placement ID as the third argument:

import { displayModal, displayEmbeddedWallet } from '@frak-labs/core-sdk/actions';
 
// Display a modal associated with the "checkout" placement
const results = await displayModal(client, {
    steps: {
        login: { allowSso: true },
        final: { action: { key: "sharing" } },
    },
}, "checkout");
 
// Display the embedded wallet for the "homepage" placement
await displayEmbeddedWallet(client, {
    loggedIn: { action: { key: "sharing" } },
}, "homepage");

Placement Configuration Options

Each placement can customize the following components. Settings defined at the placement level override the global component defaults.

Share Button (`buttonShare`)

Option	Type	Description
`text`	`string`	Button text. Use `{REWARD}` placeholder for reward amount.
`noRewardText`	`string`	Fallback text when no reward is available.
`clickAction`	`"embedded-wallet"` \| `"share-modal"` \| `"sharing-page"`	Which UI opens on click.
`useReward`	`boolean`	Whether to display the reward amount.
`css`	`string`	Component-specific CSS override.

Wallet Button (`buttonWallet`)

Option	Type	Description
`position`	`"right"` \| `"left"`	Screen position of the floating wallet button.
`css`	`string`	Component-specific CSS override.

Post-Purchase (`postPurchase`)

Option	Type	Description
`badgeText`	`string`	Text for the badge pill above the message.
`refereeText`	`string`	Message shown to referred users. Use `{REWARD}` placeholder.
`refereeNoRewardText`	`string`	Fallback message for referees when no reward is found.
`referrerText`	`string`	Message shown to referrers. Use `{REWARD}` placeholder.
`referrerNoRewardText`	`string`	Fallback message for referrers when no reward is found.
`ctaText`	`string`	CTA button text. Use `{REWARD}` placeholder.
`ctaNoRewardText`	`string`	Fallback CTA text when no reward is found.
`css`	`string`	Component-specific CSS override.

Banner (`banner`)

Option	Type	Description
`referralTitle`	`string`	Title for the referral banner variant.
`referralDescription`	`string`	Description for the referral banner.
`referralCta`	`string`	CTA button text for the referral banner.
`inappTitle`	`string`	Title for the in-app browser banner variant.
`inappDescription`	`string`	Description for the in-app browser banner.
`inappCta`	`string`	CTA button text for the in-app browser banner.
`css`	`string`	Component-specific CSS override.

Open in App (`openInApp`)

Option	Type	Description
`text`	`string`	Button text override.
`css`	`string`	Component-specific CSS override.

Placement-Level Settings

In addition to component-specific settings, each placement also supports:

Option	Type	Description
`targetInteraction`	`string`	The interaction type to use for reward calculations in this placement.
`translations`	`Record<string, string>`	Placement-specific translation overrides.
`css`	`string`	Global CSS applied to modals displayed from this placement.

Placement vs. HTML Attributes

Component settings can come from two sources: placement configuration (backend-driven) and HTML attributes (inline). When both are present, HTML attributes take precedence, allowing you to override placement defaults for specific instances.

<!-- Placement "homepage" sets text to "Share this!" via the dashboard -->
<!-- But this instance overrides it with custom text -->
<frak-button-share placement="homepage" text="Share and earn up to {REWARD}!"></frak-button-share>

Example: Multi-Page Setup

Here's an example of using different placements across a website:

<!-- Homepage: referral banner + share button opening a full sharing page -->
<frak-banner placement="homepage"></frak-banner>
<frak-button-share placement="homepage"></frak-button-share>
 
<!-- Product page: share button opening the embedded wallet -->
<frak-button-share placement="product-page"></frak-button-share>
 
<!-- Checkout confirmation: post-purchase component -->
<frak-post-purchase
    placement="checkout"
    customerId="cust_123"
    orderId="order_456"
    token="tok_abc"
></frak-post-purchase>
 
<!-- All pages: floating wallet button -->
<frak-button-wallet placement="global"></frak-button-wallet>

Each placement is configured independently in the Frak Ads Manager dashboard, giving you full control over text, styling, and behavior per section — without changing your code.

Next Steps

Backend-Driven Configuration — Learn how the SDK resolves configuration from the backend.
Configuration — Set up local SDK configuration.
Components — Explore all available web components.