# AI chat
Source: https://docs.pointer.so/ai/chat

Learn more about our AI product expert.

## Overview

The AI chat feature provides instant help by answering questions about your product. When users ask questions, the AI determines whether to provide a direct answer or generate an interactive guide for more complex tasks. Learn more about [interactive guides](https://docs.pointer.so/features/guides). 

## How it works

Our AI chat agent automatically understands your app by analyzing UI elements, their relationships, and semantic meaning. As soon as you install Pointer, it can answer basic questions about your interface and features.

For more accurate and detailed responses, connect your knowledge base. This gives the AI deeper context about your product's concepts, workflows, and best practices. The AI combines this knowledge with its UI understanding to provide comprehensive assistance.

When users ask questions, the AI determines whether to give a quick answer or generate an interactive guide based on the complexity of the task. Simple queries like "What is a project?" get immediate answers, while step-by-step requests like "How do I set up my team?" trigger visual guides.


# AI walkthroughs
Source: https://docs.pointer.so/ai/guides

Learn more about the magic behind Pointer — visual guides that make your users happy. 

## Overview

Interactive guides are step-by-step walkthroughs that help users navigate your application. Each guide consists of a series of steps that can include instructions, element highlighting, and automated actions.

<Info>
  All guides are automatically generated by AI — you don't need to configure anything manually. The technical details below explain how guides work under the hood, helping you understand the system's capabilities.
</Info>

## Guide structure

A guide is defined by the following properties:

```typescript
interface Guide {
  id: string;          // Unique identifier for the guide
  name: string;        // Display name of the guide
  steps: Step[];       // Array of steps in the guide
  resumeData?: {       // Optional data for resuming guides
    currentStep: number;
    steps: Step[];
  };
}
```

## Guide triggers

Users can trigger guides by simply asking questions in the chat widget. The AI determines whether to provide a quick answer or create a visual guide. For example:&#x20;

* "How do I create a new project?"

* "Can you show me how to update my profile picture?"

* "I need help setting up my account"

Simple questions get instant answers through AI chat, while complex tasks trigger step-by-step guides. Learn more about [AI chat](https://docs.pointer.so/features/chat).

## Step configuration

Each step in a guide contains:

```typescript
interface Step {
  id: string;          // Unique identifier for the step
  position: string;    // Position of the highlight/pointer
  instructions: string; // Text instructions for the user
  action?: Action;     // Optional action to perform
  page: string;        // Page/route where the step occurs
}
```

## Supported element interactions

Pointer can detect and interact with various UI elements:

* Buttons

* Links

* Input fields

* Lists

* Tables

* Media elements

* Containers

* Text elements

* Navigation components

* Dialogs

* Tabs

* Breadcrumbs

* Icons

* Progress indicators

* Alerts

* Accordions

* Dropdowns

* Sliders

* Datepickers

* Custom components

## User controls and feedback

Users are able to pause/resume guides, skip steps, and exit guides at any time.

When a guide is completed, users can rate their experience by clicking 👍 or 👎, add comments about what worked or didn't, and report any issues they encountered.

## Troubleshooting

In testing, we've noticed a few common issues that can occur during guide generation and execution:

* Elements not found

* Failed interactions

* Navigation problems

* Timing issues

Please [contact us](mailto:team@pointer.so) if you need help resolving persistent issues.


# Styling
Source: https://docs.pointer.so/customization/styling

Learn how to customize your widget's appearance and content.

## Overview

Pointer's UI is fully customizable through the `PointerProvider` and `PointerFlowProvider `components. You can customize the theme colors, branding elements, and content to match your application's design system.

For the `PointerProvider`:

![images/styling.png](https://mintlify.s3.us-west-1.amazonaws.com/pointer-c79e5938/images/styling.png)

For the `PointerFlowProvider`:

![styling-onboarding.png](https://mintlify.s3.us-west-1.amazonaws.com/pointer-c79e5938/styling-onboarding.png)

For both providers (steps):

![images/step-styling.png](https://mintlify.s3.us-west-1.amazonaws.com/pointer-c79e5938/images/step-styling.png)

## Theme customization

Customize the visual appearance of the widget by configuring colors and styling. You can provide either a single color value or an object with `light` and `dark` values for dark mode support:

### Basic color configuration

```typescript
<PointerProvider
  // Theme colors (single values)
  primaryColor="#111827"      // Primary text and headings
  secondaryColor="#6B7280"    // Secondary text
  tertiaryColor="#f5f5f5"     // Tertiary elements
  accentColor="#6366f1"       // Interactive elements
  interactiveColor="#4f46e5"  // Interactive state colors
  cursorColor="##6366f1"	  // Cursor color, default is accentColor
  backgroundColor="#ffffff"   // Widget background
  borderColor="#e4e4e7"      // Border color
  borderRadius="12px"        // Border radius for components
>
```

### Dark mode support

For applications that support dark mode, you can provide different colors for light and dark modes:

```typescript
const themeColors = {
  primaryColor: {
    dark: "#ffffff",   // Primary color in dark mode (zinc-50)
    light: "#111827", // Primary color in light mode (gray-800)
  },
  secondaryColor: {
    dark: "#71717a",  // Secondary color in dark mode (zinc-500)
    light: "#6B7280", // Secondary color in light mode (gray-500)
  },
  tertiaryColor: {
    dark: "#27272a",  // Tertiary color in dark mode
    light: "#f5f5f5", // Tertiary color in light mode
  },
  backgroundColor: {
    dark: "#09090b",  // Background color in dark mode (zinc-950)
    light: "#ffffff", // Background color in light mode (white)
  },
  accentColor: {
    dark: "#3730a3",  // Accent color in dark mode
    light: "#6366f1", // Accent color in light mode
  },
  interactiveColor: {
    dark: "#4338ca",  // Interactive color in dark mode
    light: "#4f46e5", // Interactive color in light mode
  },
  cursorColor: {
    dark: "#3730a3",  // Cursor color in dark mode
    light: "#6366f1", // Cursor color in light mode
  },
  borderColor: {
    dark: "#27272a",  // Border color in dark mode (zinc-800)
    light: "#e4e4e7", // Border color in light mode (zinc-200)
  },
  borderRadius: {
    dark: "12px",     // Border radius in dark mode
    light: "12px",    // Border radius in light mode
  },
};

<PointerProvider
  apiKey={process.env.NEXT_PUBLIC_POINTER_API_KEY!}
  primaryColor={themeColors.primaryColor}
  secondaryColor={themeColors.secondaryColor}
  tertiaryColor={themeColors.tertiaryColor}
  backgroundColor={themeColors.backgroundColor}
  accentColor={themeColors.accentColor}
  interactiveColor={themeColors.interactiveColor}
  cursorColor={themeColors.cursorColor}
  borderColor={themeColors.borderColor}
  borderRadius={themeColors.borderRadius}
>
```

The widget will automatically use the appropriate colors based on the user's system preferences or your application's theme setting.

## Branding

Customize branding elements to match your company's identity:

### Basic branding

```typescript
<PointerProvider
  // Branding
  logomark="/path-to-your-logo.png"     // Your company logo, .png or .svg
  triggerIcon="pointer"                  // Widget trigger icon
  triggerBackground="#ffffff"           // Trigger button background color
  triggerIconColor="#111827"           // Trigger icon color
  triggerBorder="#e4e4e7"             // Trigger button border color
>
```

### Dark mode support for branding

For applications that support dark mode, you can provide different values for light and dark modes:

```typescript
<PointerProvider
  // Branding with dark mode support
  logomark={{
    light: "/logos/your-logo-dark.svg",  // Logo for light mode
    dark: "/logos/your-logo-light.svg",  // Logo for dark mode
  }}
  triggerBackground={{
    light: "#ffffff",
    dark: "#09090b",
  }}
  triggerIconColor={{
    light: "#111827",
    dark: "#ffffff",
  }}
  triggerBorder={{
    light: "#e4e4e7",
    dark: "#27272a",
  }}
  triggerIcon="pointer"
>
```

The `logomark` prop can be either a string path to your logo or an object with `light` and `dark` properties for different themes.

The `triggerIcon` can be one of: `'sparkles'`, `'help'`, `'message'`, `'zap'`, or `'pointer'`.

## Content

Customize the widget's text content and messaging:

```typescript
<PointerProvider
  // Content customization
  welcomeMessage="Hi there 👋"              // Initial greeting
  welcomeSubheading="How can we help?"      // Greeting subtext
  inputPlaceholder="Ask AI anything..."     // Chat input placeholder
>
```

## Link buttons

Customize up to four link buttons that appear at the top of the widget. These buttons can be used to direct users to important resources like documentation, community, or contact information:

```typescript
<PointerProvider
  // Link button customization
  link1Text="Discord"                        // First button text
  link1Icon="users"                          // First button icon
  link1Url="https://dub.sh/pointer-community" // First button URL
  link2Text="Documentation"                   // Second button text
  link2Icon="book"                           // Second button icon
  link2Url="https://docs.pointer.so"         // Second button URL
  link3Text="Email us"                       // Third button text
  link3Icon="mail"                           // Third button icon
  link3Url="mailto:team@pointer.so"          // Third button URL
  link4Text="GitHub"                         // Fourth button text
  link4Icon="github"                         // Fourth button icon
  link4Url="https://github.com/pointer-gg"   // Fourth button URL
>
```

Each link button is optional and has three customizable properties:

* `text`: The button's label
* `icon`: A [Lucide](https://lucide.dev) icon name (e.g., 'users', 'book', 'mail', 'github')
* `url`: The URL to open when clicked

If not provided, the buttons will use default values pointing to Pointer's resources.

## Complete example

Here's a complete example showing all customization options with dark mode support:

```typescript
const themeColors = {
  primaryColor: {
    dark: "#ffffff",
    light: "#111827",
  },
  secondaryColor: {
    dark: "#71717a",
    light: "#6B7280",
  },
  tertiaryColor: {
    dark: "#27272a",
    light: "#f5f5f5",
  },
  backgroundColor: {
    dark: "#09090b",
    light: "#ffffff",
  },
  accentColor: {
    dark: "#3730a3",
    light: "#6366f1",
  },
  interactiveColor: {
    dark: "#4338ca",
    light: "#4f46e5",
  },
  cursorColor: {
    dark: "#3730a3",
    light: "#6366f1",
  },
  borderColor: {
    dark: "#27272a",
    light: "#e4e4e7",
  },
};

<PointerProvider
  apiKey={process.env.NEXT_PUBLIC_POINTER_API_KEY!}
  // Theme with dark mode support
  primaryColor={themeColors.primaryColor}
  secondaryColor={themeColors.secondaryColor}
  tertiaryColor={themeColors.tertiaryColor}
  backgroundColor={themeColors.backgroundColor}
  accentColor={themeColors.accentColor}
  interactiveColor={themeColors.interactiveColor}
  cursorColor={themeColors.accentColor}
  borderColor={themeColors.borderColor}
  borderRadius="12px"
  
  // Branding with dark mode support
  logomark={{
    light: "/logos/your-logo-dark.svg",
    dark: "/logos/your-logo-light.svg",
  }}
  triggerIcon="pointer"
  triggerBackground={{
    light: "#ffffff",
    dark: "#09090b",
  }}
  triggerIconColor={{
    light: "#111827",
    dark: "#ffffff",
  }}
  triggerBorder={{
    light: "#e4e4e7",
    dark: "#27272a",
  }}
  
  // Content
  welcomeMessage="Hi there 👋"
  welcomeSubheading="How can we help?"
  inputPlaceholder="Ask AI anything..."
  suggestedItems={[
    "How do I get started?",
    "What are the key features?",
    "Can you help with integration?"
  ]}
  
  // Link buttons
  link1Text="Discord"
  link1Icon="users"
  link1Url="https://dub.sh/pointer-community"
  link2Text="Documentation"
  link2Icon="book"
  link2Url="https://docs.pointer.so"
  link3Text="Email us"
  link3Icon="mail"
  link3Url="mailto:team@pointer.so"
  link4Text="GitHub"
  link4Icon="github"
  link4Url="https://github.com/pointer-gg"
>
  {/* Your app content */}
</PointerProvider>
```

All customization properties are optional. If not provided, Pointer will use its default theme and content settings.

## Debugging styling issues

If you're experiencing issues with the styling not being applied correctly, here are some steps to troubleshoot:

### 1. Check prop values and types

Ensure your color values are valid CSS colors. The component accepts Hex codes (e.g., `"#ffffff"`).

```typescript
// ❌ Invalid - missing hash
<PointerProvider primaryColor="ffffff">

// ✅ Valid
<PointerProvider primaryColor="#ffffff">
```

### 2. Verify dark mode configuration

If you're using dark mode, ensure your theme object has both `light` and `dark` properties:

```typescript
// ❌ Invalid - missing light/dark properties
<PointerProvider
  primaryColor={{
    default: "#ffffff",
    darkMode: "#000000"
  }}
>

// ✅ Valid
<PointerProvider
  primaryColor={{
    light: "#ffffff",
    dark: "#000000"
  }}
>
```

### 3. Check component hierarchy

Make sure the `PointerProvider` is:

* Mounted in your component tree
* Wrapping the components you want to style
* Not nested inside another `PointerProvider`

```typescript
// ❌ Invalid - nested providers
<PointerProvider theme={theme1}>
  <PointerProvider theme={theme2}>  {/* This will not work as expected */}
    <YourComponent />
  </PointerProvider>
</PointerProvider>

// ✅ Valid
<PointerProvider theme={theme1}>
  <YourComponent />
</PointerProvider>
```

### 4. CSS override (last resort)

If you've tried the above solutions and are still experiencing issues, you can use CSS overrides as a last resort. Create a CSS file with higher specificity selectors:

```css
/* styles/pointer-overrides.css */

/* Override widget background */
.pointer-widget[data-theme="light"] {
  --pointer-background: #ffffff !important;
}
.pointer-widget[data-theme="dark"] {
  --pointer-background: #09090b !important;
}

/* Override primary text color */
.pointer-widget[data-theme="light"] {
  --pointer-primary: #111827 !important;
}
.pointer-widget[data-theme="dark"] {
  --pointer-primary: #ffffff !important;
}

/* Override accent color */
.pointer-widget[data-theme="light"] {
  --pointer-accent: #6366f1 !important;
}
.pointer-widget[data-theme="dark"] {
  --pointer-accent: #3730a3 !important;
}
```

Then import this CSS file in your application:

```typescript
// pages/_app.tsx or similar
import '../styles/pointer-overrides.css';
```

Note: Using CSS overrides should be a temporary solution while you debug the root cause. The `PointerProvider` props are the recommended way to customize the widget's appearance.

### 5. Z-index considerations

The Pointer widget uses a high z-index value (`2147483647`) to ensure it appears above other elements on your page. While this should work in most cases, you might encounter issues with certain popups, modals, or dialogs:

```typescript
// The Pointer widget's z-index
z-index: 2147483647  // Maximum possible z-index value
```

If you notice that your popups or dialogs are being hidden behind the Pointer widget, this is likely because:

1. Your popup's stacking context is isolated from the main document flow
2. The popup is using a relative z-index within a new stacking context
3. There are intermediate elements creating new stacking contexts

To resolve z-index conflicts:

* Ensure your popups are rendered at the root level of your document (e.g., using a portal)
* Check for elements with `transform`, `opacity`, or `filter` properties that might create new stacking contexts
* Review your modal/dialog library's documentation for z-index configuration options

Note: The Pointer widget intentionally uses the maximum possible z-index value to ensure it's always accessible to users. In most cases, your popups should appear below the widget for the best user experience.

### 6. Debug with DevTools

You can use DevTools to:

1. Verify your `PointerProvider` props are being passed correctly
2. Check if theme values are being properly consumed by child components
3. Inspect the computed styles to see which CSS rules are being applied

If you're still experiencing issues after trying these solutions, please [reach out](mailto:team@pointer.so) with:

* Your theme configuration code
* Screenshots of the styling issue
* Browser console errors (if any)
* Steps to reproduce the problem


# Get in touch
Source: https://docs.pointer.so/faqs/contact-us

Learn about all the ways you can contact us.

## General support

* Email [team@pointer.so](mailto:team@pointer.so)

* Join our [Discord community](https://dub.sh/pointer-community)

* Chat live [with a founder](https://cal.com/nealchopra/chat)

## Reporting bugs

* Join our [Discord community](https://dub.sh/pointer-community)

## Requesting a feature

* Join our [Discord community](https://dub.sh/pointer-community)

## Billing and plans

* Email [team@pointer.so](mailto:team@pointer.so)


# Credits
Source: https://docs.pointer.so/faqs/credits

Learn how credits work in Pointer.

## Overview

Pointer uses a credit-based system to manage and track usage across different features and operations.

Credits are the primary currency for using Pointer's features, ensuring fair and transparent usage tracking.

<Note>
  Oftentimes, 1 chat message is equivalent to 1 credit, and 1 guide is
  equivalent to 4 credits. This is a strong estimate based on testing, but the
  actual cost may vary depending on certain factors (e.g., conversation length,
  knowledge base size, etc.).
</Note>

## Credit costs

**1 chat message is equivalent to 1 credit.** This is usually for simple question-answer interactions. For example, a question like "What's the purpose of this function?" would typically be 1 credit.

**1 guide is equivalent to 4 credits.** This is for more complex questions that require a more detailed explanation. Most guides are usually 4-5 steps, which would typically cost 4 credits. For more complex guides, cost may be higher.

A typical 4-credit guide might look like this:

* User: "How do I create a new project?"
* Guide steps:
  * Step 1: "Navigate to the 'Projects' page in the dashboard."
  * Step 2: "Click on the 'New Project' button."
  * Step 3: "Enter the project name."
  * Step 4: "Enter the project description."
  * Step 5: "Click on the 'Create' button."

## Monthly credits

* Pro plan: 1,500 credits
* Growth plan: 5,000 credits

Consider our enterprise plan if you need more credits. To learn more, [contact us](mailto:team@pointer.so).

## Emergency credits and overages

If you're running low on credits or need additional capacity, we offer immediate credit purchases. Typically, we charge 2-3x the normal rate for overages.

## Additional notes

For all plans, credits reset at the beginning of your billing cycle. However, credits that are purchased separately do not reset.

All credit purchases are processed securely through Stripe. View our [billing page](https://app.pointer.so/settings?tab=billing) for more details.

If you have any questions, [contact us](mailto:team@pointer.so).


# Pricing
Source: https://docs.pointer.so/faqs/pricing

Your questions about pricing, answered. Still need help? <a href='mailto:team@pointer.so'>Contact us</a>.

<AccordionGroup>
  <Accordion title="How do I know what plan is right for me?" defaultOpen={false}>
    Calculate your monthly needs based on your current support volume. Number of support tickets per month \* 10 = number of credits you’ll need.

    Consider Enterprise if you need unlimited views, advanced security features, or have a large team requiring custom permissions and roles. If you're interested in the Enterprise plan, [contact us](mailto:team@pointer.so).
  </Accordion>

  {" "}

  <Accordion title="Is pricing based on users or projects?" defaultOpen={false}>
    Billing is project-dependent, not user-dependent. Every project you have will
    be billed separately, allowing flexibility for teams with multiple products or
    applications. To change your plan, navigate to the [Billing tab
    ](https://app.pointer.so/settings?tab=billing)of our Settings page.&#x20;
  </Accordion>

  {" "}

  <Accordion title="How do upgrades and downgrades work?" defaultOpen={false}>
    Upgrades and downgrades take effect at the end of your current monthly billing
    period. You can adjust your plan as your needs change. To change your plan,
    navigate to the [Billing tab ](https://app.pointer.so/settings?tab=billing)of
    our Settings page.&#x20;
  </Accordion>

  {" "}

  <Accordion title="What happens if I need more credits?" defaultOpen={false}>
    We charge overages at 2-3x the base rate per request. You can purchase
    additional credits last minute to continue using Pointer without interruption.
  </Accordion>

  {" "}

  <Accordion title="Do you offer a free tier?" defaultOpen={false}>
    While we don't offer a free tier, we do offer a 7-day free trial for all new users.
  </Accordion>

  <Accordion title="Is it possible to remove the Pointer branding?" defaultOpen={false}>
    The terms of all of our plans ask that users keep the Pointer branding in the widget (see [our terms](https://pointer.so/terms) for more details). If you need to white label Pointer, it can be offered as an add-on to enterprise plans.
  </Accordion>
</AccordionGroup>


# Composite flows
Source: https://docs.pointer.so/flows/composite-flow

Learn to create onboarding experiences with welcome screens and checklists.

## Overview

Composite flows are comprehensive onboarding experiences that guide new users through your product. Unlike simple flows that focus on a single feature, composite flows combine a welcome screen, multiple guided tours, and a progress checklist to create a complete product introduction.

These flows provide a structured yet flexible way for users to learn your product, allowing them to explore features at their own pace while ensuring they discover all key functionality.

## When to use composite flows

* **For new user onboarding:** Create a guided introduction to your product that helps users get started quickly. This improves activation rates by ensuring users discover key features from day one.
* **For major releases:** Introduce existing users to multiple new features after a significant update. This increases feature adoption by highlighting what's new.
* **For trial-to-paid conversion:** Guide trial users through your product's most valuable features before their trial expires. This improves conversion rates by showcasing your product's full value.
* **For user re-engagement:** Welcome back dormant users with a refresher on key features and introduction to what's new. This helps reactivate users who haven't logged in recently.

## How composite flows work

When a composite flow is triggered, users experience:

1. **Welcome screen:** First, a welcome modal appears with a friendly introduction to the onboarding experience
2. **Checklist display:** After clicking the welcome button, a checklist appears showing all available tours
3. **Self-directed exploration:** Users can choose which features to explore in any order
4. **Progress tracking:** The checklist shows which tours have been completed
5. **Completion:** When all tours are finished, the onboarding experience is complete

This creates a guided yet self-paced learning experience that respects users' preferences while ensuring feature discovery.

## Composite flow structure

### 1. Flow definition

First, define the flow itself with its basic properties:

```typescript
const onboardingFlow = {
  id: "new-user-onboarding",    // Unique identifier
  type: "composite",            // Specifies this as a composite flow
  name: "New user onboarding",  // Display name
  description: "Welcome to our platform!" // Optional description
};
```

### 2. Welcome modal

The welcome modal introduces users to your product and sets expectations for the onboarding:

```typescript
welcome: {
  title: "Hey there 👋",                // Main headline
  subtitle: "Welcome to Pointer!",   // Subheading
  description: "Let's take a quick, interactive tour of our platform.", // Detailed description
  image: {
    light: "/welcome-image-light.svg",  // Image shown in light mode
    dark: "/welcome-image-dark.svg"     // Image shown in dark mode
  },
  buttonText: "Take a tour",           // Call-to-action button text
}
```

### 3. Subflows

Subflows are the individual guided tours that make up your onboarding experience. Each subflow can be either:

**Guided tour subflows** — Step-by-step walkthroughs of specific features:

```typescript
subflows: [
  {
    id: "dashboard-tour",
    type: "simple",
    name: "Explore the dashboard",
    description: "Learn about your dashboard",
    page: "/dashboard",
    buttonText: "Start tour",
    allowRetrigger: true, // Optional: allow users to retake the tour
    steps: [
      {
        id: "dashboard-overview",
        type: "guided", // or "self-paced"
        position: "dashboard-header",
        content: {
          description: "This is your main dashboard.",
        },
        action: { type: "click" }, // Optional interaction
        showCloseButton: true // Optional close button
      }
    ]
  }
]
```

**Button-link subflows** — Direct links to external resources like documentation:

```typescript
{
  id: "documentation",
  type: "simple",
  name: "View docs",
  description: "Check out our documentation",
  buttonText: "View docs",
  buttonLink: "https://docs.pointer.so" // External URL
}
```

### 4. Checklist configuration

The checklist helps users track their progress through the onboarding experience:

```typescript
checklistConfig: {
  header: "Getting started 👋",
  position: "right", // "left", "right", "top", "bottom", "top-start", "top-end", "bottom-start", "bottom-end"
  triggerId: "show-checklist", // Optional element ID to trigger checklist
  offset: 10, // Optional offset, if using a triggerId
  minimizable: true,
}
```

By default, checklists appear in the bottom-right corner of the screen:

![images/pointer-checklist.png](https://mintlify.s3.us-west-1.amazonaws.com/pointer-c79e5938/images/pointer-checklist.png)

For more control over the checklist's position, you can use a manual trigger. This is especially useful when you want to integrate the checklist with your UI (e.g., in a sidebar) and create a more native feel. Check out how [Knowt](https://knowt.com) (ed-tech, 3.5+ million users) customizes the checklist:

![images/knowt-checklist.png](https://mintlify.s3.us-west-1.amazonaws.com/pointer-c79e5938/images/knowt-checklist.png)

## Using cross-page flows

Composite flows can guide users across multiple pages of your application. When a subflow's page property differs from the current page, Pointer will:

1. Navigate the user to the specified page
2. Wait for the page to load
3. Start the guided tour on the new page

This creates a seamless onboarding experience that spans your entire application.

## Triggering composite flows

Like simple flows, composite flows can be triggered via the `useFlow` hook. See our [Triggers](https://docs.pointer.so/flows/triggers) page for details.

## Complete example

Here's a complete example of a composite flow for onboarding new users:

```typescript
const onboardingFlow = {
  id: "new-user-onboarding",
  type: "composite",
  name: "New user onboarding",
  
  // Welcome modal
  welcome: {
    title: "Hey there 👋",        
    subtitle: "Welcome to Pointer!",
    description: "Let's take a quick, interactive tour of our platform.",
    image: "/welcome-image.svg",     
    buttonText: "Take a tour",          
  }
  
  // Subflows
  subflows: [
    // Dashboard tour
    {
      id: "dashboard-tour",
      type: "simple",
      name: "Explore the dashboard",
      description: "Learn how to navigate your dashboard",
      page: "/dashboard",
      buttonText: "Explore dashboard",
      steps: [
        {
          id: "dashboard-overview",
          type: "self-paced" // for informational steps; for action steps, use 'guided'
          position: "dashboard-header",
          content: {
            description: "This is your main dashboard where you can see all your projects and activities."
          }
        },
        {
          id: "metrics-panel",
          type: "guided",
          position: "metrics-panel",
          content: {
            description: "Here you can track your project metrics and performance."
          }
        }
      ]
    },
    
    // Documentation link
    {
      id: "documentation",
      type: "simple",
      name: "View docs",
      description: "Check out our documentation.",
      buttonText: "View docs",
      buttonLink: "https://docs.pointer.so"
    }
  ],

  // Checklist configuration
  showChecklist: true,               
  checklistConfig: {
    header: "Getting started 👋", 
    position: "right",            
    minimizable: true,  
  }
};
```

## Best practices

* **Limit the number of subflows:** Keep your onboarding focused by including only 3-5 essential tours. Too many options can overwhelm users.
* **Order subflows logically:** Arrange tours in a natural progression, with foundational features first and advanced features later.
* **Make descriptions clear:** Each subflow should have a concise description explaining what users will learn.
* **Use visual cues:** Include images in your welcome modal to make it engaging and set expectations.
* **Allow skipping:** Don't force users to complete every tour; let them pick what's relevant to them.
* **Consider user segments:** Create different onboarding flows for different user types or roles.
* **Test thoroughly:** Verify your composite flow works across different devices, browsers, and screen sizes.

## Next steps

* Learn about [simple flows](https://docs.pointer.so/flows/simple-flow) for focused guided tours
* Explore [triggers](https://docs.pointer.so/flows/triggers) to control when flows appear


# Getting started
Source: https://docs.pointer.so/flows/getting-started

Learn how to set up interactive onboarding and guided product tours.

## Overview

Interactive flows help users discover and learn your product through step-by-step guidance. Unlike our AI chat and interactive guides, flows require explicit configuration from developers, giving you precise control over the user experience.

With Pointer's flows, you can:

* Onboard new users with guided tours of your product
* Highlight new features or important functionality
* Guide users through complex workflows
* Increase feature adoption and user engagement
* Reduce support tickets by proactively educating users

Flows are fully customizable and can be triggered automatically (when a user visits a specific page or meets certain conditions) or manually (when a user clicks a button).

We're giving flows their own section because they require additional configuration and are designed for specific scenarios\\\\!

<Note>
  Note: We're working on a visual editor and browser extension to make flow creation even easier. For now, flows are configured through code, giving you more flexibility.
</Note>

## Getting started

<Steps>
  <Step title="Grab an API key from the Pointer dashboard.">
    Login to the [Pointer dashboard](https://app.pointer.so), then create a project. Two keys will be automatically generated for you — a production and development key. Copy the development key and store it.
  </Step>

  <Step title="Install the Pointer SDK using your preferred package manager.">
    <CodeGroup>
      ```bash npm
      npm install pointer-sdk
      ```

      ```bash pnpm
      pnpm add pointer-sdk
      ```

      ```bash yarn
      yarn add pointer-sdk
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure your environment variables.">
    Add the appropriate Pointer API key into your `.env` file.

    ```bash
    POINTER_API_KEY=pt_dev_*********************
    ```

    <Note>
      Note that there are two types of API keys: development and production.

      * **Development keys** (`pt_dev_*`):
        * For local development only
        * No origin restrictions
        * Stricter rate limits
      * **Production keys** (`pt_live_*`):
        * Required for deployed applications
        * Must specify allowed origin domains
        * Domains must be valid (e.g., example.com)
    </Note>
  </Step>

  <Step title="Configure the provider">
    Add the `PointerFlowProvider` to wrap your app, typically in a layout file that contains your authenticated routes:

    ```typescript
    import { PointerFlowProvider } from "pointer-sdk";

    function App() {
    	return (
    		<PointerFlowProvider
      		 apiKey={process.env.POINTER_API_KEY!}
             flows={myFlows}
            >
      		  {children}
    		</PointerFlowProvider>
    	);
    }
    ```

    See more info below on configuring the `PointerFlowProvider`.
  </Step>
</Steps>

## Next steps

Congrats! You've set up the `PointerFlowProvider`, and are now ready to start configuring flows.

* [Simple flows](https://docs.pointer.so/flows/simple-flow) — focused, step-by-step guided tours
* [Composite flows](https://docs.pointer.so/flows/composite-flow) — comprehensive onboarding experiences


# Simple flows
Source: https://docs.pointer.so/flows/simple-flow

Learn to create step-by-step, guided tours. 

## Overview

Simple flows are focused, step-by-step guided tours that walk users through specific features or tasks in your application.

Unlike comprehensive [onboarding flows](https://docs.pointer.so/flows/composite-flow), simple flows tackle one specific goal—like creating a project, setting up a profile, or understanding a dashboard. They provide contextual guidance right when and where users need it.

## When to use simple flows

* **For new features:** Introduce users to functionality they haven't used before. Instead of hoping users discover new features, proactively show them how to use them.
* **For complex processes:** Guide users through multi-step workflows that might otherwise cause confusion. This reduces friction and increases completion rates for important tasks.
* **For converting free users:** Highlight premium functionality to free users with targeted tours. Show them what they're missing to encourage upgrades.
* **For contextual help:** Provide in-app assistance for specific tasks when users request it. This reduces support tickets and increases user confidence.

## How simple flows work

When a simple flow is triggered, it guides users through a series of steps:

1. **Highlighting:** The flow highlights a specific UI element on your page
2. **Instruction:** It displays contextual instructions for that element
3. **Action:** It waits for the user to complete the specified action (click, input, etc.)
4. **Progression:** After the action is completed, it automatically moves to the next step
5. **Completion:** When all steps are finished, the flow ends

This creates a guided, interactive experience that ensures users successfully complete each action before moving forward.

## Simple flow structure

### 1. Flow definition

First, define the flow itself with its basic properties:

```typescript
const featureTour = {
  id: "feature-tour",          // Unique identifier for your flow
  type: "simple",              // Specifies this is a simple flow
  name: "Feature tour",        // Name of the tour
  description: "Learn how to use our key features" // Optional description
};
```

The `id` is particularly important — it's how you'll reference this flow when triggering it manually.

### 2. Steps

Steps guide users through the feature. Each step highlights a specific element and provides instructions.

```typescript
steps: [
  {
    id: "create-project-step",   // Unique identifier for this step
    type: "guided",              // Step type: 'guided' | 'self-paced'
    position: "create-button",   // Element ID to highlight
    content: {
      description: "Click this button to create a project." // Description of the step
    }
	
  }
]
```

The `position` value should match the ID of an element in your application. Pointer will find this element and highlight it during the tour.

The `type` can be either guided or self-paced:

* **Guided steps** automatically progress when the user completes the specified action.
* **Self-paced steps** give users more control over their progress. They are typically used for documentation-style guides or tips.

![images/step-types.png](https://mintlify.s3.us-west-1.amazonaws.com/pointer-c79e5938/images/step-types.png)

<Note>
  Note: When configuring a step, you'll see more props available. However, those are only used when creating a composite flow. Any other props added when creating a simple flow will not be visible.
</Note>

### 3. Actions

Actions make your flow interactive, defining what the user needs to do to proceed to the next step.

```typescript
{
  id: "create-project-step",
  type: "guided",
  position: "create-button",
  content: {
    description: "Click this button to create a new project."
  },
  action: {
    type: "click" // Wait for user to click before proceeding
  }
}
```

Supported action types are:

* `click` — wait for the user to click the highlighted element
* `input` — wait for the user to type in a form field

## Creating page-specific flows

Often, you'll want flows to appear only on specific pages. You can achieve this by adding a `page` property:

```typescript
const profileTour = {
  id: "profile-tour",
  type: "simple",
  name: "Profile setup",
  page: "/profile",          // This flow will only activate on the profile page
  steps: [
    // Steps specific to the profile page
  ]
};
```

The flow will only activate when the user is on the specified page, ensuring contextual relevance.

## Creating cross-page flows

Sometimes you need to guide users across multiple pages of your application. This is possible by specifying different pages for individual steps and using navigate actions.

```typescript
steps: [
  // Step on the dashboard page
  {
    id: "find-profile",
    type: "guided",
    position: "profile-link",
    page: "/dashboard",      // This step appears on the dashboard page
    content: {
      description: "Click here to navigate to your profile settings."
    },
    action: { type: "click" }
  },
  
  // Next step on the profile page
  {
    id: "edit-avatar",
    type: "guided",
    position: "avatar-upload",
    page: "/profile",        // This step appears on the profile page
    content: {
      description: "Upload a profile picture by clicking here."
    },
    action: { type: "click" }
  }
]
```

Pointer automatically handles the page transitions, waiting for the new page to load before continuing the flow.

<Note>
  Note: for cross-page flows, we recommend setting up a [composite flow](https://docs.pointer.so/flows/composite-flow). Simple flows are ideal for quick, single page flows.
</Note>

## Creating external link flows

Not all guidance needs to happen within your app. You can create flows that direct users to external resources like documentation. This creates a simple flow with just a button that opens the specified URL. These are only available in [composite flows](https://docs.pointer.so/flows/composite-flow).

## Triggering simple flows

You can trigger flows using the `useFlow` hook. Check out the Triggers page for more info.

## Complete example

Here's a complete example of a simple flow for introducing users to a dashboard:

```typescript
const dashboardTour = {
  id: "dashboard-tour",
  type: "simple",
  name: "Dashboard intro",
  page: "/dashboard",
  
  steps: [
    // Show metrics panel
    {
      id: "metrics-step",
      type: "guided",
      position: "metrics-panel",
      content: {
        description: "Here you can see key metrics about your account activity and progress."
      },
      action: { type: "click" }
    },
    // Create a project
    {
      id: "create-project-step",
      type: "guided",
      position: "create-project-button",
      content: {
        description: "Let's create your first project. Click this button to get started."
      },
      action: { type: "click" }
    }
  ]
};
```

## Best practices

* **Focus on one goal** per flow. Each flow should help users accomplish a specific task.
* **Keep instructions concise**. Tell users exactly what to do in as few words as possible.
* **Explain the "why"** not just the "what." Help users understand why each step matters.
* **Test on multiple devices** to ensure your flows work well on different screen sizes.
* **Validate user actions** to ensure users successfully complete each step before moving forward.
* **Consider keyboard navigation** for users who don't use a mouse.
* **Avoid blocking critical UI** elements with your flow tooltips.

## Next steps

* Learn about [composite flows](https://docs.pointer.so/flows/composite-flow) for comprehensive onboarding experiences
* Explore [triggers](https://docs.pointer.so/flows/triggers) to control when flows appear


# Flow triggers
Source: https://docs.pointer.so/flows/triggers

Learn how to control when and how flows appear to your users.

## What are flow triggers?

Flow triggers determine when and how your interactive flows appear to users. They give you precise control over the user experience, ensuring flows appear at the right moment for maximum impact.

## Using the useFlow hook

The `useFlow` hook allows you to trigger and control flows. Import and implementation is as follows:

```typescript
import { useFlow } from "pointer-sdk";

function HelpButton() {
  const { startFlow } = useFlow();
  
  return (
    <button 
      onClick={() => startFlow("feature-tour")} 
      className="help-button"
    >
      Start Tour
    </button>
  );
}
```

To start a flow, use the `startFlow` method. The `startFlow` function takes the unique ID of the flow you want to start. This ID must match the `id` property in your flow configuration.

## Available methods

The useFlow hook provides the following methods:

```typescript
const {
  startFlow,      // Start a specific flow by ID
  showChecklist,  // Show the checklist for a composite flow
  getFlowProgress,// Get progress info for a specific flow
} = useFlow();
```

### startFlow

Starts a specific flow by its ID. Returns a promise that resolves when the flow is ready.

```typescript
const { startFlow } = useFlow();

function StartButton() {
  const handleStart = async () => {
    try {
      await startFlow("onboarding-flow");
      console.log("Flow started successfully");
    } catch (error) {
      console.error("Failed to start flow:", error);
    }
  };

  return <button onClick={handleStart}>Start Onboarding</button>;
}
```

### showChecklist

Shows the checklist UI for a composite flow. This is typically used for onboarding flows with multiple subflows.

```typescript
const { showChecklist } = useFlow();

function OnboardingWidget() {
  return (
    <button onClick={() => showChecklist("main-onboarding")}>
      Show Onboarding Checklist
    </button>
  );
}
```

### getFlowProgress

Returns detailed progress information for a specific flow, including completion status and step progress.

```typescript
const { getFlowProgress } = useFlow();

function FlowProgressIndicator({ flowId }) {
  const progress = getFlowProgress(flowId);

  return (
    <div>
      <div className="progress-bar">
        <div 
          className="progress-fill"
          style={{ width: `${progress.percentage}%` }}
        />
      </div>
      <div className="stats">
        <p>Completed: {progress.isCompleted ? 'Yes' : 'No'}</p>
        <p>Step: {progress.currentStep + 1} of {progress.totalSteps}</p>
        <p>Progress: {progress.percentage}%</p>
      </div>
    </div>
  );
}
```

## Trigger priority and conflicts

When multiple flows have triggers and their conditions are met simultaneously, Pointer uses these rules to determine which flow to show:

1. Only one flow can be active at a time
2. If a flow is already active, new triggers are ignored
3. If multiple flows trigger simultaneously, the first one registered takes priority

You can manually control trigger priority by carefully ordering your flows when registering them with the provider.

## Best practices

* **Be conservative with automatic triggers.** Too many automatic popups create a frustrating experience. Use them sparingly for truly important moments.
* **Consider user context.** Trigger flows when users are most likely to need them and can focus on them.
* **Implement appropriate delays.** Give users time to get oriented before showing guidance.
* **Use appropriate show limits.** One-time onboarding should show once, while feature guidance might benefit from occasional repetition.
* **Test thoroughly.** Verify trigger conditions work as expected in different scenarios.
* **Provide opt-out mechanisms.** Always let users dismiss flows they don't want to see.
* **Track completion metrics.** Monitor how many users complete triggered flows to optimize timing and relevance.

## Next steps

* Learn about [simple flows](https://docs.pointer.so/flows/simple-flow) for focused guided tours
* Learn about [composite flows](https://docs.pointer.so/flows/composite-flow) for comprehensive onboarding experiences


# Introduction
Source: https://docs.pointer.so/introduction

Learn more about Pointer.

## What is Pointer?

[Pointer](https://pointer.so) is a platform that guides users through software products in real-time.&#x20;

When users get stuck, Pointer shows them exactly what to do. No more support tickets, doc searches, or annoyed emails.

To get started, check out our [Quickstart](https://docs.pointer.so/quickstart) guide. If you'd like a .txt version of our docs to paste into an LLM, visit [this page](https://docs.pointer.so/llms-full.txt).

## How it works

<iframe width="100%" height="390" src="https://www.youtube.com/embed/11s10d9Y4UA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

## Key features

<CardGroup cols={2}>
  <Card title="In-app walkthroughs" icon="bullseye-pointer">
    * Visual step-by-step guides that show users exactly what to do.
  </Card>

  <Card title="AI chat support" icon="messages">
    * Instant answers to any question about your product, right where users need them.
  </Card>

  <Card title="Analytics" icon="chart-line">
    Track user questions and identify where they need more help.
  </Card>

  <Card title="Knowledge base" icon="book-open">
    Connect your documentation and support content to power accurate AI responses.
  </Card>
</CardGroup>

## Why Pointer?

<Accordion title="For developers" defaultOpen={false} icon="code">
  Build powerful user assistance in minutes, right alongside your app code. Our SDK automatically tracks UI elements — no manual tagging, no infrastructure headaches, just ship features faster. Check out our [Quickstart](https://docs.pointer.so/quickstart) guide to get started.
</Accordion>

<Accordion title="For product teams" defaultOpen={false} icon="cubes">
  Skip the clunky onboarding flows. Create interactive guides that adapt to each user's context and keep up with your rapid product changes. Get data on what users actually struggle with.
</Accordion>

<Accordion title="For support teams" defaultOpen={false} icon="headset">
  Answering the same "How do I..." question for the millionth time? Let AI handle the repetitive stuff while your team tackles complex issues. All while learning what documentation you really need.
</Accordion>

<Accordion title="For growth teams" defaultOpen={false} icon="chart-mixed">
  Transform confused signups into power users. Our interactive guides ensure users discover value quickly, engage with key features, and actually stick around.
</Accordion>

<Accordion title="For engineering leaders" defaultOpen={false} icon="webhook">
  Your engineers should build core product, not support tools. Pointer integrates seamlessly with your stack, scales with your needs, and keeps data under your control. Learn more about security [here](https://pointer.so/security).
</Accordion>


# Quickstart
Source: https://docs.pointer.so/quickstart

Get started with Pointer in under 5 minutes.

## Prerequisites

* Node.js 16.0 or later

* A React-based application (React 18+)

## Installation

<Steps>
  <Step title="Grab an API key from the Pointer dashboard.">
    Login to the [Pointer dashboard](https://app.pointer.so), then create a project. Two keys will be automatically generated for you — a production and development key. Copy the development key and store it.
  </Step>

  <Step title="Install the Pointer SDK using your preferred package manager.">
    <CodeGroup>
      ```bash npm
      npm install pointer-sdk
      ```

      ```bash pnpm
      pnpm add pointer-sdk
      ```

      ```bash yarn
      yarn add pointer-sdk
      ```
    </CodeGroup>
  </Step>

  <Step title="Configure your environment variables.">
    Add the appropriate Pointer API key into your `.env` file.

    ```bash
    POINTER_API_KEY=pt_dev_*********************
    ```

    <Note>
      Note that there are two types of API keys: development and production.

      * **Development keys** (`pt_dev_*`):
        * For local development only
        * No origin restrictions
        * Stricter rate limits

      * **Production keys** (`pt_live_*`):
        * Required for deployed applications
        * Must specify allowed origin domains
        * Domains must be valid (e.g., example.com)

      API keys are only shown in full during creation. After that, only the last 4 characters will be visible.

      API keys are public on the client-side. Further authentication occurs in the background to verify each user and prevent session hijacking. For more information, read our [Security page](https://pointer.so/security).
    </Note>
  </Step>

  <Step title="Wrap your app with the PointerProvider.">
    In your root file, (e.g., `layout.tsx`, `index.tsx`, `_app.tsx`) wrap your app with the `PointerProvider`.

    If you want to set up onboarding flows, see the [Onboarding](https://docs.pointer.so/features/onboarding) section.

    ```typescript
    import { PointerProvider } from 'pointer-sdk';

    function App() {
      return (
          <PointerProvider apiKey={process.env.POINTER_API_KEY!}>
            {children}
          </PointerProvider>
      );
    }
    ```

    <Tip>
      For optimal performance, place the `PointerProvider` as close as possible to its child components.
    </Tip>
  </Step>

  <Step title="Test the integration.">
    Once you run your app, Pointer widget should now appear in the bottom-right corner. Head to the [Developers page](https://app.pointer.so/developers) in the dashboard and click "Verify connection" to ensure everything is working correctly.
  </Step>
</Steps>

## Styling

You have complete control over the styling of the onboarding flow. For more information, see the [Styling](https://docs.pointer.so/features/styling) section.

## Framework-specific setup

<Note>
  Pointer currently works with any React-based application. Support for Vue,
  Svelte, and other frontend frameworks is in development.
</Note>

### Next.js

If using the `app` router:

```typescript app/layout.tsx
import { PointerProvider } from "pointer-sdk";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html>
      <body>
        <PointerProvider apiKey={process.env.NEXT_PUBLIC_POINTER_API_KEY!}>
          {children}
        </PointerProvider>
      </body>
    </html>
  );
}
```

If using the `pages` router:

```typescript pages/_app.tsx
import { PointerProvider } from "pointer-sdk";
import type { AppProps } from "next/app";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <PointerProvider apiKey={process.env.NEXT_PUBLIC_POINTER_API_KEY!}>
      <Component {...pageProps} />
    </PointerProvider>
  );
}
```

### Remix

```typescript app/root.tsx
import { PointerProvider } from "pointer-sdk";

export default function App() {
  return (
    <html>
      <body>
        <PointerProvider apiKey={process.env.POINTER_API_KEY!}>
          <Outlet />
        </PointerProvider>
      </body>
    </html>
  );
}
```


# API reference
Source: https://docs.pointer.so/user-tracking/api-reference

Complete reference for Pointer's user tracking API.

## Data types

<Tabs>
  <Tab title="EndUserData">
    The core type for identifying a user in your application.

    ```typescript
    interface EndUserData {
      /**
       * Required unique identifier for the user.
       * Use a stable, persistent ID from your authentication system.
       */
      userId: string;
      
      /**
       * Optional full name of the user.
       */
      name?: string;
      
      /**
       * Optional email address of the user.
       */
      email?: string;
      
      /**
       * Optional URL to the user's avatar image.
       */
      avatarUrl?: string;
      
      /**
       * Optional HMAC signature for verifying user identity.
       * This should be generated server-side using your Pointer secret key.
       */
      hmacSignature?: string;
      
      /**
       * Optional custom data for storing additional user information.
       * This can include any JSON-serializable data.
       */
      customData?: Record<string, any>;
    }
    ```

    <Properties>
      <Property name="userId" type="string" required>
        A stable, unique identifier for the user from your authentication system.
      </Property>

      <Property name="name" type="string">
        The user's full name.
      </Property>

      <Property name="email" type="string">
        The user's email address.
      </Property>

      <Property name="avatarUrl" type="string">
        URL to the user's profile picture or avatar.
      </Property>

      <Property name="hmacSignature" type="string">
        Server-generated signature to verify the user's identity.
      </Property>

      <Property name="customData" type="object">
        Any additional JSON-serializable data you want to associate with the user.
      </Property>
    </Properties>
  </Tab>

  <Tab title="UserEvent">
    Used for tracking custom events in your application.

    ```typescript
    interface UserEvent {
      /**
       * The type/category of the event.
       * Examples: 'FEATURE_USAGE', 'ACCOUNT_UPDATE', 'WORKFLOW_COMPLETION'
       */
      eventType: string;
      
      /**
       * The specific name of the event.
       * Examples: 'export_report', 'subscription_changed', 'completed_setup'
       */
      eventName: string;
      
      /**
       * Optional additional context for the event.
       * This can include any JSON-serializable data.
       */
      metadata?: Record<string, any>;
    }
    ```

    <Properties>
      <Property name="eventType" type="string" required>
        Category of the event (e.g., 'FEATURE\_USAGE', 'ACCOUNT\_UPDATE').
      </Property>

      <Property name="eventName" type="string" required>
        Specific action or milestone (e.g., 'export\_report', 'subscription\_changed').
      </Property>

      <Property name="metadata" type="object">
        Optional additional context for the event.
      </Property>
    </Properties>
  </Tab>
</Tabs>

## React hook API

### useUser

<CodeGroup>
  ```typescript Types
  function useUser(): {
    /**
     * The current user data, or undefined if no user is set.
     */
    userData: EndUserData | undefined;
    
    /**
     * Set or update the user data.
     * This will replace any existing user data.
     */
    setUserData: (userData: EndUserData) => void;
    
    /**
     * Clear all user data.
     * This is typically used during logout.
     */
    clearUserData: () => void;
    
    /**
     * Track a custom event.
     */
    trackEvent: (event: UserEvent) => Promise<void>;
    
    /**
     * Update the overall onboarding status for the user.
     */
    updateOnboardingStatus: (completed: boolean) => Promise<void>;
    
    /**
     * Update progress for a specific onboarding step.
     */
    updateOnboardingProgress: (progress: OnboardingProgress) => Promise<void>;
  }
  ```

  ```typescript Example
  import { useUser } from 'pointer-sdk';
  import { useEffect } from 'react';

  function UserProfile() {
    const { 
      userData,
      setUserData,
      clearUserData,
      trackEvent
    } = useUser();
    
    // Track profile view
    useEffect(() => {
      trackEvent({
        eventType: 'PROFILE',
        eventName: 'profile_viewed'
      });
    }, []);
    
    // Handle profile update
    const updateProfile = (newData) => {
      setUserData({
        ...userData,
        name: newData.name,
        email: newData.email,
        customData: {
          ...userData?.customData,
          preferences: newData.preferences
        }
      });
      
      trackEvent({
        eventType: 'PROFILE',
        eventName: 'profile_updated'
      });
    };
    
    return (
      <div>
        {/* Profile UI */}
      </div>
    );
  }
  ```
</CodeGroup>

## Direct API methods

For use outside of React components or for non-React applications.

<ApiList>
  <ApiItem name="setUser" type="function">
    <Fragment slot="signature">
      ```typescript
      function setUser(userData: EndUserData): void
      ```
    </Fragment>

    <Fragment slot="description">
      Set or update the user data. This will replace any existing user data.
    </Fragment>

    <Fragment slot="example">
      ```typescript
      import { setUser } from 'pointer-sdk';

      function onLoginSuccess(user) {
        setUser({
          userId: user.id,
          name: user.name,
          email: user.email
        });
      }
      ```
    </Fragment>
  </ApiItem>

  <ApiItem name="getUserData" type="function">
    <Fragment slot="signature">
      ```typescript
      function getUserData(): EndUserData | undefined
      ```
    </Fragment>

    <Fragment slot="description">
      Get the current user data, or undefined if no user is set.
    </Fragment>

    <Fragment slot="example">
      ```typescript
      import { getUserData } from 'pointer-sdk';

      function checkUserStatus() {
        const userData = getUserData();
        if (userData) {
          console.log(`User ${userData.name} is logged in`);
        } else {
          console.log('No user is logged in');
        }
      }
      ```
    </Fragment>
  </ApiItem>

  <ApiItem name="clearUserData" type="function">
    <Fragment slot="signature">
      ```typescript
      function clearUserData(): void
      ```
    </Fragment>

    <Fragment slot="description">
      Clear all user data. This is typically used during logout.
    </Fragment>

    <Fragment slot="example">
      ```typescript
      import { clearUserData } from 'pointer-sdk';

      function handleLogout() {
        clearUserData();
        // Continue with logout process
      }
      ```
    </Fragment>
  </ApiItem>

  <ApiItem name="trackEvent" type="function">
    <Fragment slot="signature">
      ```typescript
      function trackEvent(event: UserEvent): Promise<void>
      ```
    </Fragment>

    <Fragment slot="description">
      Track a custom event.
    </Fragment>

    <Fragment slot="example">
      ```typescript
      import { trackEvent } from 'pointer-sdk';

      function exportReport(format) {
        // Export logic...
        
        trackEvent({
          eventType: 'FEATURE_USAGE',
          eventName: 'export_report',
          metadata: { format }
        });
      }
      ```
    </Fragment>
  </ApiItem>

  <ApiItem name="updateOnboardingStatus" type="function">
    <Fragment slot="signature">
      ```typescript
      function updateOnboardingStatus(completed: boolean): Promise<void>
      ```
    </Fragment>

    <Fragment slot="description">
      Update the overall onboarding status for the user.
    </Fragment>

    <Fragment slot="example">
      ```typescript
      import { updateOnboardingStatus } from 'pointer-sdk';

      function completeOnboarding() {
        updateOnboardingStatus(true);
        // Navigate to main app
      }
      ```
    </Fragment>
  </ApiItem>

  <ApiItem name="updateOnboardingProgress" type="function">
    <Fragment slot="signature">
      ```typescript
      function updateOnboardingProgress(progress: OnboardingProgress): Promise<void>
      ```
    </Fragment>

    <Fragment slot="description">
      Update progress for a specific onboarding step.
    </Fragment>

    <Fragment slot="example">
      ```typescript
      import { updateOnboardingProgress } from 'pointer-sdk';

      function completeProfileStep() {
        updateOnboardingProgress({
          step: 'profile_setup',
          completed: true
        });
        // Continue to next step
      }
      ```
    </Fragment>
  </ApiItem>
</ApiList>

## Props API

<Tabs>
  <Tab title="PointerProvider">
    ```typescript
    interface PointerProviderProps {
      /**
       * Your Pointer API key from the dashboard.
       */
      apiKey: string;
      
      /**
       * Optional user data to identify the current user.
       */
      userData?: EndUserData;
      
      /**
       * Optional first name of the user (legacy).
       * For new applications, use userData.name instead.
       * @deprecated
       */
      userFirstName?: string;
      
      // ... other props
    }
    ```
  </Tab>

  <Tab title="PointerFlowProvider">
    ```typescript
    interface PointerFlowProviderProps {
      /**
       * Your Pointer API key from the dashboard.
       */
      apiKey: string;
      
      /**
       * Optional user data to identify the current user.
       */
      userData?: EndUserData;
      
      /**
       * Optional first name of the user (legacy).
       * For new applications, use userData.name instead.
       * @deprecated
       */
      userFirstName?: string;
      
      /**
       * Your flow configurations.
       */
      flows: FlowConfig[];
      
      // ... other props
    }
    ```
  </Tab>
</Tabs>

## Flow completion behavior

When a user completes all steps in a flow, this completion is registered in their user data. Once a flow is registered as complete, it cannot be started again for that user, enabling one-time onboarding experiences.

## Error handling

<CodeGroup>
  ```typescript Try/Catch
  try {
    await trackEvent({
      eventType: 'FEATURE_USAGE',
      eventName: 'export_report'
    });
    console.log('Event tracked successfully');
  } catch (error) {
    console.error('Failed to track event:', error);
    // Handle error (retries, fallbacks, etc.)
  }
  ```

  ```typescript Async/Await
  async function trackUserEvent() {
    try {
      await trackEvent({
        eventType: 'FEATURE_USAGE',
        eventName: 'export_report'
      });
      return true;
    } catch (error) {
      console.error('Failed to track event:', error);
      return false;
    }
  }
  ```
</CodeGroup>

<Note>
  Most user tracking operations are designed to fail gracefully to prevent disrupting the user experience. Errors are logged but don't typically cause application failures.
</Note>

## Data persistence

User data is persisted in the following ways:

* **In-memory cache**: For fast access during the current session
* **Local storage**: For persistence across page reloads
* **Server**: For analytics and personalization

### Security considerations

* Sensitive data is never stored in `customData` field
* User data is only accessible within your application domain


# Event tracking
Source: https://docs.pointer.so/user-tracking/event-tracking

Track user interactions and progress in your application.

## Overview

Event tracking allows you to monitor how users interact with your application, track their progress through flows, and record important milestones. This data helps you understand user behavior, improve your product, and provide personalized experiences.

Pointer provides a flexible system for tracking:

* **Custom events**: Record any user interaction or important milestone
* **Flow completion**: Record which guided flows users have completed

## Tracking custom events

Custom events represent user interactions or milestones in your application. They can provide valuable insights into how users engage with your product.

<CodeGroup>
  ```typescript React hooks
  import { useUser } from 'pointer-sdk';

  function FeaturePage() {
    const { trackEvent } = useUser();
    
    const handleFeatureUsage = () => {
      // Your feature logic here
      
      // Track the event
      trackEvent({
        eventType: 'FEATURE_USAGE',
        eventName: 'export_report',
        metadata: {
          reportType: 'analytics',
          format: 'csv'
        }
      });
    };
    
    return (
      <button onClick={handleFeatureUsage}>
        Export Report
      </button>
    );
  }
  ```

  ```typescript Direct API
  import { trackEvent } from 'pointer-sdk';

  function handleSubscriptionChange(newPlan) {
    // Update subscription in your system
    
    // Track the event
    trackEvent({
      eventType: 'ACCOUNT_UPDATE',
      eventName: 'subscription_changed',
      metadata: {
        previousPlan: 'basic',
        newPlan: newPlan,
        annual: true
      }
    });
  }
  ```
</CodeGroup>

## Flow completion tracking

Flows are guided walkthroughs that help users accomplish specific tasks. The SDK tracks flow completion internally with no manual code required.

### Flow completion behavior

* Once a flow is registered as complete for a user, it cannot be started again for that user
* This allows you to create one-time onboarding experiences or prevent users from seeing the same guided tour multiple times

If you need to check whether a user has completed a specific flow in your UI, you can use the user's custom data which will contain flow completion information.

## Event schema

When tracking events, you can use the following schema properties:

<ResponseField name="eventType" type="string" required>
  Category of the event (e.g., `FEATURE_USAGE`, `ACCOUNT_UPDATE`)
</ResponseField>

<ResponseField name="eventName" type="string" required>
  Specific action or milestone (e.g., `export_report`, `subscription_changed`)
</ResponseField>

<ResponseField name="metadata" type="object" optional>
  Additional context for the event

  <Expandable title="Metadata example">
    ```json
    {
      "previousPlan": "basic",
      "newPlan": "premium",
      "annual": true,
      "discountApplied": "SUMMER20",
      "referralSource": "friend"
    }
    ```
  </Expandable>
</ResponseField>

<Note>
  All events are automatically associated with the current user and session, so you don't need to include user information in your event data.
</Note>

## Best practices

* **Be consistent with naming**: Use consistent naming conventions for event types and names to make analysis easier.

* **Include useful metadata**: Add relevant context through metadata, but avoid including sensitive information.

* **Track important milestones**: Focus on tracking meaningful interactions rather than every minor action.

* **Use for personalization**: Leverage tracking data to personalize the user experience based on their progress.


# Getting started
Source: https://docs.pointer.so/user-tracking/getting-started

Identify users and track their interactions with your app.

## Overview

User tracking allows you to identify users in your application, personalize their experience, and track their progress through onboarding flows and feature usage. This powerful feature enables you to:

* **User identity**: Maintain user identity across sessions for consistent experiences
* **Personalization**: Create personalized content and flows based on user data
* **Flow tracking**: Track completion of guided tours and onboarding steps
* **Event analytics**: Record custom events for detailed usage analytics

<Note>
  This feature is only available for users on Pro and Growth plans. To upgrade, please visit the [billing](https://app.pointer.so/settings?tab=billing) page in our dashboard.
</Note>

## Setup

Follow the steps below to quickly get started with user tracking:

<Steps>
  <Step title="Configure the PointerProvider with user data.">
    Pass user information to the `PointerProvider` or `PointerFlowProvider` when initializing:

    ```typescript
    import { PointerProvider } from 'pointer-sdk';

    function App() {
      return (
        <PointerProvider 
          apiKey={process.env.POINTER_API_KEY!}
          userData={{
            userId: "user_123",           // Required
            name: "Jane Smith",           // Optional
            email: "jane@example.com",    // Optional
            avatarUrl: "/avatar.png",     // Optional
            customData: {                 // Optional
              plan: "premium",
              companyId: "company_456"
            }
          }}
        >
          {children}
        </PointerProvider>
      );
    }
    ```

    <Note>
      At minimum, you must provide a `userId` to identify the user. Additional fields are optional but recommended for better personalization.
    </Note>
  </Step>

  <Step title="Manage user data dynamically with the useUser hook.">
    For dynamic user management in your components, use the `useUser` hook:

    ```typescript
    import { useUser } from 'pointer-sdk';

    function ProfilePage() {
      const { userData, setUserData, clearUserData } = useUser();
      
      // Display user information
      return (
        <div>
          <h1>Welcome, {userData?.name}</h1>
          <button onClick={() => clearUserData()}>Logout</button>
        </div>
      );
    }
    ```

    This hook provides reactive access to user data across your application.
  </Step>
</Steps>

## Managing user data

Pointer provides multiple ways to manage user data depending on your application's architecture.

<Tabs>
  <Tab title="React hooks">
    The `useUser` hook provides a simple interface for components to interact with user data:

    ```typescript
    import { useUser } from 'pointer-sdk';
    import { useEffect } from 'react';

    function AuthenticatedApp() {
      const { userData, setUserData, clearUserData } = useUser();
      
      // Set user data after login
      useEffect(() => {
        if (authState.isAuthenticated) {
          setUserData({
            userId: authState.user.id,
            name: authState.user.name,
            email: authState.user.email
          });
        }
      }, [authState.isAuthenticated]);
      
      // Clear user data on logout
      const handleLogout = () => {
        clearUserData();
        // Additional logout logic
      };
      
      return (
        <div>
          {/* Your app content */}
        </div>
      );
    }
    ```
  </Tab>

  <Tab title="Direct API methods">
    For non-React environments or for use outside of components, you can use the direct API methods:

    ```typescript
    import { setUser, getUserData, clearUserData } from 'pointer-sdk';

    // After authentication
    function onLoginSuccess(user) {
      setUser({
        userId: user.id,
        name: user.name,
        email: user.email
      });
      
      // Redirect or continue
    }

    // Before logout
    function onLogout() {
      clearUserData();
      // Continue with logout process
    }

    // Check current user
    function getCurrentUser() {
      const userData = getUserData();
      return userData;
    }
    ```
  </Tab>
</Tabs>

### User data persistence

User data is automatically persisted in the browser's localStorage. This ensures that users remain identified across page refreshes and new sessions until explicitly logged out.

<Warning>
  Be careful not to store sensitive information in the user's customData field as it will be persisted to localStorage.
</Warning>

<Note>
  The SDK automatically manages the storage and retrieval of user data, so you don't need to handle persistence yourself.
</Note>

## Next steps

* [Track events](/user-tracking/event-tracking) — Learn how to capture user actions and milestones
* [Integration examples](/user-tracking/integration-examples) — Examples for common frameworks and auth systems
* [API reference](/user-tracking/api-reference) — Detailed API documentation


# Integration examples
Source: https://docs.pointer.so/user-tracking/integration-examples

Examples of integrating user tracking with popular frameworks and authentication systems.

## Overview

This guide provides practical examples for integrating Pointer's user tracking with popular frameworks and authentication systems. These examples will help you quickly implement user tracking in your specific tech stack.

## React integration examples

### Next.js

If using the `app` router:

```typescript
// app/layout.tsx
import { PointerProvider } from 'pointer-sdk';
import { getSession } from '@/lib/auth';

export default async function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  // Get user session server-side
  const session = await getSession();
  
  const userData = session?.user ? {
    userId: session.user.id,
    name: session.user.name,
    email: session.user.email,
    avatarUrl: session.user.image,
    customData: {
      plan: session.user.plan,
      teamId: session.user.teamId
    }
  } : undefined;
  
  return (
    <html>
      <body>
        <PointerProvider 
          apiKey={process.env.NEXT_PUBLIC_POINTER_API_KEY!}
          userData={userData}
        >
          {children}
        </PointerProvider>
      </body>
    </html>
  );
}
```

If using the `pages` router:

```typescript
// pages/_app.tsx
import { PointerProvider } from 'pointer-sdk';
import { useSession } from 'next-auth/react';

export default function App({ Component, pageProps }) {
  const { data: session } = useSession();
  
  const userData = session?.user ? {
    userId: session.user.id,
    name: session.user.name,
    email: session.user.email,
    avatarUrl: session.user.image
  } : undefined;
  
  return (
    <PointerProvider 
      apiKey={process.env.NEXT_PUBLIC_POINTER_API_KEY!}
      userData={userData}
    >
      <Component {...pageProps} />
    </PointerProvider>
  );
}
```

### Create React app

```typescript
// src/App.tsx
import { PointerProvider } from 'pointer-sdk';
import { useAuth } from './auth';

function App() {
  const { user } = useAuth();
  
  const userData = user ? {
    userId: user.id,
    name: user.name,
    email: user.email
  } : undefined;
  
  return (
    <PointerProvider 
      apiKey={process.env.REACT_APP_POINTER_API_KEY!}
      userData={userData}
    >
      <Router>
        {/* Your app routes */}
      </Router>
    </PointerProvider>
  );
}
```

## Authentication integration examples

### Auth0

```typescript
import { useAuth0 } from '@auth0/auth0-react';
import { useEffect } from 'react';
import { useUser } from 'pointer-sdk';

function Auth0Integration() {
  const { user, isAuthenticated, isLoading } = useAuth0();
  const { setUserData, clearUserData } = useUser();
  
  useEffect(() => {
    if (isLoading) return;
    
    if (isAuthenticated && user) {
      setUserData({
        userId: user.sub,
        name: user.name,
        email: user.email,
        avatarUrl: user.picture,
        customData: {
          locale: user.locale,
          emailVerified: user.email_verified
        }
      });
    } else {
      clearUserData();
    }
  }, [isAuthenticated, isLoading, user]);
  
  return null; // This is just an integration component
}

// Use this component within your PointerProvider
```

### Firebase authentication

```typescript
import { useEffect } from 'react';
import { useUser } from 'pointer-sdk';
import { onAuthStateChanged } from 'firebase/auth';
import { auth } from './firebaseConfig';

function FirebaseAuthIntegration() {
  const { setUserData, clearUserData } = useUser();
  
  useEffect(() => {
    const unsubscribe = onAuthStateChanged(auth, (firebaseUser) => {
      if (firebaseUser) {
        setUserData({
          userId: firebaseUser.uid,
          name: firebaseUser.displayName || undefined,
          email: firebaseUser.email || undefined,
          avatarUrl: firebaseUser.photoURL || undefined,
          customData: {
            emailVerified: firebaseUser.emailVerified,
            phoneNumber: firebaseUser.phoneNumber
          }
        });
      } else {
        clearUserData();
      }
    });
    
    return () => unsubscribe();
  }, []);
  
  return null;
}
```

### Clerk

```typescript
import { useUser as useClerkUser } from '@clerk/nextjs';
import { useUser as usePointerUser } from 'pointer-sdk';
import { useEffect } from 'react';

function ClerkIntegration() {
  const { user: clerkUser, isLoaded } = useClerkUser();
  const { setUserData, clearUserData } = usePointerUser();
  
  useEffect(() => {
    if (!isLoaded) return;
    
    if (clerkUser) {
      setUserData({
        userId: clerkUser.id,
        name: `${clerkUser.firstName} ${clerkUser.lastName}`.trim(),
        email: clerkUser.primaryEmailAddress?.emailAddress,
        avatarUrl: clerkUser.imageUrl,
        customData: {
          username: clerkUser.username
        }
      });
    } else {
      clearUserData();
    }
  }, [clerkUser, isLoaded]);
  
  return null;
}
```

<Note>
  The `customData` field is flexible and can include any JSON-serializable data that's relevant to your application. Use this to store organization information, user preferences, or other context that can help personalize the user experience.
</Note>