AgentShield
JavaScript Beacon

Configuration

Advanced configuration options for AgentShield Beacon

Configuration Overview

The AgentShield Beacon is highly configurable to meet your specific needs. All configuration options are passed to the constructor.

Basic Configuration

const beacon = new AgentShieldBeacon({
  // Required
  apiKey: 'your-api-key',

  // Common options
  endpoint: 'https://kya.vouched.id/v1/beacon',
  batchSize: 20,
  flushInterval: 5000,
  useWorker: true,
  debug: false,
});

Configuration Options

Core Settings

apiKey

  • Type: string
  • Required: Yes
  • Description: Your AgentShield API key
  • Example: 'as_live_abc123xyz789'
const beacon = new AgentShieldBeacon({
  apiKey: process.env.AGENTSHIELD_API_KEY,
});

endpoint

  • Type: string
  • Default: 'https://kya.vouched.id/v1/beacon'
  • Description: API endpoint for sending events
  • Example: Custom endpoint for enterprise
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  endpoint: 'https://custom.agentshield.io/beacon',
});

Batching Configuration

batchSize

  • Type: number
  • Default: 10
  • Range: 1-100
  • Description: Number of events to batch before sending
// High-traffic site: larger batches
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  batchSize: 50,
});

// Real-time requirements: smaller batches
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  batchSize: 5,
});

flushInterval

  • Type: number
  • Default: 5000 (5 seconds)
  • Range: 1000-60000 (1-60 seconds)
  • Description: Automatic flush interval in milliseconds
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  flushInterval: 10000, // Flush every 10 seconds
});

maxQueueSize

  • Type: number
  • Default: 100
  • Range: 10-1000
  • Description: Maximum events to queue before dropping
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  maxQueueSize: 500, // Allow larger queue
});

Worker Configuration

WebWorker support provides the best performance by moving processing off the main thread.

useWorker

  • Type: boolean
  • Default: true
  • Description: Enable WebWorker for background processing
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  useWorker: true, // Recommended for production
});

workerUrl

  • Type: string
  • Default: Auto-detected
  • Description: Custom worker script URL
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  useWorker: true,
  workerUrl: '/static/beacon-worker.js',
});

workerConfig

  • Type: object
  • Description: Advanced worker settings
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  useWorker: true,
  workerConfig: {
    heartbeatInterval: 5000, // Health check interval
    maxRestartAttempts: 3, // Restart attempts on failure
    enableCompression: true, // Compress messages
    maxRetries: 5, // Network retry attempts
    retryDelay: 2000, // Base retry delay
    maxMemoryUsage: 10485760, // 10MB memory limit
    gcInterval: 30000, // Garbage collection interval
  },
});

Privacy Configuration

respectDoNotTrack

  • Type: boolean
  • Default: true
  • Description: Honor browser DNT header
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  respectDoNotTrack: true, // GDPR compliance
});

anonymizeIp

  • Type: boolean
  • Default: false
  • Description: Anonymize IP addresses
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  anonymizeIp: true, // Remove last octet of IP
});

cookieOptions

  • Type: object
  • Description: Cookie configuration for sessions
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  cookieOptions: {
    name: '_as_session',
    domain: '.example.com',
    path: '/',
    secure: true,
    sameSite: 'strict',
    maxAge: 86400, // 24 hours
  },
});

Session Configuration

sessionTimeout

  • Type: number
  • Default: 1800000 (30 minutes)
  • Description: Session timeout in milliseconds
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  sessionTimeout: 3600000, // 1 hour sessions
});

sessionCookieName

  • Type: string
  • Default: '_as_beacon_session'
  • Description: Name for session cookie
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  sessionCookieName: '_my_session',
});

persistSession

  • Type: boolean
  • Default: true
  • Description: Persist sessions across page loads
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  persistSession: false, // New session each page
});

Network Configuration

retryAttempts

  • Type: number
  • Default: 3
  • Range: 0-10
  • Description: Number of retry attempts for failed requests
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  retryAttempts: 5, // More retries for unreliable networks
});

retryDelay

  • Type: number
  • Default: 2000 (2 seconds)
  • Description: Base delay between retries (uses exponential backoff)
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  retryDelay: 1000, // Start with 1 second
  retryAttempts: 3, // Results in: 1s, 2s, 4s delays
});

timeout

  • Type: number
  • Default: 10000 (10 seconds)
  • Description: Request timeout in milliseconds
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  timeout: 5000, // Faster timeout for better UX
});

Debug Configuration

debug

  • Type: boolean
  • Default: false
  • Description: Enable debug mode
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  debug: process.env.NODE_ENV === 'development',
});

logLevel

  • Type: 'error' | 'warn' | 'info' | 'debug'
  • Default: 'error'
  • Description: Logging verbosity
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  debug: true,
  logLevel: 'debug', // Maximum verbosity
});

logger

  • Type: object
  • Description: Custom logger implementation
const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  logger: {
    error: (msg, ...args) => console.error(`[AS] ${msg}`, ...args),
    warn: (msg, ...args) => console.warn(`[AS] ${msg}`, ...args),
    info: (msg, ...args) => console.info(`[AS] ${msg}`, ...args),
    debug: (msg, ...args) => console.debug(`[AS] ${msg}`, ...args),
  },
});

Environment-Specific Configuration

Development

const devConfig = {
  apiKey: process.env.AGENTSHIELD_API_KEY_DEV,
  endpoint: 'http://localhost:3000/beacon',
  debug: true,
  logLevel: 'debug',
  flushInterval: 2000, // Faster feedback
  batchSize: 1, // Immediate sending
  useWorker: false, // Easier debugging
};

Staging

const stagingConfig = {
  apiKey: process.env.AGENTSHIELD_API_KEY_STAGING,
  endpoint: 'https://staging-kya.vouched.id/v1/beacon',
  debug: true,
  logLevel: 'info',
  flushInterval: 5000,
  batchSize: 10,
  useWorker: true,
};

Production

const productionConfig = {
  apiKey: process.env.AGENTSHIELD_API_KEY,
  endpoint: 'https://kya.vouched.id/v1/beacon',
  debug: false,
  logLevel: 'error',
  flushInterval: 10000,
  batchSize: 50,
  useWorker: true,
  anonymizeIp: true,
  respectDoNotTrack: true,
  retryAttempts: 5,
  maxQueueSize: 500,
};

Dynamic Configuration

Feature Flags

const features = await fetchFeatureFlags();

const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  debug: features.debugMode,
  batchSize: features.optimizedBatching ? 50 : 10,
  useWorker: features.workerEnabled,
});

User-Based Configuration

function getBeaconConfig(user) {
  const baseConfig = {
    apiKey: process.env.AGENTSHIELD_API_KEY,
  };

  if (user.isPremium) {
    return {
      ...baseConfig,
      batchSize: 5, // Faster for premium users
      flushInterval: 2000,
      retryAttempts: 5,
    };
  }

  return {
    ...baseConfig,
    batchSize: 20,
    flushInterval: 10000,
    retryAttempts: 3,
  };
}

Runtime Updates

const beacon = new AgentShieldBeacon({
  apiKey: 'your-key',
  debug: false,
});

// Update configuration at runtime
beacon.updateConfig({
  debug: true,
  logLevel: 'debug',
});

// Respond to user preferences
if (userPreferences.reducedData) {
  beacon.updateConfig({
    batchSize: 50,
    flushInterval: 30000,
  });
}

Performance Profiles

Minimal Impact

// Minimize performance impact
const minimalConfig = {
  apiKey: 'your-key',
  useWorker: true,
  batchSize: 100,
  flushInterval: 30000,
  maxQueueSize: 1000,
  workerConfig: {
    enableCompression: true,
  },
};

Real-Time

// Near real-time tracking
const realtimeConfig = {
  apiKey: 'your-key',
  batchSize: 1,
  flushInterval: 1000,
  retryAttempts: 1,
  timeout: 3000,
};

Balanced

// Balanced performance and accuracy
const balancedConfig = {
  apiKey: 'your-key',
  batchSize: 20,
  flushInterval: 5000,
  useWorker: true,
  retryAttempts: 3,
};

Validation

The beacon validates configuration on initialization:

try {
  const beacon = new AgentShieldBeacon({
    apiKey: '', // Will throw: Invalid API key
    batchSize: 1000, // Will throw: batchSize exceeds maximum
    flushInterval: 100, // Will throw: flushInterval too short
  });
} catch (error) {
  console.error('Invalid configuration:', error.message);
}

Best Practices

Tip: Start with defaults and adjust based on your specific needs and monitoring data.

  1. Use environment variables for sensitive configuration
  2. Enable WebWorker in production for best performance
  3. Adjust batching based on traffic patterns
  4. Respect privacy settings and regulations
  5. Monitor performance and adjust configuration accordingly
  6. Test thoroughly with different configurations
  7. Document your configuration choices

Next Steps

Command Palette

Search for a command to run...