@vitalwall/client

A JavaScript client library for VitalWall that allows you to integrate real-time wall displays and programmatically add items to your walls.

🌐 Visit VitalWall.com to create your account, get API keys, and manage your walls.

What is VitalWall?

VitalWall is a real-time activity wall service that helps businesses showcase live user interactions, sales, signups, and other activities on their websites. Think of it as a "social proof engine" that displays real-time notifications to boost user engagement and conversions.

🎯 Use Cases

E-commerce & Sales:

• "John from New York just purchased Premium Plan - $299"
• "Sarah completed checkout for Wireless Headphones"
• "5 people viewing this product right now"

SaaS & Apps:

• "Welcome Alex! Just signed up from California"
• "ProjectManager Pro upgrade by TechCorp Inc."
• "1,247 tasks completed today across all users"

Events & Webinars:

• "Michael just registered for tomorrow's webinar"
• "LiveStream starting in 5 minutes - 234 attendees ready"
• "Q&A session: 'Great question from Jennifer in Miami'"

General Business:

• "New review: ⭐⭐⭐⭐⭐ 'Excellent service!' - David"
• "Newsletter signup from Berlin, Germany"
• "Support ticket resolved in 2 minutes"

✨ Why Use VitalWall?

• 🚀 Increase Conversions: Social proof encourages action
• ⚡ Real-time Updates: Live activity creates urgency
• 🎨 Customizable: Match your brand and design
• 📱 Responsive: Works on desktop, tablet, and mobile
• 🔧 Easy Integration: Add with just a few lines of code
• 📊 Analytics Ready: Track engagement and performance

🌟 How It Works

1. Track Events: Use this library to send user activities to VitalWall
2. Display Live: VitalWall renders real-time notifications on your site
3. Engage Users: Visitors see live activity and are encouraged to take action
4. Boost Results: Increased social proof leads to higher conversions

Example Flow:

User Action → VitalWall.addItem() → Real-time Display → Increased Engagement

🛠️ Library Features

• 🔄 Real-time Communication: WebSocket-based live updates
• 📦 Multiple Formats: Support for text and HTML content
• 🎯 Multi-Wall Support: Manage different walls for different purposes
• 🔒 Secure: Automatic domain validation and API key authentication
• ⚡ Lightweight: Minimal footprint with zero dependencies
• 🌐 Universal: Works in browsers and Node.js environments
• 🎨 Auto-Tracking: Optional data-attribute based tracking
• 📱 Responsive: Mobile-friendly wall displays

🏢 Perfect For

• E-commerce stores wanting to show live purchases
• SaaS companies displaying user signups and upgrades
• Event organizers showing live registrations
• Service businesses highlighting reviews and testimonials
• Any website wanting to add social proof and urgency

🚀 Get Started with VitalWall

1. 📝 Create Account: Visit VitalWall.com to sign up
2. 🔑 Get API Key: Generate your API credentials in the dashboard
3. 🏗️ Create Wall: Set up your first wall and get the wall ID
4. 💻 Install Library: Follow the Quick Start below to integrate

Quick Start

Get VitalWall running on your site in 3 steps:

1. Install & Initialize

npm install @vitalwall/client

import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();
await vitalWall.init({
  apiKey: 'your-api-key',  // Get from VitalWall dashboard
  wallId: 'your-wall-id'   // Create in VitalWall dashboard
});

2. Add Display Container

<!-- This div will show your real-time activity -->
<div data-vital-wall="your-wall-id" style="height: 400px;"></div>

3. Track Events

// When someone makes a purchase
await vitalWall.addTextItem('New sale: Premium Plan - $99');

// When someone signs up  
await vitalWall.addHtmlItem(`
  <strong>Welcome!</strong> ${userName} just joined from ${city}
`);

That's it! Your wall will now display real-time activity to boost engagement and conversions.

💡 Need an API key? Visit VitalWall.com to create your free account and get your API credentials.

Installation

npm install @vitalwall/client

Detailed Usage

💡 New to VitalWall? Check the Quick Start section above for a simple 3-step setup.

Basic Setup

🔑 Getting Your Credentials: Sign up at VitalWall.com to get your apiKey and create walls to get wallId values.

import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();

// Initialize with your API key
await vitalWall.init({
  apiKey: 'your-api-key',
  wallId: 'your-wall-id', // Optional: set default wall
  debug: true // Optional: enable debug logging
});

HTML Wall Display

Add a wall display to your HTML:

<div data-vital-wall="your-wall-id" style="height: 400px;"></div>

The wall will automatically initialize and display real-time updates.

Adding Items Programmatically

// Add a text item to the current wall
const itemId = await vitalWall.addTextItem('New user signed up!');

// Add an HTML item to a specific wall
const itemId = await vitalWall.addHtmlItem(
  '<div><strong>Sale!</strong> User purchased Product X</div>',
  'specific-wall-id'
);

// Add a custom item
const itemId = await vitalWall.addItem({
  content: 'Custom content',
  isHtml: false,
  wallId: 'wall-id' // Optional, uses current wall if not specified
});

Wall Management

// Set the current wall (for addItem methods without wallId)
vitalWall.setCurrentWall('new-wall-id');

// Get the current wall ID
const currentWall = vitalWall.getCurrentWall();

// Check if VitalWall is initialized
if (vitalWall.isInitialized()) {
  // Ready to use
}

// Listen for initialization completion
vitalWall.onReady(() => {
  console.log('VitalWall is ready!');
  // Add items, etc.
});

Automatic Tracking (Legacy Compatibility)

VitalWall also supports automatic tracking of user interactions using data attributes, maintaining compatibility with the script tag version:

<!-- Track clicks on this button -->
<button data-vital-item="User clicked signup button">Sign Up</button>

<!-- Auto-track when element appears (no click required) -->
<div data-vital-item="Page loaded" data-vital-auto="true"></div>

<!-- Track with HTML content -->
<div data-vital-item="Rich content" data-vital-html="true">
  <strong>User Action:</strong> Downloaded PDF
</div>

<!-- Send content from another element -->
<div id="user-info">John Doe purchased Product X</div>
<button data-vital-send-content="user-info">Track Purchase</button>

Configuration Options

await vitalWall.init({
  apiKey: 'your-api-key',           // Required: Your VitalWall API key
  wallId: 'default-wall-id',        // Optional: Default wall ID for addItem methods
  debug: true,                      // Optional: Enable debug logging
  domain: 'example.com'             // Optional: Only for Node.js environments (auto-detected in browsers)
});

Security Note: The domain parameter is automatically detected from window.location.hostname in browser environments for security purposes. It should only be manually specified when using VitalWall in Node.js server environments.

Cleanup

// Clean up all walls and event listeners
vitalWall.cleanup();

Examples

E-commerce Site

import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();

await vitalWall.init({
  apiKey: 'your-api-key',
  wallId: 'sales-wall'
});

// Track purchases
document.getElementById('purchase-btn').addEventListener('click', async () => {
  const product = getCurrentProduct();
  await vitalWall.addHtmlItem(`
    <div class="purchase-notification">
      <strong>${product.name}</strong> purchased by ${user.name}
      <span class="price">$${product.price}</span>
    </div>
  `);
});

Real-time Dashboard

import VitalWall from '@vitalwall/client';

const vitalWall = new VitalWall();

await vitalWall.init({
  apiKey: 'your-api-key'
});

// Multiple walls for different metrics
const salesWall = 'sales-wall-id';
const signupsWall = 'signups-wall-id';

// Track different events to different walls
await vitalWall.addTextItem('New sale: $299', salesWall);
await vitalWall.addTextItem('New user registered', signupsWall);

More Examples

For additional comprehensive examples including e-commerce integration, real-time dashboards, and lifecycle management, see the examples.ts file in this package.

Node.js Server Example

For server-side usage with Express.js middleware, batch operations, and programmatic item tracking, see the complete Node.js example at examples/nodejs-server.mjs.

The Node.js example demonstrates:

• Server-side VitalWall initialization with domain validation
• Express.js middleware integration
• Batch event processing
• E-commerce order tracking
• User registration notifications
• System alert monitoring

API Reference

For complete API documentation with detailed method signatures, error handling, and type definitions, see API.md.

VitalWall Class

Methods

• init(config: VitalWallConfig): Promise<void> - Initialize VitalWall
• addItem(item: WallItem): Promise<string | undefined> - Add a custom item
• addTextItem(content: string, wallId?: string): Promise<string | undefined> - Add text item
• addHtmlItem(content: string, wallId?: string): Promise<string | undefined> - Add HTML item
• setCurrentWall(wallId: string): void - Set default wall ID
• getCurrentWall(): string | null - Get current wall ID
• isInitialized(): boolean - Check initialization status
• onReady(callback: () => void): void - Add ready callback
• cleanup(): void - Clean up resources

Types

interface VitalWallConfig {
  apiKey: string;
  debug?: boolean;
  wallId?: string;
  domain?: string; // For Node.js environments only
}

interface WallItem {
  content: string;
  isHtml?: boolean;
  wallId?: string;
}

Browser Support

• Chrome/Edge 60+
• Firefox 55+
• Safari 10.1+
• IE 11+ (with polyfills)

License

MIT