@releaseo/sdk-core

Install

npm install @releaseo/sdk-core

import releaseo from "@releaseo/sdk-core";

releaseo.init({ publishKey: "pk_live_xxx" });

Public API

API	Purpose
init(config)	Initialize runtime, fetch /sdk/config, and mount the launcher infrastructure.
endpoint(endpoint)	Update the API endpoint at runtime.
identify(userId, properties?)	Attach the current viewer to the SDK session.
open() / close()	Control the widget drawer manually.
track(eventName, payload?)	Send a custom analytics event for dashboard analytics and selected integrations.
registerAction(actionKey, handler)	Register a host-app action that a whitelisted widget Home action can trigger.
unregisterAction(actionKey)	Remove a previously registered host-action handler.
logout()	Clear identity and keep the widget mounted in anonymous mode.
reset()	Fully tear down iframe, launcher, identity, and runtime state.
setMockData(posts)	Replace changelog mock data for preview/local flows.
setMockFeatureRequests(items)	Replace feature request mock data for preview/local flows.
settings	Read the latest resolved settings snapshot.

Identity

Call identify() after your app knows the signed-in viewer.

await releaseo.identify("viewer_123", {
  email: "[email protected]",
  name: "Demo User",
  tenantId: "tenant_456",
  plan: "startup",
});

Identity is persisted by the runtime with a default TTL of 30 days. Use logout() when a user signs out, and use reset() for tenant, organization, or project switches that need a clean SDK session.

For trusted contact identity, pass a backend-generated userHash alongside the normal identity properties when your backend supports HMAC identity signing.

Custom events and host actions

Use track() for custom events that should appear in dashboard analytics or be eligible for selected integration forwarding.

await releaseo.track("billing_limit_reached", {
  plan: "pro",
  source: "settings",
});

Use registerAction() when the dashboard Home action should trigger behavior in your host app, such as opening an existing chat tool. The dashboard stores only an action key; it does not store or execute raw JavaScript.

releaseo.registerAction("open-chat", async ({ actionKey, label }) => {
  console.info("Releaseo action", actionKey, label);
  await window.SupportChat?.open?.();
});

Remove handlers when the owning app shell unmounts:

releaseo.unregisterAction("open-chat");

Runtime callbacks

Subscribe to lifecycle callbacks when you need custom host behavior.

releaseo.on("ready", () => {
  console.log("Releaseo is ready");
});

releaseo.on("error", (error) => {
  console.error("[Releaseo]", error);
});

Useful callback groups include readiness, unread changes, state changes, identity errors, and bridge recovery notices.

Preview and mock mode

For demos or dashboard previews, initialize with mock changelog or feature request data. This lets the widget render without public network calls for those surfaces.

releaseo.init({
  publishKey: "pk_demo",
  mockFeatureRequests: [
    {
      id: "fr_1",
      projectId: "proj_demo",
      kind: "feature_request",
      title: "Clearer export labels",
      description: "Let customers request clearer export names.",
      status: "open",
      reviewStatus: "approved",
      categoryId: "general",
      category: {
        id: "general",
        value: "general",
        label: "General",
        color: "rgb(107, 114, 128)",
      },
      authorUserId: null,
      authorName: "Anonymous",
      authorEmail: null,
      reviewedAt: null,
      reviewedByUserId: null,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
      commentCount: 0,
      upvotes: 12,
      downvotes: 0,
      score: 12,
    },
  ],
});