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**
```javascript
// 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**
```javascript
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**
```javascript
// 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:
```javascript
{
  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`
```javascript
// 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

```javascript
// 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}`);
}
```