Embeddable Referral Widgets | blade47/dub Wiki | doc0

Public

Embeddable Referral Widgets | blade47/dub Wiki | doc0

Option / Event	Type / Value	Purpose
`token`	`string`	Required link authentication token for embed data access.
`root`	`HTMLElement`	Target DOM element where the embed container is appended (`document.body` by default).
`containerStyles`	`Partial<CSSStyleDeclaration>`	Custom CSS overrides for the root embed container.
`data`	`"referrals" \| "analytics"`	Specifies the target data type for the widget (`"referrals"` resolves to `/embed/referrals`).
`theme`	`"light" \| "dark" \| "system"`	Theme preference passed as a URL search parameter to the iframe.
`themeOptions`	`{ backgroundColor?: string }`	Additional theme customization options serialized into JSON.
`onError`	`(error: Error) => void`	Callback triggered when an `ERROR` message is received from the iframe.
`ERROR` event	`IframeMessage`	Handles error codes and messages dispatched from the frame.
`PAGE_HEIGHT` event	`IframeMessage`	Dynamically updates the embed container height upon receiving height updates.

Design Choice	Benefit	Cost
Imperative core SDK wrapped in React `useEffect`	Allows the core widget logic to be consumed in vanilla JavaScript or any framework while offering a clean React component facade.	Requires manual serialization of options in React hooks (`JSON.stringify`) to track deep configuration updates accurately.
Global singleton container ID check (`DUB_CONTAINER_ID`)	Prevents duplicate container injection if multiple render cycles or strict mode mount instances concurrently.	Restricts a single page to running one active embed instance under the default container identifier.
Hostname-based environment resolution (`localhost`, `preview.dub.co`, `app.dub.co`)	Automatically routes iframe requests to the correct local, preview, or production domain without requiring explicit host configuration.	Ties SDK deployment behavior directly to specific hostname strings matching the primary platform domains.

class ReferralsEmbedToken {
  async create(props: ReferralsEmbedTokenProps) {
    const publicToken = createId({
      prefix: EMBED_PUBLIC_TOKEN_PREFIX,
    });
 
    await redis.set(publicToken, JSON.stringify(props), {
      ex: EMBED_PUBLIC_TOKEN_EXPIRY,
      nx: true,
    });
 
    return {
      publicToken,
      expires: new Date(Date.now() + EMBED_PUBLIC_TOKEN_EXPIRY * 1000),
    };
  }
 
  async get(token: string) {
    return await redis.get<ReferralsEmbedTokenProps>(token);
  }
}

export function EmbedMiddleware(req: NextRequest) {
  const { path, searchParamsObj, fullPath } = parse(req);
 
  if (path.startsWith("/embed/support-chat")) {
    return NextResponse.rewrite(new URL(`/app.dub.co${fullPath}`, req.url));
  }
 
  if (searchParamsObj.token) {
    return NextResponse.rewrite(new URL(`/app.dub.co${fullPath}`, req.url));
  }
 
  return NextResponse.redirect(new URL("/", req.url));
}

Design Choice	Benefit	Cost
Storing token payloads directly in Upstash Redis	Provides sub-millisecond token resolution without requiring heavy relational database lookups for every session check.	Requires careful TTL management to ensure expired tokens are purged automatically.
Bearer token extraction via `Authorization` header	Aligns with standard HTTP REST authentication conventions for secure token transmission.	Relies on client-side headers being correctly attached by the iframe hosting wrapper.
Rate-limiting per token identifier (`ratelimit` via Redis)	Protects downstream program enrollment queries from abuse and brute-force inspection.	Adds latency checking overhead to every authenticated request.

const createIframe = (
  iframeUrl: string,
  token: string,
  options: Pick<DubEmbedOptions, "theme" | "themeOptions">,
): HTMLIFrameElement => {
  const iframe = document.createElement("iframe");
 
  const params = new URLSearchParams({
    token,
    ...(options.theme ? { theme: options.theme } : {}),
    ...(options.themeOptions
      ? { themeOptions: JSON.stringify(options.themeOptions) }
      : {}),
 
    // Allows the iframe content to set overflow values and send height messages without affecting older embed scripts
    dynamicHeight: "true",
  });
 
  iframe.src = `${iframeUrl}?${params.toString()}`;
  iframe.style.width = "100%";
  iframe.style.height = "100%";
  iframe.style.border = "none";
  iframe.setAttribute("credentialssupport", "");
  iframe.setAttribute("allow", "clipboard-write");
 
  return iframe;
};

export function DynamicHeightMessenger() {
  useEffect(() => {
    document.body.style.overflow = "hidden";
    const update = () => {
      const height = document.body.scrollHeight;
      parent.postMessage(
        {
          originator: "Dub",
          event: "PAGE_HEIGHT",
          data: { height },
        },
        "*",
      );
    };
    update();
 
    const resizeObserver = new ResizeObserver(update);
    resizeObserver.observe(document.body);
 
    return () => {
      resizeObserver.disconnect();
    };
  }, []);
 
  return false;
}

    // Listen the message from the iframe
    window.addEventListener("message", (e) => {
      const { data, event } = e.data as IframeMessage;
 
      console.debug("[Dub] Iframe message", data);
 
      switch (event) {
        case "ERROR":
          onError?.(
            new EmbedError({
              code: data?.code ?? "",
              message: data?.message ?? "",
            }),
          );
          break;
        case "PAGE_HEIGHT": {
          const container = document.getElementById(DUB_CONTAINER_ID);
          if (container) container.style.height = `${data.height}px`;
 
          break;
        }
      }
    });

export const getReferralsEmbedData = async (token: string) => {
  const { programId, partnerId } = (await referralsEmbedToken.get(token)) ?? {};
 
  if (!programId || !partnerId) {
    notFound();
  }
 
  const programEnrollment = await getProgramEnrollmentOrThrow({
    partnerId,
    programId,
    include: {
      partner: {
        select: {
          id: true,
          name: true,
          email: true,
          username: true,
          country: true,
          tremendousEmail: true,
          defaultPayoutMethod: true,
          platforms: {
            select: {
              type: true,
              identifier: true,
              verifiedAt: true,
            },
          },
        },
      },
      program: {
        select: {
          id: true,
          name: true,
          slug: true,
          domain: true,
          defaultGroupId: true,
          minPayoutAmount: true,
          termsUrl: true,
          embedData: true,
          resources: true,
        },
      },
      links: {
        include: {
          linkReward: {
            include: {
              clickReward: true,
              leadReward: true,
              saleReward: true,
              discount: true,
            },
          },
        },
      },
      partnerGroup: true,
      clickReward: true,
      leadReward: true,
      saleReward: true,
      referralReward: true,
      customReward: true,
      discount: true,
      programPartnerTags: {
        select: {
          partnerTagId: true,
        },
      },
    },
  });
 
  if (!programEnrollment || !programEnrollment.partnerGroup) {
    notFound();
  }
...

  const { totalClicks, totalLeads, totalConversions } =
    aggregatePartnerLinksStats(links);
 
  const [commissions, bounties] = await Promise.all([
    prisma.commission.groupBy({
      by: ["status"],
      _sum: {
        earnings: true,
      },
      _count: {
        id: true,
      },
      where: {
        earnings: {
          gt: 0,
        },
        programId,
        partnerId,
      },
    }),
 
    getBountiesForPartner(programEnrollment),
  ]);

export const ReferralsReferralsEmbedToken = () => {
  const token = useEmbedToken();
 
  const { error } = useSWR<{ token: number }>(
    "/api/embed/referrals/token",
    (url) =>
      fetcher(url, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }),
    {
      revalidateOnFocus: true,
      dedupingInterval: 30000,
      keepPreviousData: true,
    },
  );
 
  // Inform the parent if there's an error (Eg: token is expired)
  useEffect(() => {
    if (error) {
      window.parent.postMessage(
        {
          originator: "Dub",
          event: "ERROR",
          data: error.info,
        },
        "*",
      );
    }
  }, [error]);
 
  return null;
};

  const analyticsSearchParams = new URLSearchParams({
    event: "composite",
    groupBy: "timeseries",
    interval: "1y",
    saleType: "new",
  });
 
  const { data: analytics } = useSWR<AnalyticsTimeseries[]>(
    !isEmpty &&
      `/api/embed/referrals/analytics?${analyticsSearchParams.toString()}`,
    (url) =>
      fetcher(url, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }),
    {
      keepPreviousData: true,
      dedupingInterval: 60000,
    },
  );

Payout Method	Configuration Identifier	Minimum/Maximum Limits	Authentication Flow
Gift Cards (Tremendous)	`tremendous`	Min: `$10.00` (1000 cents), Max: `$10,000.00`	Email submission → OTP Request → 6-digit verification code input via `OTPInput`
Cash	Custom / External	Determined by program terms	External redirect to registration or SSO login endpoint