Embedded referral dashboard

Tip

This feature is only available on Advanced plans and above.

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.

Tip

Looking to set up non-monetary rewards for your user referral partners? Read the guide on how to set that up.

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:

Dub embedded referral dashboard demo app

View the source code for acme.dub.sh 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.

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.

Note

When you call this endpoint, it first attempts to find an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment automatically. This means you don't need to handle enrollment logic separately – the endpoint guarantees a valid enrollment and returns a usable embed token every time.

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:

datareferrals | analyticsrequired#

The type of embed to use. In this case, we're using the referrals type.

themelight | dark | system#

The theme of the embed.

Default: "light"

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