In your app

Put the chat in a single-page web app, a mobile app or a desktop app, and recognise your signed-in customers there.

Single-page web apps

In React, Vue, Svelte, Next.js and the like, load the chat's line once, in the page shell that every route shares: index.html, or the root layout. The chat then stays put as people move around your app.

In Next.js, put it in the root layout with the Script component from next/script: its src is the address in the line on your Chat page (it carries your own site key), and its strategy is afterInteractive, so it loads once.

Add your app's address to Websites allowed to embed. While you build, you can add the address you develop on too, such as http://localhost:3000: it counts as one of your plan's websites, so remove it when you are done.

To open the chat from your own Help menu, give the menu item data-sw-open, or call window.SupportWidget.open(). To hide the round button, see Opening the chat from your own button.

Signed-in customers in a web app

On Growth and Scale, tell the chat who is signed in, so their conversation follows them to any device. Your server signs the customer with your secret (never your app's browser code: anyone could read it there).

A route on your server that returns the signature for whoever is signed in, here in Next.js:

// app/api/support-identity/route.ts
import crypto from "node:crypto";

export async function GET() {
  const user = await getSignedInUser();            // your own session
  if (!user) return Response.json(null);
  const ts = Math.floor(Date.now() / 1000);
  const hash = crypto.createHmac("sha256", process.env.SUPPORT_IDENTITY_SECRET!)
    .update(`${user.id}|${user.email.toLowerCase()}|${ts}`).digest("hex");
  return Response.json({ id: String(user.id), email: user.email, name: user.name, ts, hash });
}

Then, in your app, after someone signs in and again after they sign out:

async function tellTheChat() {
  const user = await fetch("/api/support-identity").then((r) => r.json());
  const sw = (window.SupportWidget = window.SupportWidget || {});
  if (typeof sw.identify === "function") sw.identify(user);
  else sw.user = user;                             // the chat has not loaded yet: it reads this when it does
}

The signature, its rules and how to check it works are in Signed-in visitors.

Mobile apps

For a Help button in an iOS or Android app, open your chat link in the system's in-app browser (SFSafariViewController on iOS, Custom Tabs on Android). Nothing to build, and the chat is the same one your website has. Visitors there are anonymous: a person who asks for help types their email address.

To recognise signed-in customers in the app, make a help page on your own website instead:

A page your server renders for the signed-in customer, with the chat's line and their signature set before it (Signed-in visitors).
Add that website to Websites allowed to embed.
Open the page in a web view, with JavaScript and web storage turned on (on Android, setJavaScriptEnabled(true) and setDomStorageEnabled(true)), signed in to your website as the same customer.

Desktop apps

A page loaded from the app's own files (a file:// address, as in Electron) cannot be one of your websites. Open your chat link in the person's browser from your Help menu, or load a help page from your own website, as for mobile apps.

If the chat doesn't appear

See Troubleshooting. In a web view, check JavaScript and web storage are on.

Still stuck? Write to hello@getswaru.com.