Quick Start

Step 1: Install the SDK

Follow the installation guide to install the SDK and get your API key.

Step 2: Wrap Your App

Wrap your root component with UserbubbleProvider:

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

export default function App() {
  return (
    <UserbubbleProvider
      config={{
        apiKey: process.env.EXPO_PUBLIC_USERBUBBLE_API_KEY!,
        debug: __DEV__, // Enable debug logging in development
      }}
    >
      <YourAppContent />
    </UserbubbleProvider>
  );
}

Step 3: Identify Users

Use the useUserbubble() hook to identify users after they log in:

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

function LoginScreen() {
  const { identify } = useUserbubble();

  const handleLogin = async () => {
    // Your login logic here
    const user = await yourLoginFunction();

    // Identify the user with Userbubble
    await identify({
      id: user.id,           // Your user ID
      email: user.email,     // User email
      name: user.name,       // Optional: user name
      avatar: user.avatar,   // Optional: avatar URL
    });

    // Navigate to home screen
    navigation.navigate("Home");
  };

  return <Button title="Login" onPress={handleLogin} />;
}

Step 4: Open Userbubble

Add a button to let users give feedback or access Userbubble:

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

function HomeScreen() {
  const { openUserbubble, isIdentified } = useUserbubble();

  if (!isIdentified) {
    return <Text>Please log in first</Text>;
  }

  return (
    <Button
      title="Give Feedback"
      onPress={() => openUserbubble("/feedback")}
    />
  );
}

Complete Example

Here's a complete working example:

import React from "react";
import { Button, View, Text } from "react-native";
import {
  UserbubbleProvider,
  useUserbubble,
} from "@userbubble/react-native";

// Root component
export default function App() {
  return (
    <UserbubbleProvider
      config={{
        apiKey: process.env.EXPO_PUBLIC_USERBUBBLE_API_KEY!,
        debug: __DEV__,
      }}
    >
      <MyApp />
    </UserbubbleProvider>
  );
}

// Your app content
function MyApp() {
  const { identify, openUserbubble, isIdentified, logout } = useUserbubble();
  const [loading, setLoading] = React.useState(false);

  const handleLogin = async () => {
    setLoading(true);
    try {
      // Simulate login (replace with your actual login)
      const user = {
        id: "user_123",
        email: "john@example.com",
        name: "John Doe",
      };

      await identify(user);
      console.log("User identified!");
    } catch (error) {
      console.error("Identification failed:", error);
    } finally {
      setLoading(false);
    }
  };

  const handleLogout = async () => {
    await logout();
    console.log("User logged out");
  };

  return (
    <View style={{ padding: 20, gap: 10 }}>
      {!isIdentified ? (
        <Button
          title={loading ? "Logging in..." : "Login"}
          onPress={handleLogin}
          disabled={loading}
        />
      ) : (
        <>
          <Text>Welcome back!</Text>
          <Button
            title="Open Feedback"
            onPress={() => openUserbubble("/feedback")}
          />
          <Button title="Logout" onPress={handleLogout} />
        </>
      )}
    </View>
  );
}

Configuration Options

The config object accepts these options:

Option	Type	Default	Description
`apiKey`	`string`	Required	Your organization's API key
`debug`	`boolean`	`false`	Enable debug logging
`storageType`	`"expo" \| "async-storage" \| "auto"`	`"auto"`	Storage type (auto-detect recommended)
`customStorage`	`StorageAdapter`	`undefined`	Custom storage implementation

Next Steps

Learn about all available methods in the API Reference
See more examples in the Examples page
Check out advanced usage patterns

Enable debug: __DEV__ during development to see helpful logs about user identification and SDK operations.