SDK API reference

The Releaseo SDK exposes a single runtime object. With the direct CDN loader, every function lives on window.releaseo. With the recommended npm package, the default export is a typed facade with the same methods and it loads the compatible host runtime automatically.

// CDN — the loader assigns the runtime to window.releaseo
window.releaseo.init({ publishKey: "pk_live_xxx" });

// npm — the facade loads the compatible runtime automatically
import releaseo from "@releaseo/sdk";
releaseo.init({ publishKey: "pk_live_xxx" });

Loading and readiness

The widget initializes asynchronously: init() fetches your project config and mounts the launcher. The @releaseo/sdk facade queues supported calls while it loads the compatible runtime. With a direct script install, the runtime accepts calls after loader.js has run and replays them when the runtime and bridge are live. A browser cannot call window.releaseo before the direct loader itself has loaded, so use the synchronous snippet or the explicit load handler in the CDN quick start.

Methods that return a Promise resolve once the underlying action completes. They never reject for normal control flow, so fire-and-forget with void is safe:

void window.releaseo.open();

Method index

Method	Group	Summary
init(config)	Lifecycle	Initialize the runtime and mount the launcher.
endpoint(url)	Lifecycle	Point the SDK at a different API base URL at runtime.
reset()	Lifecycle	Tear down the iframe, launcher, identity, and state.
identify(userId, traits?)	Identity	Attach the signed-in viewer to the session.
logout()	Identity	Clear identity and switch to anonymous mode.
open()	Widget	Open the drawer on its default tab bar.
openFocused(tab)	Widget	Open the drawer directly on one tab.
close()	Widget	Close the drawer.
triggerLaunch(campaignId)	In-app Launches	Request a manually triggered banner, toast, or modal campaign.
track(event, payload?)	Analytics	Send a custom analytics event.
consent	Privacy	Read the current consent state.
setConsent(state)	Privacy	Update consent at runtime (GDPR).
purgeAll()	Privacy	Erase all persisted SDK data (right to erasure).
registerAction(key, handler)	Host actions	Wire a widget Home action to host-app code.
unregisterAction(key)	Host actions	Remove a registered host-action handler.
on(event, handler)	Events	Subscribe to a runtime event.
off(event, handler)	Events	Unsubscribe a runtime event handler.
setMockData(posts)	Preview	Swap in mock changelog data.
setMockFeatureRequests(items)	Preview	Swap in mock feature-request data.
settings	Diagnostics	Read the resolved runtime snapshot.

Lifecycle

init()

init(config: ReleaseoInitConfig): void

Initializes the runtime, fetches /sdk/config for your project, and mounts the launcher when the widget is enabled in dashboard settings. Call it once, as early as possible. See the ReleaseoInitConfig reference for every option.

Parameters

Parameter	Type	Description
config	ReleaseoInitConfig	At minimum a publishKey. All other fields are optional and resolved from dashboard settings.

Returns void

window.releaseo.init({
  publishKey: "pk_live_xxx",
  theme: "auto",      // "auto" | "light" | "dark"
  position: "right",  // "left" | "right"
  locale: "en",
  debug: false,
});

endpoint()

endpoint(endpoint: string): Promise<void>

Updates the API base URL after init(). Use this for self-hosted backends or to switch environments without re-initializing. The backward-compatible apiHost init option does the same thing at boot.

Parameters

Parameter	Type	Description
endpoint	string	Absolute base URL of the Releaseo API.

Returns Promise<void> — resolves once the new endpoint is applied.

await window.releaseo.endpoint("https://api.example.com");

reset()

reset(): void

Full teardown — clears identity, closes the widget, removes the launcher and iframe from the DOM, and returns internal state to IDLE. After reset() you can call init() again with a fresh configuration. Use it for tenant, organization, or project switches that need a completely clean session.

Returns void

window.releaseo.reset();
window.releaseo.init({ publishKey: "pk_live_other_tenant" });

Identity

identify()

identify(userId: string | number, properties?: ReleaseoIdentifyProperties): Promise<void>

Attaches the current signed-in viewer to the SDK session and opens an authenticated widget session. Call it as soon as your app knows who the user is. Identity is persisted (default TTL 30 days, configurable via identityTtl) so it survives refreshes.

Parameters

Parameter	Type	Description
userId	string | number	Your stable user identifier.
properties	ReleaseoIdentifyProperties	Optional flat traits. Values must be string, number, boolean, null, or undefined — no nested objects or arrays.

Recognized traits include email, name, tenantId, and userHash. See ReleaseoIdentifyProperties.

Returns Promise<void>

await window.releaseo.identify("u_123", {
  tenantId: "t_456",
  email: "[email protected]",
  name: "Amina",
  userHash: "server-generated-hmac", // optional, see below
});

logout()

logout(): void

Clears the current identity and session. The widget stays mounted but switches to anonymous mode; persisted identity is removed from localStorage and a fresh anonymous ID is minted on the next interaction. Call it when a user signs out.

Returns void

window.releaseo.logout();

Widget controls

open()

open(): Promise<void>

Opens the widget drawer with its full tab bar. Required when the dashboard trigger mode is set to “Only manually”; otherwise the launcher handles opening for you.

Returns Promise<void> — resolves once the drawer is open.

void window.releaseo.open();

openFocused()

openFocused(tab: ReleaseoFocusableTab): Promise<void>

Opens the drawer directly on a single tab, with the tab bar hidden — ideal for a dedicated “What’s new” button, an embedded help launcher, or a marketing CTA that should deep-link to one surface. The drawer returns to its default (full tab bar) the next time open() is called after close().

Parameters

Parameter	Type	Description
tab	ReleaseoFocusableTab	One of "home", "changelog", "feature_requests", "roadmap", "help".

Returns Promise<void>

// Deep-link a "What's new" button straight to the changelog feed
document.querySelector("#whats-new")?.addEventListener("click", () => {
  void window.releaseo.openFocused("changelog");
});

close()

close(): void

Closes the widget drawer.

Returns void

window.releaseo.close();

In-app Launches

Releaseo can show a release announcement as a banner, toast, or modal on the host page. These surfaces are not rendered inside the widget iframe; the SDK loads their renderer only when it needs one. Configure the campaign and its targeting in Releaseo, then use this API only for a campaign set to manual triggering. See In-app Launches for the surface guide.

triggerLaunch()

triggerLaunch(campaignId: string): Promise<void>

Requests a campaign configured with trigger mode manual.

Parameter	Type	Description
campaignId	string	The identifier of the manual campaign to request.

Returns Promise<void>

await window.releaseo.triggerLaunch("launch_abc123");

The request is not a guarantee that the surface will display immediately. Normal path, domain, audience, frequency, consent, kill-switch, and surface-slot rules still apply. Before initialization or engagement readiness, only the latest pending manual trigger is retained.

Analytics

track()

track(eventName: string, payload?: Record<string, unknown>): Promise<void>

Sends a custom analytics event. Events appear in dashboard analytics and can be forwarded to selected integrations (Slack, Discord, PostHog, and Webhook Out). After you define a matching active event trigger in the dashboard, the same call can send a custom Slack or Discord notification and trigger an in-app launch. Use it to record product moments worth correlating with widget engagement.

Parameters

Parameter	Type	Description
eventName	string	A stable, snake_case-friendly event name.
payload	Record<string, unknown>	Optional structured properties for the event.

Returns Promise<void>

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

Privacy and consent

GDPR / ePrivacy controls for telemetry and persistent storage. Default consent is "granted", so existing integrations need no changes.

consent

readonly consent: ConsentState

Read-only property holding the current consent state — "granted", "denied", or "pending".

console.log(window.releaseo.consent); // "granted" | "denied" | "pending"

setConsent()

setConsent(state: ConsentState): Promise<void>

Updates the consent state at runtime — wire it to your cookie banner.

State	localStorage	Analytics
"granted"	read + write	sent normally (queued telemetry is flushed)
"pending"	memory only	queued, not sent
"denied"	memory only	dropped; persistence stays off

Parameters

Parameter	Type	Description
state	ConsentState	"granted", "denied", or "pending".

Returns Promise<void>

// Initialize deferred, then grant after the user accepts the banner
window.releaseo.init({ publishKey: "pk_live_xxx", consent: "pending" });
window.releaseo.setConsent("granted");

purgeAll()

purgeAll(): Promise<void>

GDPR Article 17 (right to erasure). Best-effort wipe of all persisted SDK data: host-side localStorage/sessionStorage keys, queued telemetry, the in-memory identity, and widget-side storage. The user becomes anonymous, the SDK stays mounted, and the promise never rejects.

Returns Promise<void>

// Segment-style reset: wipe everything, mint a fresh anonymous id
await window.releaseo.purgeAll();

// Strict erasure — leave zero releaseo:* keys behind
await window.releaseo.setConsent("denied");
await window.releaseo.purgeAll();

Host actions

A “host action” lets a whitelisted widget Home button trigger code in your app — for example opening your existing support chat. The dashboard stores only an action key; it never stores or executes raw JavaScript.

registerAction()

registerAction(actionKey: string, handler: ReleaseoWidgetActionHandler): void

Registers a handler for a host action key configured in the dashboard.

Parameters

Parameter	Type	Description
actionKey	string	The key configured on the widget Home action.
handler	ReleaseoWidgetActionHandler	Receives { actionKey, actionId, label } and may return a Promise.

Returns void

window.releaseo.registerAction("open_chat", async ({ actionKey, actionId, label }) => {
  window.Intercom?.("show");
  console.info("Releaseo action", { actionKey, actionId, label });
});

unregisterAction()

unregisterAction(actionKey: string): void

Removes a previously registered host-action handler — call it when the owning app shell unmounts.

Parameters

Parameter	Type	Description
actionKey	string	The key passed to registerAction().

Returns void

window.releaseo.unregisterAction("open_chat");

Events

Subscribe to runtime lifecycle events for custom host behavior — badge counts, analytics bridges, or recovery handling.

on()

on<K extends keyof ReleaseoEventMap>(eventName: K, handler: (payload: ReleaseoEventMap[K]) => void): void

Subscribes a handler to a runtime event.

Returns void

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

window.releaseo.on("unreadChange", (count) => {
  document.querySelector("#badge")?.replaceChildren(String(count));
});

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

off()

off<K extends keyof ReleaseoEventMap>(eventName: K, handler: (payload: ReleaseoEventMap[K]) => void): void

Unsubscribes a previously registered handler. Pass the same function reference you gave to on().

Returns void

const onUnread = (count: number) => updateBadge(count);
window.releaseo.on("unreadChange", onUnread);
// later…
window.releaseo.off("unreadChange", onUnread);

Event reference

Event	Payload	Fires when
ready	void	The runtime has initialized and is usable.
unreadChange	number	The unread announcement count changes.
error	Error	A non-fatal runtime error occurs.
stateChange	SDKState	The internal state machine transitions.
identityChange	{ userId, previousUserId }	The identified user changes.
identityError	Error	Identity handoff (e.g. userHash) fails.
widgetAction	{ actionKey, actionId, label }	A host action is requested from the widget.
bridge:ready	void	The iframe bridge connects.
bridge:lost	void	The iframe bridge disconnects.
bridge:recovered	void	The iframe bridge reconnects after a loss.

Preview and mock data

Swap in mock content for demos, local development, and dashboard previews without reloading. After init(), these update the widget immediately.

setMockData()

setMockData(posts: ReleaseoChangelogListItem[]): void

Replaces the changelog posts shown in the widget.

Returns void

setMockFeatureRequests()

setMockFeatureRequests(featureRequests: ReleaseoFeatureRequestListItem[]): void

Replaces the feature-request items shown in the widget.

Returns void

window.releaseo.setMockFeatureRequests([
  {
    id: "fr_1",
    projectId: "proj_demo",
    kind: "feature_request",
    title: "Clearer export labels",
    description: "Let customers request clearer export names.",
    status: "open",
    reviewStatus: "approved",
    upvotes: 12,
    downvotes: 0,
    score: 12,
    commentCount: 0,
    authorName: "Anonymous",
    createdAt: new Date().toISOString(),
    updatedAt: new Date().toISOString(),
  },
]);

Diagnostics

settings

readonly settings: ReleaseoSettingsSnapshot | undefined

Read-only snapshot of the resolved configuration and live runtime state. undefined until init() has resolved. Useful for debugging and for reading values like the current unread count or session state.

Frequently used fields

Field	Type	Description
state	SDKState	Current state-machine value (e.g. "IDENTIFIED", "OPENED").
unreadCount	number	Current unread announcement count.
hasSession	boolean	Whether an authenticated session is active.
bridgeReady	boolean	Whether the iframe bridge is connected.
consent	ConsentState	Effective consent state.
userid	string | number | null	The identified user id, or null when anonymous.
anonymousId	string	The current anonymous id.
version	string	Runtime version.
theme / position / locale	—	Resolved widget presentation settings.

console.log(window.releaseo.settings?.unreadCount); // e.g. 8
console.log(window.releaseo.settings?.state);       // e.g. "IDENTIFIED"

Type reference

ReleaseoInitConfig

Field	Type	Default	Description
publishKey	string	—	Project publish key. Required unless mock content is provided.
endpoint	string	Releaseo API	Preferred API base URL. Takes precedence over apiHost.
apiHost	string	—	Backward-compatible alias for endpoint.
widgetUrl	string	Releaseo CDN	Override only for self-hosted or local dev.
engagementAssetsBase	string	Releaseo CDN	Base URL for lazy In-app Launch chunks. Override only for self-hosted assets or local development.
analyticsEndpoint	string	same as endpoint	Analytics ingestion endpoint.
productId	string	from /sdk/config	Override only if needed.
theme	"auto" | "light" | "dark"	dashboard	Widget theme preference.
position	"left" | "right"	dashboard	Launcher / drawer position.
locale	string	dashboard	Widget locale.
debug	boolean	false	Verbose runtime diagnostics and dev warnings.
consent	ConsentState	"granted"	Telemetry/storage consent (GDPR).
respectDoNotTrack	boolean	false	Treat navigator.doNotTrack as "denied".
styleNonce	string	—	CSP nonce for injected host <style> tags.
identityTtl	number	2_592_000_000	Persisted-identity lifetime in ms (30 days).
mockPosts	ReleaseoChangelogListItem[]	—	Bypass the API and serve these changelog posts.
mockFeatureRequests	ReleaseoFeatureRequestListItem[]	—	Bypass the API and serve these feature requests.

ReleaseoIdentifyProperties

type TraitValue = string | number | boolean | null | undefined;
type ReleaseoIdentifyProperties = Record<string, TraitValue>;

Flat key/value traits only — nested objects and arrays are not allowed. Reserved keys with special handling: email, name, tenantId, and userHash (the server-generated HMAC for trusted identity).

ReleaseoFocusableTab

type ReleaseoFocusableTab =
  | "home"
  | "changelog"
  | "feature_requests"
  | "roadmap"
  | "help";

The strict set of tabs accepted by openFocused(). feedback and messages are widget tabs but are not navigable content views, so they are intentionally excluded.

ConsentState

type ConsentState = "granted" | "denied" | "pending";

ConsentState is also exported as a top-level type from the recommended package:

import type { ConsentState } from "@releaseo/sdk";

ReleaseoEventMap

interface ReleaseoEventMap {
  ready: void;
  unreadChange: number;
  error: Error;
  stateChange: SDKState;
  identityChange: { userId: string; previousUserId: string | null };
  identityError: Error;
  widgetAction: { actionKey: string; actionId: string; label: string };
  "bridge:ready": void;
  "bridge:lost": void;
  "bridge:recovered": void;
}