> For the complete documentation index, see [llms.txt](https://penida.gitbook.io/orka-livechat/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://penida.gitbook.io/orka-livechat/how-to-add-orka-.../how-to-add-orka-on-your-single-page-application-spa.md).

# How to add Orka on your Single Page Application (SPA) ?

## Chat Application SDK Documentation

This documentation provides step-by-step guidance on how to integrate and use the Orka chat application SDK on your website. The SDK allows seamless integration of a support chat widget with powerful customization and user interaction capabilities.

***

### Getting Started

To integrate the Orka chat widget into your website, you need to include the Orka SDK script and initialize it with your app ID and other configurations.

#### Include the SDK Script

Add the following script tag to your HTML:

```html
<script type="text/javascript">
  window.ORKA_APP_ID = "[YOUR PROJECT ID]";
  (function () {
    d = document;
    s = d.createElement("script");
    s.src = "//widget.orka.chat/app.js";
    s.async = 1;
    d.getElementsByTagName("head")[0].appendChild(s);
  })();
</script>
```

#### Session Data

If you need to authenticate your users or get custom data about their session, you can also pass session data to the widget by setting the `ORKA_SESSION` variable:

```javascript
window.ORKA_SESSION = {
  name: "John Doe",
  email: "john.doe@example.com",
};
```

Important: you should insert the `ORKA_SESSION` script before the SDK script.

#### Optional Auto-Loading Configuration

By default, the widget loads automatically when the script is included. You can prevent this automatic loading by setting the `ORKA_LOAD` option to `false` before including the SDK script:

```javascript
window.ORKA_LOAD = false;
```

#### Single Page Application

If you are using a single page application, you can install the npm package and use it to initialize the widget.

```bash
npm install orka-web-sdk
```

Use the package this way:

```javascript
import { Orka } from "orka-web-sdk";

Orka.configure("[YOUR PROJECT ID]");
```

The chat will appear in your SPA app.

You can then use the SDK methods you will find below. For example to update the session data:

```javascript
Orka.update({
  name: "Marc Doe",
});
```

***

### Initialization

#### Initialize the Widget

Widget is loaded automatically when the script is included. However, if you use the `ORKA_LOAD` option and set it to `false`, you need to initialize the widget manually.

In that case, to initialize the chat widget, call the `load` method with your `appId` and optional configuration parameters.

```javascript
window.Orka.load("YOUR_APP_ID", "appType");
```

* **`YOUR_APP_ID`**: Replace this with your application ID.
* **`appType`**: (Optional) Specify the type of app if applicable. (Shopify / Standalone)

***

### API Methods

The Orka SDK provides several methods for interacting with the chat widget. Below is a detailed explanation of each method:

#### `update(data)`

Updates the session data for the chat widget.

```javascript
window.Orka.update({
  userName: "John Doe",
  email: "john.doe@example.com",
  theme: "dark",
});
```

* **Parameters**:
  * `data` (Object): Key-value pairs to update the session data.
* **Behavior**: If the widget is not ready, it temporarily stores the session data and applies it once initialized.

***

#### `reset()`

Resets the chat session and sends updated context information to the widget.

```javascript
window.Orka.reset();
```

* **Behavior**:
  * Closes the current chat.
  * Sends the current page's title and URL as context to the chat widget.

***

#### `toggle()`

Toggles the visibility of the chat widget.

```javascript
window.Orka.toggle();
```

* **Behavior**:
  * If the widget is open, it hides it.
  * If the widget is hidden, it opens it.

***

#### `show(message)`

Opens the chat widget and optionally pre-fills a message.

```javascript
window.Orka.show("Hello! I need help with my order.");
```

* **Parameters**:
  * `message` (String): (Optional) A message to display in the chat input field when opened.
* **Default**: If no message is provided, it simply opens the chat widget.

***

#### `hide()`

Closes the chat widget.

```javascript
window.Orka.hide();
```

***

#### `destroy()`

Destroys the chat widget instance and removes it from the page.

```javascript
window.Orka.destroy();
```

* **Behavior**: Cleans up the widget and removes it from the DOM.

***

### Example Integration

Here’s a complete example of integrating the Orka chat widget on your website:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Orka Chat Integration</title>
    <script type="text/javascript">
      window.ORKA_APP_ID = "[YOUR PROJECT ID]";
      // Optional: set session data
      window.ORKA_SESSION = {
        name: "John Doe",
        email: "john.doe@example.com",
      };
      (function () {
        d = document;
        s = d.createElement("script");
        s.src = "//widget.orka.chat/app.js";
        s.async = 1;
        d.getElementsByTagName("head")[0].appendChild(s);
      })();
    </script>
    <script>
      document.addEventListener("DOMContentLoaded", function () {
        // Update user session data
        document.getElementById("set-session").addEventListener("click", function () {
          window.Orka.update({
            name: "Marc Doe",
          });
        });

        // Show the chat widget with a pre-filled message
        document.getElementById("show-chat").addEventListener("click", function () {
          window.Orka.show("Hi, how can I help you?");
        });

        // Hide the chat widget
        document.getElementById("hide-chat").addEventListener("click", function () {
          window.Orka.hide();
        });
      });
    </script>
  </head>
  <body>
    <button id="set-session">Set session data</button>
    <button id="show-chat">Open Chat</button>
    <button id="hide-chat">Close Chat</button>
  </body>
</html>
```

***

### Troubleshooting

#### Common Issues

* **Widget Not Loading**:
  * Ensure the SDK script URL is correct.
  * Verify that your `appId` is valid.
* **API Calls Failing**:
  * Check the browser console for errors.
  * Ensure the widget is fully initialized before calling methods.

***

For additional support, visit [Orka Support](https://orka.chat/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://penida.gitbook.io/orka-livechat/how-to-add-orka-.../how-to-add-orka-on-your-single-page-application-spa.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.