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.
- Use environment variables for sensitive configuration
- Enable WebWorker in production for best performance
- Adjust batching based on traffic patterns
- Respect privacy settings and regulations
- Monitor performance and adjust configuration accordingly
- Test thoroughly with different configurations
- Document your configuration choices
Next Steps
- Worker Mode - Deep dive into WebWorker optimization
- Events - Event handling guide
- API Reference - Complete API documentation