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