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:

<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:

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:

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.

npm install orka-web-sdk

Use the package this way:

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:

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

Initialization

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.

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.

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.

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.

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.

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.

window.Orka.hide();

`destroy()`

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

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:

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

PreviousHow to add Orka on your Shopify app NextHow to add Orka Live chat Widget to Webflow

Last updated 1 year ago