Referrals Embed

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:

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
  },
});

from dub import Dub

with Dub(
    token="DUB_API_KEY",
) as d_client:
    res = d_client.embed_tokens.referrals(request={
        "tenant_id": 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
            "tenant_id": user.id,  # the user's ID within your application
        },
    })

    # Handle response
    print(res.public_token)

package main

import(
    "context"
    dubgo "github.com/dubinc/dub-go"
    "github.com/dubinc/dub-go/models/operations"
    "log"
)

func main() {
    ctx := context.Background()

    s := dubgo.New(
        dubgo.WithSecurity("DUB_API_KEY"),
    )

    res, err := s.EmbedTokens.Referrals(ctx, &operations.CreateReferralsEmbedTokenRequestBody{
        TenantID: user.ID, // the user's ID within your application
        Partner: &operations.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
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res != nil {
        // Handle response
        log.Printf("Public token: %s", res.PublicToken)
    }
}

declare(strict_types=1);

require 'vendor/autoload.php';

use Dub;
use Dub\Models\Operations;

$sdk = Dub\Dub::builder()
    ->setSecurity('DUB_API_KEY')
    ->build();

$request = new Operations\CreateReferralsEmbedTokenRequestBody(
    tenantId: $user->id, // the user's ID within your application
    partner: new Operations\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
    ),
);

$response = $sdk->embedTokens->referrals(
    request: $request
);

if ($response->object !== null) {
    // Handle response
    echo $response->object->publicToken;
}

require 'dub'

s = ::OpenApiSDK::Dub.new(
    security: ::OpenApiSDK::Shared::Security.new(
        token: "DUB_API_KEY",
    ),
)

req = ::OpenApiSDK::Operations::CreateReferralsEmbedTokenRequestBody.new(
    tenant_id: user.id, # the user's ID within your application
    partner: ::OpenApiSDK::Operations::Partner.new(
        name: user.name, # the user's name
        email: user.email, # the user's email
        image: user.image, # the user's image/avatar
        tenant_id: user.id, # the user's ID within your application
    ),
)

res = s.embed_tokens.referrals(req)

if !res.object.nil?
    # Handle response
    puts res.object.public_token
end

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

yarn add @dub/embed-react

pnpm add @dub/embed-react

bun add @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:

referrals | analytics

required

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

light | dark | system

default:"light"

The theme of the embed.

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

const publicToken = "...";

const iframeUrl = "https://app.dub.co/embed/referrals";

const iframeParams = new URLSearchParams({
  token: publicToken,
  theme: "light",
  themeOptions: JSON.stringify({ backgroundColor: "#F5F5F5" }),
});

<iframe
  src={`${iframeUrl}?${iframeParams.toString()}`}
  allow="clipboard-write"
  class="h-screen w-full"
/>;

Overview

SDKs

APIs

Example App

Dub embedded referral dashboard demo app

Step 1: Generate embed token

Using server-side SDKs

Using REST API

Step 2: Install the embed

React component

Iframe embed

Embed options

​Example App

Dub embedded referral dashboard demo app

​Step 1: Generate embed token

​Using server-side SDKs

​Using REST API

​Step 2: Install the embed

​React component

​Iframe embed

​Embed options

Example App

Step 1: Generate embed token

Using server-side SDKs

Using REST API

Step 2: Install the embed

React component

Iframe embed

Embed options