broswer-automation/app/chrome-extension/USER_ID_GUIDE.md

Chrome Extension User ID Guide

Overview

The Chrome extension automatically generates and manages unique user IDs when connecting to the remote server. This guide explains how to access and use these user IDs.

How User IDs Work

1. Automatic Generation

• Each Chrome extension instance generates a unique user ID in the format: user_{timestamp}_{random}
• Example: user_1704067200000_abc123def456
• User IDs are persistent across browser sessions (stored in chrome.storage.local)

2. User ID Display in Popup

When connected to the remote server, the popup will show:

• User ID section with the current user ID
• Truncated display for long IDs (shows first 8 and last 8 characters)
• Copy button (📋) to copy the full user ID to clipboard
• Tooltip showing the full user ID on hover

Getting User ID Programmatically

1. From Popup/Content Scripts

// Send message to background script to get user ID
const response = await chrome.runtime.sendMessage({ type: 'getCurrentUserId' });
if (response && response.success) {
  const userId = response.userId;
  console.log('Current User ID:', userId);
} else {
  console.log('No user ID available or not connected');
}

2. From Background Script

import { getRemoteServerClient } from './background/index';

// Get the remote server client instance
const client = getRemoteServerClient();
if (client) {
  const userId = await client.getCurrentUserId();
  console.log('Current User ID:', userId);
}

3. Direct Storage Access

// Get user ID directly from chrome storage
const result = await chrome.storage.local.get(['chrome_extension_user_id']);
const userId = result.chrome_extension_user_id;
console.log('Stored User ID:', userId);

User ID Lifecycle

1. Generation

• User ID is generated on first connection to remote server
• Stored in chrome.storage.local with key chrome_extension_user_id
• Persists across browser restarts and extension reloads

2. Usage

• Sent to remote server during connection handshake
• Used for session management and routing
• Enables multi-user support with session isolation

3. Display

• Shown in popup when connected to remote server
• Updates automatically when connection status changes
• Cleared from display when disconnected

Remote Server Integration

1. Connection Info

When connecting, the extension sends:

{
  type: 'connection_info',
  userId: 'user_1704067200000_abc123def456',
  userAgent: navigator.userAgent,
  timestamp: Date.now(),
  extensionId: chrome.runtime.id
}

2. Server-Side Access

The remote server receives and uses the user ID for:

• Session management
• LiveKit room assignment (mcp-chrome-user-{userId})
• Command routing
• User isolation

Troubleshooting

1. User ID Not Showing

• Ensure you're connected to the remote server
• Check browser console for connection errors
• Verify remote server is running and accessible

2. User ID Changes

• User IDs should persist across sessions
• If changing frequently, check chrome.storage permissions
• Clear extension data to force new user ID generation

3. Copy Function Not Working

• Ensure clipboard permissions are granted
• Check for HTTPS context requirements
• Fallback: manually select and copy from tooltip

API Reference

Background Script Messages

getCurrentUserId

// Request
{ type: 'getCurrentUserId' }

// Response
{ 
  success: true, 
  userId: 'user_1704067200000_abc123def456' 
}
// or
{ 
  success: false, 
  error: 'Remote server client not initialized' 
}

Storage Keys

chrome_extension_user_id

• Type: String
• Format: user_{timestamp}_{random}
• Persistence: Permanent (until extension data cleared)
• Access: chrome.storage.local

Best Practices

1. Always check connection status before requesting user ID
2. Handle null/undefined user IDs gracefully
3. Use the background script API for reliable access
4. Don't hardcode user IDs - they should be dynamic
5. Respect user privacy - user IDs are anonymous but unique

Example Implementation

// Complete example of getting and using user ID
async function handleUserIdExample() {
  try {
    // Get current user ID
    const response = await chrome.runtime.sendMessage({ 
      type: 'getCurrentUserId' 
    });
    
    if (response && response.success && response.userId) {
      console.log('✅ User ID:', response.userId);
      
      // Use the user ID for your application logic
      await processUserSpecificData(response.userId);
      
    } else {
      console.log('❌ No user ID available');
      console.log('Make sure you are connected to the remote server');
    }
    
  } catch (error) {
    console.error('Failed to get user ID:', error);
  }
}

async function processUserSpecificData(userId) {
  // Your application logic here
  console.log(`Processing data for user: ${userId}`);
}