Configuration

The Traise Widget offers configuration options to customize its appearance and behavior to match your application's needs.

Basic Configuration

const { init } = window.TraiseWidget;

const widget = await init({
  apiKey: 'your-api-key',  // Required
  mode: 'light',           // Optional
  position: 'bottom-right' // Optional
});

Configuration Options

Required Options

Option	Type	Description
apiKey	string	Your Traise API key for authentication

UI Customization

Option	Type	Default	Description
mode	'light' | 'dark'	'light'	Widget color mode
position	'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'	'bottom-right'	Widget position on screen

User Information

Option	Type	Default	Description
userId	string	''	User identifier
firstName	string	''	User's first name
lastName	string	''	User's last name

Feature Flags

Option	Type	Default	Description
debug	boolean	false	Enable debug mode and debug panel
demoMode	boolean	false	Enable demo mode with simulated data

Demo Mode

Use demo mode to test the widget without a real API key:

traise('init', { demoMode: true, debug: true });

Demo mode provides simulated data including mock alerts and bypasses API authentication.

Complete Configuration Example

const { init, show } = window.TraiseWidget;

const config = {
  // Required
  apiKey: 'your-api-key-here',

  // UI Settings
  mode: 'light',
  position: 'bottom-right',

  // User Information
  userId: 'user-123',
  firstName: 'John',
  lastName: 'Doe',

  // Development
  debug: false,
  demoMode: false
};

const widget = await init(config);

// Check initialization status
const status = widget.getStatus();
if (status.initialized) {
  console.log('Widget initialized successfully!');
  show(); // Show the widget

  // Set up event listeners
  widget.on('error', (error) => {
    console.error('Widget error:', error);
  });
} else {
  console.error('Failed to initialize widget');
}

Dynamic Configuration Updates

You can update configuration after initialization:

const { updateConfig, getConfig } = window.TraiseWidget;

// Get current configuration
const currentConfig = getConfig();
console.log('Current mode:', currentConfig.mode);

// Update configuration
updateConfig({
  mode: 'dark',
  position: 'top-left'
});

// Toggle debug mode
updateConfig({
  debug: !currentConfig.debug
});

Configuration Validation

The widget automatically validates configuration and provides helpful feedback:

// Invalid position - will use default 'bottom-right'
const config = {
  apiKey: 'your-api-key',
  position: 'center' // Invalid - will default to 'bottom-right'
};

// Missing API key - will show error
const config = {
  mode: 'light'
  // Missing apiKey - initialization will fail with clear error
};

Security Considerations

API Key Management

Never hardcode API keys in your source code:

// Bad - Never do this
const config = {
  apiKey: 'widget_1234abcd'
};

// Good - Use environment variables
const config = {
  apiKey: process.env.TRAISE_WIDGET_API_KEY
};

// Better - Proxy through your backend
const config = {
  apiKey: await fetchApiKeyFromBackend()
};

Content Security Policy

If using CSP, add these directives:

<meta http-equiv="Content-Security-Policy" content="
  script-src 'self' https://widget.traise.app;
  style-src 'self' 'unsafe-inline';
  connect-src 'self' https://api.traise.com wss://api.traise.com;
  media-src 'self' https://media.twiliocdn.com;
">

Troubleshooting Configuration

Debug Mode

Enable debug mode to see detailed logs:

const config = {
  apiKey: 'your-api-key',
  debug: true // Shows debug panel and verbose logging
};

// Access debug panel with Shift+D when widget is open

Common Issues

Issue	Solution
Widget not appearing	Check API key validity and HTTPS requirement
Wrong position	Verify position value is valid
Mode not applying	Verify mode value is 'light' or 'dark'
WebSocket issues	Check firewall allows WSS protocol

Next Steps

• API Reference - Complete API documentation
• Events - Event reference and handling
• Customization Guide - Theme and styling