Start

Releaseo SDK installation

Install Releaseo with the recommended @releaseo/sdk package, the hosted CDN script, React, Vue, or the version-pinned sdk-core runtime.

Choose an integration path

Path	Use it when
`@releaseo/sdk`	Recommended. You want a typed npm import with automatic compatible runtime updates.
CDN script	You want the fastest install in a marketing site, docs site, or app shell.
`@releaseo/react`	You are on React and want provider state, hooks, unread count, and widget actions.
`@releaseo/vue`	You are on Vue 3 and want plugin setup, composables, unread count, and widget actions.
`@releaseo/sdk-core`	You explicitly need the host runtime pinned inside your application bundle.

Package links:

Recommended npm package

Install the facade, import it, and initialize Releaseo once in browser-side code:

npm install @releaseo/sdk

import releaseo from "@releaseo/sdk";

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

await releaseo.identify("viewer_123", {
  tenantId: "tenant_456",
  email: "[email protected]",
  name: "Demo User",
  userHash: "server-generated-hmac",
});

await releaseo.open();

The facade and TypeScript declarations stay pinned in your package lock. The compatible host runtime is delivered through Releaseo’s stable /sdk/v0/ CDN channel, so compatible runtime fixes can arrive without reinstalling the package. Upgrade @releaseo/sdk when you need facade, type, or public API changes.

Direct CDN loader

The fastest install. No build step, no npm — paste two <script> tags and a floating launcher appears on your site.

<!-- Releaseo widget — paste once, before </body> -->
<script src="https://cdn.releaseo.io/sdk/v0/loader.js"></script>
<script>
  window.releaseo.init({ publishKey: "pk_live_3f9c2a7b8e1d4056a1b2c3d4" });
</script>

Contact, custom events, and host actions

After install, identify signed-in users so Contact can prefill safe fields:

await releaseo.identify("viewer_123", {
  tenantId: "tenant_456",
  email: "[email protected]",
  name: "Demo User",
  userHash: "server-generated-hmac",
});

userHash is optional, but required for verified Contact identity in the dashboard. Generate it server-side: HMAC_SHA256(CONTACT_IDENTITY_HMAC_SECRET, userId || email).

Send custom events that can be used by dashboard analytics and integrations:

await releaseo.track("plan_upgraded", {
  plan: "team",
  source: "billing",
});

releaseo.registerAction("open_chat", async ({ actionKey, label }) => {
  window.SupportChat?.open?.();
});

See Releaseo integrations to connect GitHub repositories, route events to Slack and Discord with custom messages, forward them to PostHog, send signed Webhook Out deliveries, and review the event catalog. GitHub setup is dashboard-owned and does not require SDK credentials in your host app.

React package

Install both packages for React apps.

npm install @releaseo/sdk @releaseo/react

import { ReleaseoProvider } from "@releaseo/react";

export function App() {
  return (
    <ReleaseoProvider config={{ publishKey: "pk_live_xxx" }}>
      <AppShell />
    </ReleaseoProvider>
  );
}

Vue package

Install both packages for Vue 3 apps.

npm install @releaseo/sdk @releaseo/vue

import { createApp } from "vue";
import { createReleaseo } from "@releaseo/vue";
import App from "./App.vue";

createApp(App)
  .use(createReleaseo({ config: { publishKey: "pk_live_xxx" } }))
  .mount("#app");

Use Vue composables when you need custom controls.

<script setup lang="ts">
import { useReleaseo, useReleaseoUnread } from "@releaseo/vue";

const { isReady, open } = useReleaseo();
const unread = useReleaseoUnread();
</script>

<template>
  <button type="button" :disabled="!isReady" @click="void open()">
    What's new {{ unread > 0 ? `(${unread})` : "" }}
  </button>
</template>

See the @releaseo/vue guide for identity sync, reset keys, and Nuxt setup.

Version-pinned host runtime

Use @releaseo/sdk-core only when your application must bundle and run an exact host-runtime version. It does not update that host runtime automatically from the CDN; upgrade the package and redeploy your application to receive a newer runtime. Hosted widget and engagement assets may still load from Releaseo, but they do not replace the bundled host runtime.

See the version-pinned @releaseo/sdk-core guide.

SPA frameworks and client-side routing

The SDK works with single-page-app frameworks out of the box — Astro ClientRouter, Next.js client navigation, Vue Router, React Router, SvelteKit, and similar. When the framework swaps <body> or merges <head> during navigation, the SDK detects the change and re-attaches its launcher, iframe, and stylesheet on the next microtask. No configuration is required.

For zero-flicker persistence — the SDK DOM never disappears even briefly during a transition — render a sentinel inside your stable layout and apply your framework’s persist mechanism.

Astro

---
import { ClientRouter } from "astro:transitions";
---
<html>
  <head>
    <ClientRouter />
  </head>
  <body>
    <slot />
    <div data-releaseo-host transition:persist="releaseo-host" aria-hidden="true"></div>
  </body>
</html>

Next.js App Router

// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        {children}
        <div data-releaseo-host aria-hidden />
      </body>
    </html>
  );
}

Next.js preserves the root layout DOM across client navigations by default, so the sentinel does not need an explicit persist directive.

React Router, Vue Router, SvelteKit

Render <div data-releaseo-host> in your root layout, outside the route outlet (<Routes>, <RouterView>, +layout.svelte).

If you skip the sentinel, the SDK still works correctly via automatic DOM recovery — the sentinel is a UX optimization, not a requirement.

Hosted defaults

The published SDK is built with hosted defaults for the API and widget iframe. In production, most customers should pass only publishKey. Only pass endpoint or widgetUrl for local development or self-hosted environments.

SEO note

These docs are MDX, but Astro renders them as regular HTML at build time. Search engines can discover these pages through normal links and the generated sitemap.

Was this page helpful?