Single-page apps

In a single-page app (SPA), the browser loads one page and your JavaScript swaps the content when visitors navigate. React, Next.js, Vue, Angular, Svelte and many site builders work this way. The ASDK widget is built for it: load it once, and it follows the visitor from route to route by itself.

Load the widget once

Put the snippet where it loads once for the whole app, not inside a route or component:

The Next.js and React guide shows the code. Two things to avoid:

• Don't add the script from a component's effect. React may run effects twice in development, and an effect runs again whenever the component mounts.
• Don't remove and re-add the script on navigation. The widget keeps the conversation open across routes; reloading it would close the panel.

What the widget does on route changes

When your app changes the address with the browser's history functions, as every router does, the widget notices by itself. MDN's pushState reference explains the mechanism (checked October 2026). On each route change:

• The conversation stays open. A visitor can keep chatting while browsing your pricing and docs pages.
• The current page is updated, so each question is recorded with the address and title of the page it was asked on, and the Inbox can show where a conversation happened.
• A page view is recorded once the navigation settles.

You don't need to call anything from your router.

Signed-in users

In an app with accounts, tell the widget who is signed in when the session starts, and forget them when it ends:

// after sign-in, or when the app starts with a session
window.asdk("identify", { userId: user.id, email: user.email, name: user.name, userHash });

// on sign-out
window.asdk("shutdown");

shutdown removes the widget and forgets the identity and the current conversation, so the next person on the same computer starts fresh. To show the widget again after a new sign-in, reload the page or the app shell.

Add the queue line from the JavaScript API page before the snippet, so calls made before the widget has loaded aren't lost. For userHash, see Identity verification.

In TypeScript, declare the function once so the compiler knows it:

declare global {
  interface Window {
    asdk: (command: string, ...args: unknown[]) => void;
  }
}
export {};

Language switchers

If your app switches language without a page load, tell the widget so its interface follows:

window.asdk("setLocale", "de");

Agents answer in the language the visitor writes in, whatever the interface language. See Languages.

Opening the chat from your app

Call asdk("open") from any button, for example a "Contact us" item in your app's menu. To react to the panel or to leads in your app's state, subscribe with asdk("on", "open", handler), asdk("on", "close", handler) or asdk("on", "lead", handler), and unsubscribe with off when your component unmounts.

Install check for apps

Check installation looks for the snippet in the HTML your server sends. If your app renders only in the browser, the snippet may not be in that HTML. That's fine: the widget reports itself when it loads, so open your app once in a browser and run the check again.

Things that need care

• Routes on several domains. If your app runs on app.example.com and your marketing site on example.com, both need to be in the site's Allowed domains. See Add your website.
• Pages behind login. ASDK's crawler reads only public pages. Help content inside your app needs to be added another way, for example as files or text snippets.
• Content built only in the browser. If your public pages show their text only after JavaScript runs, the crawler may find little on them. See Crawl stuck or blocked.

Related: Content Security Policy, Install with HTML.