@pobuca/pobuca-ai-web-sdk

v1.0.1

Published

2 months ago

JavaScript SDK for embedding Pobuca AI chat on any website

0High
0Medium
0Low

raelgor

pmanikas

pobuca ai chat chatbot sdk widget

Pobuca AI Web SDK

JavaScript SDK for embedding Pobuca AI chat widget on any website. Works with vanilla JavaScript, TypeScript, React, Vue, Angular, and any other web framework.

Installation

NPM

npm install @pobuca/pobuca-ai-web-sdk

CDN (Coming Soon)

<script src="https://cdn.pobuca.com/ai-web-sdk/latest/pobuca-ai-web-sdk.js"></script>

Usage

Vanilla JavaScript

<!DOCTYPE html>
<html>
<head>
  <title>My Website</title>
</head>
<body>
  <h1>Welcome to my website</h1>
  
  <!-- Include the SDK -->
  <script src="node_modules/@pobuca/pobuca-ai-web-sdk/dist/pobuca-ai-web-sdk.js"></script>
  
  <!-- Initialize and show the chat badge -->
  <script>
    const client = new PobucaAIClient({
      apiKey: 'your-api-key-here'
    });
    
    client.showBadge();
  </script>
</body>
</html>

TypeScript / ES Modules

import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

const client = new PobucaAIClient({
  apiKey: 'your-api-key-here',
  serviceUrl: 'https://ai.pobuca.com' // Optional, defaults to https://ai.pobuca.com
});

client.showBadge();

React

import { useEffect, useRef } from 'react';
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

function App() {
  const clientRef = useRef<PobucaAIClient | null>(null);
  
  useEffect(() => {
    clientRef.current = new PobucaAIClient({
      apiKey: 'your-api-key-here'
    });
    
    clientRef.current.showBadge();
    
    // Cleanup on unmount
    return () => {
      if (clientRef.current) {
        clientRef.current.destroy();
      }
    };
  }, []);
  
  return (
    <div>
      <h1>My React App</h1>
    </div>
  );
}

export default App;

💡 See full React demo: Check the demo-react/ folder for a complete working example with TypeScript!

Vue 3

<template>
  <div>
    <h1>My Vue App</h1>
  </div>
</template>

<script setup>
import { onMounted, onUnmounted } from 'vue';
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

let client;

onMounted(() => {
  client = new PobucaAIClient({
    apiKey: 'your-api-key-here'
  });
  
  client.showBadge();
});

onUnmounted(() => {
  if (client) {
    client.destroy();
  }
});
</script>

Angular

import { Component, OnInit, OnDestroy } from '@angular/core';
import { PobucaAIClient } from '@pobuca/pobuca-ai-web-sdk';

@Component({
  selector: 'app-root',
  template: '<h1>My Angular App</h1>'
})
export class AppComponent implements OnInit, OnDestroy {
  private client?: PobucaAIClient;
  
  ngOnInit() {
    this.client = new PobucaAIClient({
      apiKey: 'your-api-key-here'
    });
    
    this.client.showBadge();
  }
  
  ngOnDestroy() {
    if (this.client) {
      this.client.destroy();
    }
  }
}

API Reference

`PobucaAIClient`

Constructor Options

interface PobucaAIClientOptions {
  apiKey: string;        // Required: Your Pobuca AI API key
  serviceUrl?: string;   // Optional: Custom service URL (defaults to 'https://ai.pobuca.com')
}

Methods

`showBadge()`

Displays the chat badge in the bottom-right corner of the page. If the badge is already shown, this method does nothing.

client.showBadge();

`hideBadge()`

Hides the chat badge without removing it from the DOM. The badge can be shown again by calling showBadge().

client.hideBadge();

`destroy()`

Completely removes the chat badge from the DOM and cleans up all resources. After calling this method, you'll need to create a new instance to show the badge again.

client.destroy();

Demos

Interactive Demos Included

Vanilla JavaScript Demo: demo.html - Full-featured interactive demo
React + TypeScript Demo: demo-react/ - Complete React application with Vite

To run the React demo:

# From the web-sdk folder
npm run demo-react

# Or manually
cd demo-react
npm install
npm run dev

See demo-react/LAUNCH.md for detailed instructions.

Customization

The chat badge appears as a floating button in the bottom-right corner of your website. When clicked, it opens a chat window with your Pobuca AI agent.

Positioning

The badge is positioned at:

Desktop: 20px from bottom and right
Mobile: 10px from bottom and right
Small mobile: Full screen when opened

Styling

The widget uses Shadow DOM to prevent style conflicts with your website. The badge has a purple gradient background and smooth animations.

Browser Support

Chrome/Edge (latest 2 versions)
Firefox (latest 2 versions)
Safari (latest 2 versions)
Mobile browsers (iOS Safari, Chrome Mobile)

Development

Building from Source

# Install dependencies
npm install

# Build the SDK
npm run build

# Start development server
npm start

Project Structure

web-sdk/
├── src/
│   ├── client.ts              # Main client class
│   ├── badge.component.ts     # Angular badge component
│   ├── badge.component.html   # Badge template
│   ├── badge.component.scss   # Badge styles
│   ├── main.ts                # Angular Elements bootstrap
│   └── index.ts               # Public API exports
├── demo-react/                # React + TypeScript demo
├── dist/                      # Built files
│   ├── pobuca-ai-web-sdk.js  # Bundled JavaScript
│   └── index.d.ts            # TypeScript definitions
└── package.json

Features

✅ Framework Agnostic - Works with any JavaScript framework or vanilla JS
✅ TypeScript Support - Full type definitions included
✅ Lightweight - Only ~51KB gzipped
✅ Responsive - Mobile-first design with full-screen mobile support
✅ Style Isolation - Uses Shadow DOM to prevent CSS conflicts
✅ Easy Integration - Just 3 lines of code to get started
✅ Modern UI - Beautiful gradient design with smooth animations

Configuration Options

The SDK accepts the following options:

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | apiKey | string | Yes | - | Your Pobuca AI API key | | serviceUrl | string | No | 'https://ai.pobuca.com' | Custom service URL for self-hosted instances |

Advanced Usage

Controlling Badge Visibility

const client = new PobucaAIClient({ apiKey: 'your-api-key' });

// Show badge when user clicks a button
document.getElementById('openChat').addEventListener('click', () => {
  client.showBadge();
});

// Hide badge programmatically
document.getElementById('closeChat').addEventListener('click', () => {
  client.hideBadge();
});

// Destroy badge completely (cleanup)
document.getElementById('removeChat').addEventListener('click', () => {
  client.destroy();
});

Conditional Loading

// Only show chat for logged-in users
if (user.isLoggedIn) {
  const client = new PobucaAIClient({
    apiKey: user.apiKey
  });
  client.showBadge();
}

Self-Hosted Instance

const client = new PobucaAIClient({
  apiKey: 'your-api-key',
  serviceUrl: 'https://your-domain.com'
});
client.showBadge();

Troubleshooting

Badge doesn't appear

Check browser console for errors
Verify your API key is correct
Ensure the script is loaded: console.log(window.PobucaAIClient)
Check if there are any CSP (Content Security Policy) restrictions

Iframe content doesn't load

Verify the serviceUrl is accessible
Check browser console for CORS errors
Ensure your API key has proper permissions

TypeScript errors

Make sure the type definitions are properly installed:

npm install --save-dev @types/node

File Size

Uncompressed: 168 KB
Gzipped: 51 KB
Brotli: ~45 KB (estimated)

Changelog

See CHANGELOG.md for version history and updates.

License

MIT

Support

For support, please contact [email protected] or visit https://pobuca.com

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Roadmap

[ ] Additional customization options (colors, position, size)
[ ] Event system for tracking chat interactions
[ ] Offline support
[ ] Pre-chat forms
[ ] File upload support
[ ] Multi-language support