User Presence Tracker (JS)

Real-time user online/offline/activity tracking with WebSocket + REST API. Tracks connections, heartbeats, and inactivity with Redis persistence. Pure JavaScript version.

websocketsocket.iopresenceonline-statusactivityreal-timeuser-trackingexpressjavascript

v1.0.0utility

Overview

A plug-and-play real-time user presence system for Express apps. Tracks online/offline status, activity timestamps, and heartbeats using WebSocket + Redis.

Call one endpoint from ANY frontend event ('POST /api/presence/activity') to register user activity. Auto-handles WebSocket connect/disconnect for instant status updates. Perfect for chat apps, dashboards, and social platforms.

Installation

CLI

npx backternity add user-presence-tracker

What This Does

Installs a complete user presence tracking system with Redis persistence, WebSocket real-time updates, and REST API for manual activity pings.

Files & Folders Created

File / Path	Description
/src/config/redis.js	Redis connection with TTL cleanup
/src/services/presenceService.js	Core presence logic
/src/routes/presence.js	REST API + WebSocket integration
/src/socket/presenceSocket.js	Real-time socket handlers
/server.js.example	3-line integration demo
/.env.example	Redis + timeout configuration

Files to be modified

File / Path	Description
server.js	Add `app.use('/api/presence', presenceRoutes)` + `setSocketIO(io)`
.env	Add Redis connection (REDIS_HOST, REDIS_PORT)

Configuration

# Redis Configuration (required)
REDIS_HOST=127.0.0.1
REDIS_PORT=6379

# Timeout Settings
INACTIVITY_TIMEOUT=300000  # 5 minutes in ms

# Server
PORT=3001

Frontend Integration

Connect via WebSocket for **auto online/offline** or ping REST API from **any frontend event** (clicks, scrolls, typing). Receive real-time updates when other users go online/offline.

POST/api/presence/activity

Call from ANY frontend event (click, scroll, type, etc.)

GET/api/presence/status/:userId

Get single user online status + last activity

GET/api/presence/online/count

Get total online users count

GET/api/presence/online/users

Get list of all online user IDs

Example

// app/components/PresenceTracker.jsx (React/Next.js)
'use client';
import { useState, useEffect } from 'react';
import io from 'socket.io-client';

export default function PresenceTracker({ userId }) {
  const [status, setStatus] = useState('');
  const [onlineCount, setOnlineCount] = useState(0);
  let socket = null;

  // WebSocket for real-time (optional)
  useEffect(() => {
    socket = io('/', { query: { userId } });
    
    socket.on('status', (data) => setStatus('🟢 Online'));
    socket.on('user_offline', (data) => console.log('User offline:', data.userId));
    socket.on('user_activity', (data) => console.log('User active:', data.userId));

    return () => socket?.disconnect();
  }, [userId]);

  // Activity ping on ANY event
  const trackActivity = async () => {
    try {
      const res = await fetch('/api/presence/activity', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId })
      });
      if (res.ok) setStatus('✅ Activity tracked');
    } catch {
      setStatus('⚠️ Activity tracking failed');
    }
  };

  // Check online count
  const checkOnlineCount = async () => {
    const res = await fetch('/api/presence/online/count');
    const data = await res.json();
    setOnlineCount(data.data.count);
  };

  return (
    <div className="p-6 border border-white/10 rounded-xl bg-gradient-to-r from-black/50 to-gray-900">
      <div className="flex gap-4 mb-4">
        <button
          onClick={trackActivity}
          className="bg-emerald-600 hover:bg-emerald-700 text-white px-6 py-2 rounded-lg font-medium"
        >
          Track Activity
        </button>
        <button
          onClick={checkOnlineCount}
          className="bg-blue-600 hover:bg-blue-700 text-white px-6 py-2 rounded-lg font-medium"
        >
          Online Count
        </button>
      </div>
      
      <div className="space-y-2 text-sm">
        <p><strong>Status:</strong> {status}</p>
        <p><strong>Online Users:</strong> {onlineCount}</p>
        <p className="text-xs text-gray-400">
          💡 Click ANYWHERE on page → auto-tracks activity via REST API<br/>
          🔌 WebSocket auto-handles online/offline
        </p>
      </div>
    </div>
  );
}

Usage

// From ANY frontend event (click, scroll, mouse move, etc.)
fetch('/api/presence/activity', {
  method: 'POST',
  body: JSON.stringify({ userId: 'user_123' })
});

// Check user status
fetch('/api/presence/status/user_123').then(r => r.json());

// WebSocket (auto online/offline)
const socket = io('/', { query: { userId: 'user_123' } });
socket.on('user_offline', handleUserOffline);