Web Widget

The web widget is a thin client over the REST API. Drop it into any page to give users a guided domain-connect experience.

Installation

Add the script tag, or install the npm package for bundler-based apps.

<script src="https://dns.global/widget.js"></script>

Initialization

Call DnsGlobal.init() with a backend-minted session token and your public key.

DnsGlobal.init({
  sessionToken: "sess_abc123...",
  publicKey: "pk_live_...",
  theme: { primaryColor: "#CF4520", borderRadius: 8 },
  onSuccess: (result) => console.log("Connected", result),
});

Theming

Field	Type	Required	Description
`primaryColor`	string	no	Accent colour for buttons and highlights (hex).
`borderRadius`	number	no	Corner radius in pixels.
`fontFamily`	string	no	CSS font-family stack for widget text.
`darkMode`	boolean	no	Force dark mode. Defaults to following the host page.

Callbacks

Field	Type	Required	Description
`onPlanReady`	(plan) => void	no	Fires when the change plan is computed, before the user confirms.
`onSuccess`	(result) => void	no	Fires after records are deployed and verified.
`onError`	(error) => void	no	Fires on any unrecoverable error.
`onClose`	() => void	no	Fires when the user dismisses the widget.

CSP configuration

If your site sends a Content-Security-Policy header, allow the widget origins:

script-src  https://dns.global;
connect-src https://api.dns.global;
frame-src   https://dns.global;

Note

The widget opens provider OAuth in a separate browser context, so you do not need to relax frame-src for provider domains.

Example: full integration

<!doctype html>
<html>
  <body>
    <button id="connect">Connect your domain</button>

    <script src="https://dns.global/widget.js"></script>
    <script>
      document.getElementById("connect").addEventListener("click", async () => {
        // Fetch a session token from YOUR backend (which calls /v1/sessions).
        const { sessionToken } = await fetch("/api/dns-session").then((r) => r.json());

        DnsGlobal.init({
          sessionToken,
          publicKey: "pk_live_...",
          onSuccess: (result) => {
            window.location.href = "/onboarding/domain-connected";
          },
        });
      });
    </script>
  </body>
</html>

Next steps

Set up webhooks for server-side confirmation
Read the Sessions reference