← Installation guidesREACT · 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 ↓Doing it with AI? Start here ↗

OverviewBillingSettings

/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.

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

npm install orka-web-sdk

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

// 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;
}

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 ↗

EXAMPLE VISITOR DATA

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

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 oncePlan or feature changes Update the contextHelp button clicked Open the chatAccount 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 ↗

A BRIEF YOU CAN COPY

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 ↗

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.

STRAIGHT FROM THE DOCUMENTATION

The details, when you need them.

Checked in September 2026. Questions or corrections? [email protected].

More context.
A better first answer.

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

Start with Orka ↗

How to add Orka to yourSingle Page Application.

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