Skip to main content
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
    groupId: "grp_xxxxxx", // optional: the partner's group ID on Dub (https://d.to/groups)
  },
});

​
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
      groupId: "grp_xxxxxx", // optional: the partner's group ID on Dub (https://d.to/groups)
    },
  }),
});

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",
  }}
/>;
⌘I