@betterstacks/engage-sdk NPM

Engage SDK

A powerful SDK for adding contextual AI chat, comments, and highlights to your React applications.

📦 Installation

Choose your preferred package manager:

# npm
npm install @betterstacks/engage-sdk

# yarn
yarn add @betterstacks/engage-sdk

# pnpm
pnpm add @betterstacks/engage-sdk

# bun
bun add @betterstacks/engage-sdk

🚀 Usage

React Applications

import { Toolbar } from '@betterstacks/engage-sdk';

function App() {
  return (
    <Toolbar
      theme="dark"
      aiChatTitle="AI Assistant"
      assistantName="Engage AI"
      features={{
        aiChat: true,
        comments: true,
        highlights: true,
        reactions: true,
      }}
      reactionConfig={{
        icon: "heart",
        maxCount: 500,
        label: "Like",
      }}
    />
  );
}

Next.js Applications

"use client";

import dynamic from "next/dynamic";
import type { EngageConfig } from "@betterstacks/engage-sdk";

// Dynamically import the Toolbar with SSR disabled
const Toolbar = dynamic<EngageConfig>(
  () => import("@betterstacks/engage-sdk").then((mod) => mod.Toolbar),
  { ssr: false }
);

export default function App() {
  return (
    <Toolbar
      theme="dark"
      aiChatTitle="AI Assistant"
      assistantName="Engage AI"
      features={{
        aiChat: true,
        comments: true,
        highlights: true,
        reactions: true,
      }}
      reactionConfig={{
        icon: "heart",
        maxCount: 500,
        label: "Like",
      }}
    />
  );
}

⚙️ Configuration

Theme Options

type Theme = 'light' | 'dark' | 'system';

The SDK supports three theme modes:

light: Light theme
dark: Dark theme
system: Automatically matches system preferences

Assistant Configuration

interface EngageConfig {
  // Assistant identity
  aiChatTitle?: string;    // Title shown in the chat window
  assistantName?: string;  // Name used by AI in responses

  // Feature flags
  features?: {
    aiChat?: boolean;      // Enable AI chat
    comments?: boolean;    // Enable comments
    highlights?: boolean;  // Enable highlights
  };

  // Theme configuration
  theme?: Theme;          // UI theme
}

🧩 Components

Toolbar

The main component that provides the floating toolbar interface.

<Toolbar
  theme="dark"
  aiChatTitle="AI Assistant"
  assistantName="Engage AI"
  features={{
    aiChat: true,
    comments: true,
    highlights: true,
    reactions: true,
  }}
  reactionConfig={{
    icon: "heart",
    maxCount: 500,
    label: "Like",
    siteId: "my-website",
    pageUrl: "/custom-page-path"
  }}
/>

💖 Reaction System

The Engage SDK includes a powerful reaction system that allows users to react to content on your website. This feature is similar to the "like" or "clap" functionality found on platforms like Medium.

Configuration

interface ReactionConfig {
  icon?: 'heart' | 'star' | 'gem' | 'arrow';  // Icon to display
  maxCount?: number;                          // Maximum reaction count
  label?: string;                             // Label for the reaction
  siteId?: string;                            // Identifier for the website
  pageUrl?: string;                           // Custom page URL
}

Add the reaction configuration to your Toolbar component:

<Toolbar
  features={{
    reactions: true,  // Enable reactions feature
    // ... other features
  }}
  reactionConfig={{
    icon: "heart",           // Type of reaction icon
    maxCount: 500,           // Maximum number of reactions
    label: "Like",           // Label shown in tooltip
    siteId: "my-website",    // Optional site identifier
    pageUrl: "/custom-path"  // Optional custom page path
  }}
/>

How It Works

The reaction system is fully managed by Better Stacks:

Cloud Storage: All reaction data is securely stored on Better Stacks servers
No Database Setup: You don't need to set up or manage any database
Automatic Scaling: The system automatically scales to handle any volume of reactions

Page Identification

The reaction system identifies pages using a combination of:

Page URL: By default, the system uses window.location.pathname to identify the current page
Site ID (optional): You can provide a siteId in the configuration to group reactions across multiple deployments or environments

📚 Better Stacks Collections Integration

The Engage SDK supports integration with Better Stacks Collections, allowing your AI assistant to use curated collections as knowledge sources when answering user questions.

Configuration

interface StacksCollection {
  url: string;  // URL to the Better Stacks collection
}

Add the collections configuration to your Toolbar component:

<Toolbar
  // ... other configuration
  stacksCollection={{
    url: "https://betterstacks.com/user/your-username/collections/collection-id"
  }}
/>

How It Works

Collection Context: The AI assistant uses the links and resources from your Better Stacks collection as context
Automatic Fetching: The SDK handles fetching and caching collection data from the Better Stacks API
Smart Cache Invalidation: The cache is automatically refreshed when the collection URL changes
Enhanced Responses: Your AI assistant can provide more accurate and contextual responses based on your curated content

Cache Management

You can manually clear the collection cache using the exported utility function:

import { clearCollectionCache } from '@betterstacks/engage-sdk';

// Clear cache for a specific collection URL
clearCollectionCache('https://betterstacks.com/user/your-username/collections/collection-id');

// Clear all collection caches
clearCollectionCache();

Analytics

Engage SDK includes integrated analytics capabilities to track user interactions and engagement with the SDK components. All analytics data is collected and managed by Better Stacks, eliminating the need for you to set up your own analytics infrastructure.

Setup

Obtain an API Key:
- Sign in to the Engage Dashboard using your Better Stacks account (Google, GitHub, etc.)
- Once signed in, navigate to the Projects section
- Click "Create New Project" and provide a name and optional description
- After creating a project, go to the "API Keys" section within your project
- Click "Create API Key", provide a descriptive name (e.g., "Production", "Development"), and click Generate
- Copy the generated API key for use in your application

Integration in Your App:

import { Toolbar } from "@betterstacks/engage-sdk";

function MyApp() {
  return (
    <Toolbar
      theme="dark"
      aiChatTitle="AI Assistant"
      assistantName="Engage AI"
      features={{
        aiChat: true,
        comments: true,
        highlights: true,
        reactions: true
      }}
      reactionConfig={{
        icon: "heart",
        maxCount: 500,
        label: "Like"
      }}
      analytics={{
        enabled: true,
        apiKey: process.env.NEXT_PUBLIC_API_KEY,
        debug: process.env.NODE_ENV === 'development'
      }}
    />
  );
}

Tracked Events:
The SDK automatically tracks the following events:
- Page Views: Records when users visit your pages
- Scroll Depth: Measures how far users scroll down your content (25%, 50%, 75%, 100%)
- AI Chat Interactions:
  - Opening the chat window
  - Sending messages
  - Session duration
- Content Engagement:
  - Highlight creation
  - Comment creation
  - Reaction interactions
- Session Data:
  - User sessions
  - Engagement time

Project-Based Analytics

With the API key approach, all analytics are tied to your specific project:

No Setup Required: All analytics infrastructure is managed by Better Stacks
Project Identification: Your API key identifies your project in our analytics system
Dashboard Access: View your project's analytics through the Better Stacks dashboard
Data Filtering: Analytics are automatically filtered by project, showing only your data
Privacy Compliance: Simplified compliance with privacy regulations

Viewing Analytics

Once you've integrated the SDK with your API key, your analytics data will automatically be collected. To view this data:

Sign in to the Engage Dashboard using your Better Stacks account
Navigate to the Projects section and select your project
Click on the "Analytics" tab to access your project's analytics dashboard
Here you can view:
- Daily and monthly engagement trends
- User session statistics
- Feature usage breakdown (AI Chat, Comments, Highlights, Reactions)
- Content performance metrics
- Scroll depth analysis

You can filter analytics data by date range and export reports as needed.

Troubleshooting Analytics

If you're not seeing analytics data in your dashboard, check the following:

Verify API Key: Ensure your API key is correctly configured in the analytics prop
Enable Debug Mode: Set debug: true in your analytics configuration during development to see debug logs in the console
Check for Errors: Look for any error messages in the browser console related to analytics tracking
Data Delay: Note that there may be a short delay (up to 5 minutes) before new data appears in your dashboard
Ad Blockers: Some ad blockers may interfere with analytics tracking - try disabling them for testing

Example debug configuration:

<Toolbar
  // ... other configuration
  analytics={{
    enabled: true,
    apiKey: "your-api-key",
    debug: true // Enables detailed console logging
  }}
/>