Embedded referral dashboards require an Advanced plan subscription or higher.
With Dub Partners, you can build an embedded referral dashboard that lives directly inside your application in just a few lines of code. This way, your users can automatically enroll in your partner program without needing to leave your app and sign up on a third-party platform.
In this guide, we’ll walk you through the steps to get started with Dub’s embedded referral dashboard feature.

​
Example App

Before we dive in, here’s an open-source example app showing Dub’s embedded referral dashboard in action: acme.dub.sh
You can also view the source code for the example app on GitHub:

​
Step 1: Generate embed token

First, you need to create a server API route that generates a public token, which will be used by the embedded referral dashboard to fetch real-time conversions and earnings data from the client-side.
A diagram of the embed token flow

​
Using server-side SDKs

If you’re using our server-side SDKs, you can generate an embed token using the dub.embedTokens.referrals method. 
const { publicToken } = await dub.embedTokens.referrals({
  tenantId: user.id, // the user's ID within your application
  partner: {
    name: user.name, // the user's name
    email: user.email, // the user's email
    image: user.image, // the user's image/avatar
    tenantId: user.id, // the user's ID within your application
  },
});

​
Using REST API

If you’re not using our server-side SDKs, you can generate an embed token using our REST API instead (via the POST /tokens/embed/referrals endpoint).
JavaScript
const response = await fetch("https://api.dub.co/tokens/embed/referrals", {
  method: "POST",
  body: JSON.stringify({
    tenantId: user.id, // the user's ID within your application
    partner: {
      name: user.name, // the user's name
      email: user.email, // the user's email
      image: user.image, // the user's image/avatar
      tenantId: user.id, // the user's ID within your application
    },
  }),
});

const data = await response.json();

const { publicToken } = data;
Refer to the full API reference to learn more about the properties you can pass to the POST /tokens/embed/referrals endpoint.

​
Step 2: Install the embed

Then, with the publicToken from Step 1, you can install and initialize the embedded referral dashboard. There are two ways to do this:

​
React component

First, install the NPM package: 
npm install @dub/embed-react
Then use the component in your React application: 
import { useState, useEffect } from "react";
import { DubEmbed } from "@dub/embed-react";

export default function App() {
  const [publicToken, setPublicToken] = useState("");

  useEffect(() => {
    const fetchPublicToken = async () => {
      // fetching from the server API route you created in Step 1
      const response = await fetch("/api/embed-token");
      const data = await response.json();
      setPublicToken(data.publicToken);
    };

    fetchPublicToken();
  }, []);

  if (!publicToken) {
    return <div>Loading...</div>;
  }

  return <DubEmbed data="referrals" token={publicToken} />;
}

​
Iframe embed

Alternatively, if you’re not using React (or you’re not on React v18.2.0 or higher), you can add the iframe directly to your HTML: 
import { useState, useEffect } from "react";

export default function App() {
  const [publicToken, setPublicToken] = useState("");

  useEffect(() => {
    const fetchPublicToken = async () => {
      // fetching from the server API route you created in Step 1
      const response = await fetch("/api/embed-token");
      const data = await response.json();
      setPublicToken(data.publicToken);
    };

    fetchPublicToken();
  }, []);

  if (!publicToken) {
    return <div>Loading...</div>;
  }

  return (
    <iframe
      src={`https://app.dub.co/embed/referrals?token=${publicToken}`}
      allow="clipboard-write"
      class="h-screen w-full"
    />
  );
}

​
Embed options

The embedded referral dashboard supports the following options for styling and behavior:
​
data
referrals | analytics
required
The type of embed to use. In this case, we’re using the referrals type.
​
theme
light | dark | system
default:"light"
The theme of the embed.
​
themeOptions
JSON-stringified object
Available options:
  • backgroundColor: The background color of the embed.
Depending on the embed type, you can use the following examples to initialize the embed options: 
import { DubEmbed } from "@dub/embed-react";

const publicToken = "...";

<DubEmbed
  data="referrals"
  token={publicToken}
  theme="light"
  themeOptions={{
    backgroundColor: "#F5F5F5",
  }}
/>;