@releaseo/sdk-core

Install

npm install @releaseo/sdk-core

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

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

Version behavior

The JavaScript host runtime stays pinned to the version in your package lock. Upgrade @releaseo/sdk-core and redeploy your application when you want a newer runtime:

npm install @releaseo/sdk-core@latest

The default configuration may still load hosted widget and engagement assets. Those assets do not replace or automatically update the host runtime imported from this package.

Core API at a glance

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() / openFocused(tab) / close()	Control the widget drawer manually.
triggerLaunch(campaignId)	Request a manually triggered banner, toast, or modal campaign.
track(eventName, payload?)	Send a custom analytics event for dashboard analytics and selected integrations.
on(event, handler) / off(event, handler)	Subscribe to or remove a runtime callback.
consent / setConsent(state) / purgeAll()	Read or manage persisted SDK data and consent.
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: "viewer@example.com",
  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");

In-app Launches

The same runtime can render a release announcement as a banner, toast, or modal on the host page. Configure its content, audience, target, and surface in Releaseo. For a campaign configured to trigger manually:

await releaseo.triggerLaunch("launch_abc123");

The campaign rules still decide whether it can appear. See In-app Launches for the right surface and trigger flow.

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,
    },
  ],
});