How to add Orka on your Shopify app

PreviousHow to add Orka Live chat Widget to Wordpress NextHow to add Orka on your Single Page Application (SPA) ?

Last updated 3 months ago

How to add Orka on your Shopify app

Orka Chat Integration Documentation for Shopify

This documentation explains how to integrate the Orka chat widget into your Shopify application. Choose the integration method based on your development framework.

👉

Integration with Remix

If you built your application with Remix, you have two integration options:

Option 1: Using npm package (Recommended)

This approach uses Orka's official npm package and provides better integration with Remix.

Install the package via npm:

npm install orka-web-sdk

Create a new OrkaChat.tsx component:

import { useEffect } from 'react';

const OrkaChat = () => {
  useEffect(() => {
    import('orka-web-sdk').then((Orka) => {
      Orka.default.configure('YOUR_APP_ID');
    });
  });
  
  return null;
};

export default OrkaChat;

Integrate the component in your pages:

import OrkaChat from './components/OrkaChat';

export default function MyPage() {
  return (
    <div>
      {/* Your content */}
      <OrkaChat />
    </div>
  );
}

Option 2: Script Integration

This approach uses the script directly in your root.tsx file.

Add the script to your App component in root.tsx:

export default function App() {
  return (
    <html>
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width,initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        <script
          dangerouslySetInnerHTML={{
            __html: `
              window.ORKA_APP_ID="YOUR_APP_ID";
              (function(){
                d=document;
                s=d.createElement("script");
                s.src="//widget.orka.chat/app.js";
                s.async=1;
                d.getElementsByTagName("head")[0].appendChild(s);
              })();
            `
          }}
        />
      </body>
    </html>
  );
}

Standard Integration (Without Remix)

If you're not using Remix, you have several options for integrating the Orka widget:

Basic Integration

Add the following script to the <head> section of your HTML:

<script type="text/javascript">
  window.ORKA_APP_ID = "YOUR_APP_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>

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:

window.ORKA_LOAD = false;

If you disable auto-loading, you'll need to initialize the widget manually:

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

YOUR_APP_ID: Replace with your application ID
appType: (Optional) Specify "Shopify" or "Standalone"

Single Page Application Integration

If you're using a Single Page Application (SPA), you can use the npm package:

Install the package:

npm install orka-web-sdk

Initialize the widget:

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

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

Session Configuration

You can configure session data for any integration method:

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

Important: Insert the ORKA_SESSION configuration before the main Orka script.

API Methods

update(data)

Updates the session data for the chat widget.

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

reset()

Resets the chat session and updates context information.

window.Orka.reset();

Closes the current chat
Sends the current page's title and URL as context

toggle()

Toggles the widget visibility.

window.Orka.toggle();

show(message)

Opens the chat widget with an optional pre-filled message.

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

hide()

Closes the chat widget.

window.Orka.hide();

destroy()

Removes the widget instance from the page.

window.Orka.destroy();

Complete Integration Example

Here's a full example showing how to integrate the widget with various features:

<!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:
- Verify that the SDK script URL is correct
- Check that your APP_ID is valid
- Ensure the script is loaded after the DOM
- Check if auto-loading is disabled (ORKA_LOAD = false)
API calls failing:
- Check the browser console for errors
- Make sure the widget is fully initialized before calling methods
- Verify that methods are called after DOM content is loaded