Installation

Choose Your Method

Script Tag (any website)

Add this snippet before the closing </body> tag:

<script src="https://unpkg.com/@userbubble/web/dist/userbubble.min.js"></script>
<script>
  Userbubble.init({ apiKey: 'ub_live_xxxxxxxxxxxxx' });
</script>

That's it — the widget will appear on your page immediately.

npm / pnpm / yarn

npm install @userbubble/web

pnpm add @userbubble/web

yarn add @userbubble/web

Then import and initialize:

import { Userbubble } from "@userbubble/web";

Userbubble.init({ apiKey: "ub_live_xxxxxxxxxxxxx" });

React

Install the package:

npm install @userbubble/web

Import from the /react subpath:

import {
  UserbubbleProvider,
  UserbubbleWidget,
} from "@userbubble/web/react";

function App() {
  return (
    <UserbubbleProvider config={{ apiKey: "ub_live_xxxxxxxxxxxxx" }}>
      <MyApp />
      <UserbubbleWidget />
    </UserbubbleProvider>
  );
}

Get Your API Key

Before using the SDK, you'll need an API key:

Go to your organization settings in Userbubble
Navigate to "API Keys"
Click "Generate New Key"
Copy the API key (it starts with ub_live_ or ub_test_)

Store your API key securely in environment variables. Never commit it to your repository.

Environment Variables

For Next.js / Vite / any bundler:

Add to your .env file:

NEXT_PUBLIC_USERBUBBLE_API_KEY=ub_live_xxxxxxxxxxxxx

Then reference it in code:

Userbubble.init({
  apiKey: process.env.NEXT_PUBLIC_USERBUBBLE_API_KEY!,
});

Next Steps

Continue to the Quick Start guide to identify users and open the widget.