Nimbia Widget Integration Guide

This guide shows how to add the Nimbia widget to your web app and control it from your own code. The widget loads from one script tag.

#Quick Start

Add this snippet to every page where the widget should appear, and fill in the visitor's details:

<script>
(function (w, d) {
  if (w.Nimbia) return;
  var q = [];
  var n = { _q: q };
  "identify update shutdown boot startGuide stopGuide pauseGuide resumeGuide startCall endCall sendText continueCall dismissCtaModal off".split(" ").forEach(function (m) {
    n[m] = function () {
      var a = [].slice.call(arguments);
      return new Promise(function (res, rej) { q.push([m, a, res, rej]); });
    };
  });
  ["on", "once"].forEach(function (m) {
    n[m] = function (e, h) {
      q.push([m, [e, h]]);
      return function () { w.Nimbia.off(e, h); };
    };
  });
  n.ready = new Promise(function (r) { n.once("ready", r); });
  w.Nimbia = n;
  var s = d.createElement("script");
  s.type = "module";
  s.async = true;
  s.src = "https://widget.nimbia.ai/assets/widget.js";
  d.head.appendChild(s);
})(window, document);

Nimbia.boot({
  platformId: "your-platform-id", // from the Nimbia dashboard
  user: {
    id: user.id,
    email: user.email,
    name: user.fullName,
    createdAt: user.createdAt, // sign-up date, ISO 8601
    locale: user.locale, // e.g. "en", "nl"
    company: { id: user.companyId, name: user.companyName },
  },
});
</script>

The first part puts a stub on window.Nimbia and loads the widget script without blocking the page. The stub queues every call made before the script has loaded and runs them in order once it has, so the boot() call below it works.

boot() starts the widget. It takes:

boot() returns a promise that resolves once the visitor's session has started, or at once without user. It also still accepts the older snake_case config (platform_id, user_id, email, full_name, ...), and initialize() is a deprecated name for boot(). window.Hyper is a deprecated alias for window.Nimbia.

#With npm (coming soon)

Coming soon: the @nimbia/js package isn't published yet. Until then, use the script snippet above.

Once it's published, an app with a bundler can install the package instead of pasting the snippet:

npm install @nimbia/js

import { loadNimbia } from "@nimbia/js";

const nimbia = await loadNimbia({
  platformId: "your-platform-id",
  user: { id: user.id, email: user.email, name: user.fullName },
});
await nimbia.startGuide("your-guide-id");

loadNimbia() adds the same script to the page once and returns the same object as window.Nimbia, with TypeScript types. With user, it resolves once the session has started.

#Who the visitor is

boot({ user }) and identify(user) take the visitor's details:

#Logging out

When the visitor logs out, call shutdown(). It ends the session, clears what the widget stored, and removes it from the page, so the next visitor doesn't inherit the session.

async function handleLogout() {
  await Nimbia.shutdown("logout");
  // ... the rest of your logout logic
}

Pass a reason. A shutdown without one that interrupts a running guide is reported on our side as a possible integration problem.

When the next visitor logs in, call boot() again with their details. If a visitor logs in while the widget runs for an anonymous one, call identify() instead: it switches the running widget to the new visitor, which ends a running call.

#JavaScript API

The JavaScript API page lists every function, setting, action and event on window.Nimbia.

#Browser Compatibility

#Safari with Intelligent Tracking Prevention (ITP)

When your application (that includes the Nimbia widget) is embedded as an iframe on a different domain, Safari users with ITP enabled will experience session persistence issues. Sessions will not persist across page navigations, creating a new session on each page load.

Recommended solutions:

• Use a Single Page Application (SPA) - no page navigations means no session loss
• Avoid embedding your application in cross-domain iframes
• Host your application on the same domain as the parent frame
• See Safari ITP Limitations for detailed information

#Troubleshooting

If the widget doesn't show up:

• Open the browser console and look for errors that start with [nimbia].
• Check the platform UUID. Most settings are optional, but the widget won't load without a valid one.
• Check that your page can load the widget script URL. A content security policy can block it.
• Check that you pass a user identifier for the visitor.