Install

@cusuai/web-sdk is the browser widget. It mounts into a shadow root on the page. There is no iframe. Use it from a plain script tag, or from an ES module in Svelte, React, Vue, or anything else that runs in the browser.

You need the group id and public key. The shop origin must be on that key's allowed origins.

Package

npm install @cusuai/web-sdk

Bun, pnpm, and yarn work the same way. Types ship with the package.

import Cusu from "@cusuai/web-sdk";

Cusu.onError((error) => {
	console.warn("[cusu]", error.code, error.message);
});

Cusu.initialize({
	group: "grp_…",
	apiKey: "pk_…"
});

Script tag

For Shopify, Shoptet, or plain HTML, load the script before </body>. Pin the version. latest can stay cached for up to 30 days.

<script src="https://storage.cdn.zerops.app/4gfpg-widgetcdn/widget/0.2.0/cusu.js"></script>
<script>
	Cusu.initialize({
		group: "grp_…",
		apiKey: "pk_…"
	});
</script>

The global Cusu has the same methods as the default export. The reference lists them.

Order

1. Register errors first

   onError before initialize, so a failed boot is not missed.

2. Initialize

   initialize boots in the background. Calling it again replaces the previous widget.

3. Identify when someone is signed in

   identify can run before boot finishes. It waits and then sends. See Identify.

4. Reset on sign-out

   reset() starts a new anonymous visitor.

5. Destroy when the page should drop the widget

   In a single-page app, destroy on the route that should unmount it.

Call initialize from the client: an effect, onMount, or useEffect. Do not call it during server render.

useEffect(() => {
	Cusu.initialize({ group, apiKey });
	return () => Cusu.destroy();
}, [group, apiKey]);