npm package: @getrise-ai/web-sdk
Description: Rise AI Web SDK
Latest version: 0.35.0

# Rise AI Web SDK

[![Accessibility](https://img.shields.io/badge/accessibility-WCAG%202.1%20AA-green)](./documentation/accessibility/compliance.md)

A lightweight TypeScript SDK for adding an AI-powered user engagement engine by Rise AI to your web app.

## Quick Install with AI Assistant

Copy and paste this prompt to your AI coding assistant (Claude, Copilot, etc.) to get Rise AI set up with best practices:

```text
Install and integrate the Rise AI Web SDK (@getrise-ai/web-sdk) into my project.

PACKAGE INFO:
- Name: @getrise-ai/web-sdk
- Purpose: Lightweight TypeScript SDK that adds an AI-powered user engagement engine
- Supports: React, Next.js, Vue, Nuxt, Angular, and vanilla JS
- Includes full TypeScript definitions

TASKS:
1. Detect my framework and package manager (npm, pnpm, or yarn) from lock files
2. Install the SDK using the detected package manager
3. For vanilla JS/HTML projects: Use the CDN script instead:
   <script src="https://unpkg.com/@getrise-ai/web-sdk/dist/loader.umd.js"></script>
4. Initialize early in the app lifecycle (use appropriate lifecycle hook for the framework):
   - Import: import Rise from '@getrise-ai/web-sdk'
   - Call Rise.init() with the appKey:
     Rise.init({ appKey: 'your-rise-app-key' })
5. Identify users after authentication:
   if (user?.id) Rise.identify(user.id);

IMPLEMENTATION NOTES:
- Follow my existing project structure and code style conventions
- Use appropriate lifecycle hooks: React (useEffect), Vue (onMounted), Angular (ngOnInit)

FIRST analyze my project structure and detect the framework and package manager. Then and only then implement the Rise AI Web SDK integration accordingly.
```

## Installation

```bash
npm install @getrise-ai/web-sdk
# or
pnpm add @getrise-ai/web-sdk
# or
yarn add @getrise-ai/web-sdk
```

## Quick Start

### Basic Integration

```typescript
import Rise from '@getrise-ai/web-sdk';

// Initialize the SDK
Rise.init({
    appKey: 'your-app-key'
});

// Identify a user
Rise.identify('user-123');
```

**Note:** `Rise.init()` must be called before other methods. User identification via `Rise.identify()` enables activity
tracking.

### HTML/JavaScript Integration

```html

<script src="https://unpkg.com/@getrise-ai/web-sdk/dist/loader.umd.js"></script>
<script>
    Rise.init({
        appKey: 'your-app-key'
    });

    Rise.identify('user-123');
</script>
```

## Configuration

```typescript
Rise.init({
    appKey: string,                               // Required: Your Rise AI app key
    apiEndpoint: string | undefined,              // Optional: Custom API endpoint
    wsEndpoint: string | undefined,               // Optional: Custom WebSocket endpoint
    isDevelopment: boolean | undefined,           // Optional: Enable dev mode logging (default: false)
    autoShowBubble: boolean | undefined,          // Optional: Auto-show bubble (default: true)
    bubbleConfig: BubbleConfig | undefined,       // Optional: Bubble appearance customization
});
```

### BubbleConfig

Customize the chat bubble appearance:

```typescript
interface BubbleConfig {
    position?: BubblePosition;  // Position on screen
}

enum BubblePosition {
    BOTTOM_LEFT = "bottom-left",
    BOTTOM_RIGHT = "bottom-right"  // default
}
```

### Example with Custom Configuration

```typescript
Rise.init({
    appKey: 'your-app-key',
    isDevelopment: true,
    autoShowBubble: true,
    bubbleConfig: {
        position: 'bottom-left'
    }
});
```

## API Reference

### `Rise.init(config)`

Initialize the SDK with configuration options. Must be called before using other methods.

### `Rise.identify(userId)`

Associate a user ID with the current session for personalized experiences.

### `Rise.reportEvent(name, params)`

Report a custom event with the given name and parameters.

**Parameters:**

- `name` (string): Event name (will be normalized: trimmed, lowercased, special characters replaced with underscores)
- `params` (object): Event parameters as a plain object

**Example:**

```typescript
Rise.reportEvent('Product Purchased', {
    product_id: 'ABC-123',
    quantity: 5,
    price: 99.99
});
// Event sent with normalized name: "product_purchased"
```

### `Rise.setUserProfile(userProfile)`

Set or update the user profile for the currently identified user.

**Parameters:**

- `userProfile` (object): User profile data as a plain object. Can contain any JSON-serializable properties.

**Example:**

```typescript
Rise.setUserProfile({
    name: 'Jane Doe',
    email: 'jane@example.com',
    age: 28,
    preferences: {
        theme: 'dark',
        notifications: true
    }
});
```

**Notes:**

- Profile is upserted (created if new, replaced if exists)
- Profile data completely replaces existing profile on each call

### `Rise.showBubble(config?)`

Show the AI chat bubble. Optional configuration for appearance customization.

### `Rise.hideBubble()`

Hide the AI chat bubble.

### `Rise.isBubbleVisible()`

Check if the bubble is currently visible.

### `Rise.destroy()`

Clean up SDK resources and stop all tracking.

## Framework Examples

### React

```tsx
import {useEffect} from 'react';
import Rise from '@getrise-ai/web-sdk';

function App() {
    useEffect(() => {
        Rise.init({
            appKey: 'your-app-key'
        });

        // Identify user when available
        if (user?.id) {
            Rise.identify(user.id);
        }
    }, [user?.id]);

    return <div>Your App</div>;
}
```

### Vue

```vue

<script setup>
  import {onMounted} from 'vue';
  import Rise from '@getrise-ai/web-sdk';

  onMounted(() => {
    Rise.init({
      appKey: 'your-app-key'
    });
  });
</script>
```

### Angular

```typescript
import {Component, OnInit} from '@angular/core';
import Rise from '@getrise-ai/web-sdk';

@Component({
    selector: 'app-root',
    template: '<div>Your App</div>'
})
export class AppComponent implements OnInit {
    ngOnInit() {
        Rise.init({
            appKey: 'your-app-key'
        });
    }
}
```

## Features

- **AI-powered user engagement and assistance**: Interactive chat interface for user support
- **Automatic user behavior analysis**: Intelligent tracking and understanding of user interactions
- **Framework-agnostic integration**: Works with React, Vue, Angular, and vanilla JavaScript
- **Full TypeScript support**: Complete type definitions included
- **Lightweight**: Minimal bundle size impact

## Edge Cases & Internal Behavior

### Error Handling

The SDK handles all errors internally. Callers don't need try-catch blocks around SDK methods. Failed operations are
logged to the console and retried automatically when appropriate.

### State Persistence

User identification and settings persist across page reloads via localStorage. Once a user is identified, they remain
identified until `Rise.destroy()` is called or localStorage is cleared.

### Multiple init() Calls

Calling `Rise.init()` multiple times is safe. Subsequent calls after the first are ignored.

### Automatic Retries

Failed API calls and uploads are automatically retried with exponential backoff. No manual intervention required.

### Call Queue

All SDK calls should be called after the SDK is initialized via `Rise.init()`, and the user is identified via
`Rise.identify()`.
In case a call is made before `init` or `identify` the SDK queues the call internally and eventually executed once the
prerequisite calls were made.

## Troubleshooting

### Bubble doesn't appear

- Check `autoShowBubble` is set to `true` OR manually call `Rise.showBubble()`
- Verify `Rise.init()` was called with valid `appKey`
- Check browser console for initialization errors

### User identification not working

- Ensure `Rise.init()` is called before `Rise.identify()`
- User ID must be non-empty string
- Check browser console for error logs