# Embedded Referral Dashboard

Show each signed-in user their referral link, stats, and rewards directly inside your product.

# Embedded Referral Dashboard

Use the embedded dashboard when you want users to manage referrals inside your
app instead of sending them to a separate portal.

It gives each user a referral link, performance stats, and reward details in a
single view. Open Campaigns for that affiliate appear as a card under Your
Rewards. The card is omitted when there are none. `showRewards=false` hides
commission rates only. Campaigns stay visible.

If you only want a lightweight widget or modal for the link itself, see
[Build a Custom Referral Modal in Your App](/help/installation-guides/custom-referral-modal).
That pattern works well as an entry point, while the embedded dashboard remains
the better destination for stats, rewards, and referral activity.

## When to Use It

Choose the embedded dashboard if:

- referrals should happen inside your product
- users already have accounts in your app
- you want a lightweight referral experience without a separate affiliate login

Use the standard affiliate portal instead if you need a dedicated affiliate
workspace, a separate onboarding flow, or broader partner management features.

## What You Need

Before you embed it, make sure you have:

- an Affonso program configured
- a signed-in user in your app
- a server-side endpoint that creates embed tokens for that user

Never create embed tokens in frontend code and never expose your Affonso API
key in the browser.

## Step 1: Preview and Customize the Dashboard

In Affonso:

1. Open [**Affiliate Program → Appearance**](https://affonso.io/app/affiliate-program/appearance)
2. Switch to the [**Embed** tab](https://affonso.io/app/affiliate-program/appearance?tab=embed)
3. Adjust theme, language, background, and which cards or controls appear
4. To hide referral-link advanced settings and payout-settings navigation in the embed, turn off **Show settings controls** (see [Hide settings in the embedded affiliate portal](/help/portal/hide-settings-in-embedded-portal)). The generated snippet then includes `showSettings=false`. Existing embeds that omit the parameter keep Settings visible.
5. To let partners see recent payouts and add or update their payout method in the embed, turn on **Partners can enter payout information**. Off is the default. The generated snippet then includes `showPayouts=true`. Existing embeds that omit the parameter stay without a Payout tab.
6. Copy the generated integration code as your starting point

## Step 2: Create the Embed Token on Your Server

Your backend should create an embed token for the current signed-in user and
return it to your frontend.

Treat the token like any other authenticated app resource:

- create it on the server
- scope it to the current user
- send it to the frontend only when you are ready to render the iframe

For the endpoint details, see the
[create embed token API reference](https://docs.affonso.io/api/endpoint/embed/create-token).

## Step 3: Render the First-Party Iframe (Recommended)

For production, first set up the
[embedded dashboard proxy](/help/installation-guides/proxy-setup/embedded-dashboard-proxy).
Then render the iframe from your domain:

```html
<iframe
  src="https://customer.com/r/embed/referrals?token=YOUR_EMBED_TOKEN&theme=light&lang=en"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write"
></iframe>
```

Replace `YOUR_EMBED_TOKEN` with the token your server generated for the current
user.

## Hosted Iframe (Fallback)

If you cannot set up a proxy yet, the hosted iframe still works:

```html
<iframe
  src="https://affonso.io/embed/referrals?token=YOUR_EMBED_TOKEN&theme=light&lang=en"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write"
></iframe>
```

Switch to the first-party setup when you can; it is less likely to be blocked
by ad blockers and privacy tools.

## What Your Users See

The embedded dashboard can show:

- their personal referral link
- performance stats such as clicks, signups, and sales
- rewards or earnings based on your program configuration
- a Campaigns card under Your Rewards when that affiliate has an open eligible Campaign. View opens portal Campaigns. Submit stays in the portal
- a **Payout** tab (recent payouts plus payout-method setup) only when you turn on **Partners can enter payout information**

## Verify the Integration

1. Sign in as a real or test user in your app
2. Load the page that contains the iframe
3. Confirm the iframe renders without console or network errors
4. Confirm the user sees their own referral data, not another user's
5. If you use first-party mode, confirm the iframe URL starts with your domain

## Troubleshooting

### The iframe is blank or blocked

- Check the iframe `src`
- Verify the token is valid and generated on the server
- Inspect browser DevTools for CSP, blocker, or proxy errors
- Use the first-party proxy setup if the hosted URL is blocked

### The wrong user data appears

- Confirm you create the embed token for the currently signed-in user
- Make sure cached tokens are not reused across users

## Next Steps

- [Hide settings in the embedded affiliate portal](/help/portal/hide-settings-in-embedded-portal)
- [Proxy the Embedded Dashboard Through Your Own Domain](/help/installation-guides/proxy-setup/embedded-dashboard-proxy)
- [How Affiliate Tracking Works](/help/installation-guides/overview/how-affiliate-tracking-works)
- [Full embedded dashboard API guide](https://docs.affonso.io/api/embedded-dashboard)