API Reference

Components

UserbubbleProvider

The root provider component that manages SDK state and configuration.

import { UserbubbleProvider } from "@userbubble/react-native";

<UserbubbleProvider config={config}>
  {/* Your app */}
</UserbubbleProvider>

Props:

Prop	Type	Required	Description
`config`	`UserbubbleConfig`	Yes	SDK configuration object
`children`	`ReactNode`	Yes	Your app components

Hooks

useUserbubble()

Access Userbubble SDK functionality from any component.

import { useUserbubble } from "@userbubble/react-native";

function MyComponent() {
  const {
    user,
    isInitialized,
    isIdentified,
    authToken,
    organizationSlug,
    identify,
    logout,
    getUser,
    openUserbubble,
    getEmbedUrl,
  } = useUserbubble();
}

Returns: UserbubbleContextValue

This hook must be used within a UserbubbleProvider. Using it outside the provider will throw an error.

Types

UserbubbleConfig

Configuration object for the SDK.

type UserbubbleConfig = {
  apiKey: string;
  baseUrl?: string;
  debug?: boolean;
  storageType?: "expo" | "async-storage" | "auto";
  customStorage?: StorageAdapter;
};

Properties:

Property	Type	Default	Description
`apiKey`	`string`	Required	Your organization's API key from Userbubble
`baseUrl`	`string`	`"https://app.userbubble.com"`	Base URL for the Userbubble service. Override for custom domains or self-hosted instances.
`debug`	`boolean`	`false`	Enable debug logging to console
`storageType`	`"expo" \| "async-storage" \| "auto"`	`"auto"`	Storage type to use (auto-detection recommended)
`customStorage`	`StorageAdapter`	`undefined`	Custom storage implementation

Example:

const config: UserbubbleConfig = {
  apiKey: "ub_live_xxxxxxxxxxxxx",
  baseUrl: "https://app.userbubble.com", // Default, can be omitted
  debug: __DEV__,
  storageType: "auto",
};

UserbubbleUser

User information for identification.

type UserbubbleUser = {
  id: string;
  email: string;
  name?: string;
  avatar?: string;
};

Properties:

Property	Type	Required	Description
`id`	`string`	Yes	Your user's unique ID
`email`	`string`	Yes	User's email address
`name`	`string`	No	User's display name
`avatar`	`string`	No	URL to user's avatar image

Example:

const user: UserbubbleUser = {
  id: "user_123",
  email: "john@example.com",
  name: "John Doe",
  avatar: "https://example.com/avatar.jpg",
};

UserbubbleContextValue

Return value from useUserbubble() hook.

type UserbubbleContextValue = {
  user: UserbubbleUser | null;
  isInitialized: boolean;
  isIdentified: boolean;
  authToken: string | null;
  organizationSlug: string | null;
  identify: (user: UserbubbleUser) => Promise<void>;
  logout: () => Promise<void>;
  getUser: () => UserbubbleUser | null;
  openUserbubble: (path?: string) => Promise<void>;
  getEmbedUrl: (path?: string) => string | null;
};

Properties:

Property	Type	Description
`user`	`UserbubbleUser \| null`	Current identified user, or `null` if not identified
`isInitialized`	`boolean`	Whether SDK has finished initialization
`isIdentified`	`boolean`	Whether a user is currently identified
`authToken`	`string \| null`	Authentication token for the current user, or `null`
`organizationSlug`	`string \| null`	Organization slug for the current user, or `null`
`identify`	`Function`	Identify a user
`logout`	`Function`	Log out current user
`getUser`	`Function`	Get current user synchronously
`openUserbubble`	`Function`	Open full portal in device browser
`getEmbedUrl`	`Function`	Generate an authenticated embed URL (minimal UI) for WebView

StorageAdapter

Interface for custom storage implementations.

interface StorageAdapter {
  getItem(key: string): Promise<string | null>;
  setItem(key: string, value: string): Promise<void>;
  removeItem(key: string): Promise<void>;
  clear(): Promise<void>;
}

Example Implementation:

const customStorage: StorageAdapter = {
  async getItem(key: string): Promise<string | null> {
    return yourStorage.get(key);
  },
  async setItem(key: string, value: string): Promise<void> {
    await yourStorage.set(key, value);
  },
  async removeItem(key: string): Promise<void> {
    await yourStorage.remove(key);
  },
  async clear(): Promise<void> {
    await yourStorage.clearAll();
  },
};

Methods

identify()

Identify a user with Userbubble.

await identify(user: UserbubbleUser): Promise<void>

Parameters:

Parameter	Type	Description
`user`	`UserbubbleUser`	User information object

Returns: Promise<void>

Throws: Error if identification fails

Example:

const { identify } = useUserbubble();

await identify({
  id: "user_123",
  email: "john@example.com",
  name: "John Doe",
});

logout()

Log out the current user and clear stored data.

await logout(): Promise<void>

Returns: Promise<void>

Example:

const { logout } = useUserbubble();

await logout();

getUser()

Get the current user synchronously.

getUser(): UserbubbleUser | null

Returns: UserbubbleUser | null - Current user or null if not identified

Example:

const { getUser } = useUserbubble();

const currentUser = getUser();
if (currentUser) {
  // User is identified
}

Generate an authenticated URL for embedding in a WebView. Returns a URL to the embed view — a minimal UI with user info, content area, and a bottom tab bar (Feedback, Roadmap, Updates). No full header or navigation is shown.

getEmbedUrl(path?: string): string | null

Parameters:

Parameter	Type	Default	Description
`path`	`string`	`"/feedback"`	Path to load (e.g., `/feedback`, `/roadmap`, `/changelog`)

Returns: string | null - Authenticated URL, or null if user is not identified

Example:

import { Modal, View } from "react-native";
import { WebView } from "react-native-webview";

const { getEmbedUrl } = useUserbubble();
const url = getEmbedUrl("/feedback");

// Show in a form sheet modal
if (url) {
  return (
    <Modal presentationStyle="formSheet" animationType="slide">
      <WebView source={{ uri: url }} style={{ flex: 1 }} />
    </Modal>
  );
}

The embed URL renders a minimal view with a bottom tab bar for navigation — no full header. Use openUserbubble() instead if you want the full portal experience in the device browser.

openUserbubble()

Open Userbubble in the device's default browser.

await openUserbubble(path?: string): Promise<void>

Parameters:

Parameter	Type	Default	Description
`path`	`string`	`"/"`	Path to open (e.g., `/feedback`, `/changelog`)

Returns: Promise<void>

Throws: Error if user is not identified or URL cannot be opened

Example:

const { openUserbubble } = useUserbubble();

// Open feedback page
await openUserbubble("/feedback");

// Open changelog
await openUserbubble("/changelog");

// Open root
await openUserbubble();

Platform Detection

The SDK automatically detects whether you're using Expo or bare React Native:

Storage Selection:

Expo: Uses expo-secure-store for encrypted storage
Bare RN: Uses @react-native-async-storage/async-storage
Custom: Use customStorage config option

Override Auto-Detection:

<UserbubbleProvider
  config={{
    apiKey: "ub_live_xxxxx",
    storageType: "expo", // Force Expo storage
  }}
>

Error Handling

The SDK throws errors in these scenarios:

Hook Usage Error:

// ❌ Using hook outside provider
function MyComponent() {
  const { identify } = useUserbubble();
  // Error: useUserbubble must be used within UserbubbleProvider
}

Identification Error:

try {
  await identify(user);
} catch (error) {
  // Handle error (show message to user, retry, etc.)
}

Opening Userbubble Error:

try {
  await openUserbubble("/feedback");
} catch (error) {
  // User not identified or URL invalid
}

Debug Logging

Enable debug logging to see SDK operations:

<UserbubbleProvider
  config={{
    apiKey: "ub_live_xxxxx",
    debug: __DEV__, // Enable in development
  }}
>

Debug logs include:

Storage operations
User identification
API requests
URL generation
Error details

Example output:

[userbubble] Initializing SDK...
[userbubble] Storage type: expo-secure-store
[userbubble] User restored from storage: user_123
[userbubble] Identifying user: user_123
[userbubble] User identified successfully
[userbubble] Opening Userbubble: /feedback

Next Steps

Check out Examples for complete code samples
Return to Quick Start guide
Learn about Installation options

API Reference

Components

UserbubbleProvider

Hooks

useUserbubble()

Types

UserbubbleConfig

UserbubbleUser

UserbubbleContextValue

StorageAdapter

Methods

identify()

logout()

getUser()

getEmbedUrl()

openUserbubble()

Platform Detection

Error Handling

Debug Logging

Next Steps

On this page