# How to add Orka live chat to a Single Page Application (SPA)

Canonical: https://orka.chat/how-to-add-orka-to-single-page-application
Updated: 2026-09-21

[← Installation guides](/installation) REACT · VUE · ANGULAR · YOUR NEXT WEB APP 

# How to add Orka to your Single Page Application. 

 Keep chat in the app as people move from screen to screen. Give your team the user context that makes support easier.

[Follow the guide ↓](#spa-install)[Doing it with AI? Start here ↗](#spa-ai)

 Overview Billing Settings 

 /overview ↓ /billing ↓ /settings 

 Your chat stays aboard. One app shell. One widget. 

 FOR THE PEOPLE BUILDING THE PRODUCT 

## They need help in your app. Not another place to explain it.

### SaaS & member dashboards

 Answer questions about a plan, workspace or feature while the person is using it. Pass those details to Visitor Data.

### Shopify & product portfolios

 Keep each app’s identity clear while the same small team handles all the conversations in one inbox.

### Vibe-coded products

 Your AI assistant can add the integration to the app it helped build. Give it the docs and test the result, just as you test the rest of your product.

## What makes a SPA different?

 A traditional site loads another document when you follow a link. A single-page app often keeps the same document and replaces the content of the screen. That means a chat widget belongs in the persistent application shell, rather than in a component that is recreated for every route.

 You do not need to become a framework expert to understand the goal: one widget, the right project, useful customer data and a conversation that remains available while someone navigates. React, Vue and Angular can all use the JavaScript SDK; a framework that renders on the server needs a browser-only initialization step.

 THE PRACTICAL SETUP 

## From package to first reply.

 01 

### Choose the right project

 Open Orka → Settings → your project → Installation. Use that project’s ID. The example below uses YOUR_PROJECT_ID , not a real account identifier. Create separate projects for products whose support context should remain separate.

 INSTALL IN YOUR WEB APP Copy example 

```html
npm install orka-web-sdk
```

 02 

### Initialize once, in the browser

 Call this helper from your persistent client root after it mounts. The cached promise prevents repeated configuration when routes or components remount. For React, call it in a client effect; for Vue, in the persistent root’s mounted lifecycle; for Angular, in a browser-only application service.

 The package reads window , so keep its import out of server rendering. This example matches the default export in the published package.

 CLIENT-ONLY INITIALIZATION Copy example 

```html
// orka-client.js — called from the browser after mount.
let sdkPromise;

export function getOrka() {
 if (typeof window === "undefined") return Promise.resolve(null);
 if (!sdkPromise) {
 sdkPromise = import("orka-web-sdk").then(({ default: Orka }) => {
 Orka.configure("YOUR_PROJECT_ID");
 return Orka;
 });
 }
 return sdkPromise;
}
```

 03 

### Give the conversation context

 Once your app knows who is signed in, supply the fields your team needs. Your own data provides the values: a subscription, installation date, usage tier or current feature. Call update again when relevant values change.

 These attributes help with support; they are not a replacement for authentication or server-side permissions. [Explore custom visitor data ↗](/sdk)

 EXAMPLE VISITOR DATA Copy example 

```html
// Once your client has the signed-in account data:
const orka = await getOrka();
orka?.update({
 name: "Alex Morgan",
 email: "alex@example.com",
 plan: "Pro",
 workspace: "Studio Fern",
 current_screen: "Billing"
});
```

 04 

### Connect navigation deliberately

 Keep the widget mounted while people change screens. Use update for changing attributes. The browser reset() method refreshes the current page title and URL but also closes chat, so choose when that behavior is useful.

 You can open chat from a Help button with the browser SDK once it has loaded. Avoid inserting a second installation script on every click.

 Application starts Initialize once Plan or feature changes Update the context Help button clicked Open the chat Account changes Test the session boundary 

 YOU CAN ASK YOUR AI TO DO THE CODE 

## Not technical? Give it a precise brief.

 Claude, ChatGPT, Gemini or Grok can help you find the shared layout and add Orka. A coding tool with access to the repository can propose the change directly; a chat-only assistant may give you files to copy.

 Replace the placeholder ID, list the fields you want and ask it to explain its changes. Then test a real conversation. A confident “done” from the assistant is not the same as a working integration.

[More about installing with AI ↗](/how-to-install-orka-with-ai)

 A BRIEF YOU CAN COPY Copy example 

```html
Add Orka to this single-page application using the official orka-web-sdk package.
Read these docs first: https://penida.gitbook.io/orka-livechat/how-to-add-orka-.../how-to-add-orka-on-your-single-page-application-spa

Use my project ID: YOUR_PROJECT_ID
1. Identify the app's persistent root and client-only lifecycle.
2. Initialize Orka once. Use the package's default export. Do not import browser-only code during server rendering.
3. Send the support fields I choose from existing account state with update(). Do not invent data or include API keys, access tokens or payment credentials.
4. Update useful context after route or account changes. Do not claim reset() securely signs a user out; review account switching separately.
5. Avoid duplicate widgets on navigation or remount. Preserve the current layout and consent settings.
6. Show the changed files and a test plan for navigation, messages, replies and logout.

Fields I want to show in Visitor Data: [LIST YOUR FIELD NAMES HERE]
```

 BEFORE YOU SHIP 

## A short test. A calmer launch.

 ✓ 

### One widget

 Navigate through several routes and use Back/Forward. Confirm the launcher is not duplicated.

 ✓ 

### The right person

 Check Visitor Data with test accounts, then change the plan or relevant app state.

 ✓ 

### A full conversation

 Send a message, answer from Orka and confirm the reply returns to the customer.

 ✓ 

### A clean handover

 Test sign-out and account switching. Do not assume reset alone removes identity or conversation access.

 ✓ 

### Real devices

 Try a narrow screen, a refresh on a deep URL and any consent rules your app uses.

 ✓ 

### A useful fallback

 If a call runs too early, wait for the widget API. Check the project ID, network and browser console if chat does not appear.

 YOUR BEARINGS, BEFORE YOU DIVE IN 

## Your SPA questions. Before the first hello.

 Still wondering about something? [Ask a human at Orka ↗](mailto:hello@orka.chat)

 What is a single-page application? + A web app that changes screens in the browser without loading a completely new HTML document for every click. Many React, Vue and Angular apps work this way, and frameworks such as Next.js or Remix can combine server rendering with client navigation.

 Who benefits from adding Orka to a SPA? + SaaS founders, Shopify app developers, product teams, agencies and people building with AI. It is especially useful when customers need support inside a signed-in dashboard and your team needs account context.

 Is adding Orka to a SPA difficult? + The basic integration is small: install the package, configure your project once in the browser and test a conversation. Connecting account fields or handling server rendering and logout needs more care. The exact effort depends on your app.

 Can I do it with an AI coding assistant if I am not technical? + Yes, with a tool that can read and edit your project, or by applying its proposed changes. Give it the official documentation, your project ID and the fields you want. Ask it to explain and test navigation, duplicate loading and account changes before publishing.

 Can I use the ordinary installation snippet instead? + Yes. Install it once in the persistent shared layout and set initial ORKA_SESSION data before the widget script. Choose either the snippet or the npm integration so the same project is not loaded twice.

 Do I need to reload Orka on every route? + No. Keep the widget attached to the persistent app shell. Send changed visitor fields with update. If you use reset to refresh page title and URL, remember that it also closes the chat.

 How do I use Orka with server-side rendering? + The published package accesses window. Load it only in the browser, for example through a dynamic import after a client component mounts. Do not import it in server-executed code.

 Why does the example use a default import? + The published orka-web-sdk 1.0.4 source and type declarations export the SDK instance as default. Some older documentation examples show a named import. This guide uses the published package API checked in September 2026.

 Does reset erase the previous user’s identity? + Do not rely on it for that. The documented behavior is to close chat and send current page context. Test account switching and logout explicitly so the next person cannot inherit the wrong conversation. Ask Orka for the appropriate session flow if needed.

 Will Orka work with the other projects I run? + Create or select the right Orka project for each product. All those conversations can flow into one shared inbox. The free Solo plan includes unlimited projects; the team and AI options are listed on the pricing page.

 Your question for Orka ↗ 

 Ask Orky · AI answers from our website, with sources. Your question is sent to OpenAI; please leave out personal information. [Privacy](/privacy) 

 [Email your question ↗](mailto:hello@orka.chat) 

 STRAIGHT FROM THE DOCUMENTATION 

## The details, when you need them.

 Checked in September 2026. Questions or corrections? [hello@orka.chat](mailto:hello@orka.chat).

 [Orka: SPA integration and SDK methods ↗](https://penida.gitbook.io/orka-livechat/how-to-add-orka-.../how-to-add-orka-on-your-single-page-application-spa) [Orka: Shopify and Remix integration ↗](https://penida.gitbook.io/orka-livechat/how-to-add-orka-.../how-to-add-orka-on-your-shopify-app) [orka-web-sdk on npm ↗](https://www.npmjs.com/package/orka-web-sdk) 

## More context. A better first answer.

 One inbox for every app, store and idea you run.

[Start with Orka ↗](http://dashboard.orka.chat/signup)