Configuration

Learn how to configure the Apta SDK with all available options and customization settings.

Configuration

The Apta SDK offers extensive configuration options to customize the crypto assistant chat experience for your specific needs.

Basic Configuration

The minimal configuration requires only partnerKey:

const chat = new Apta({
  partnerKey: 'your-partner-key'
});

Complete Configuration Options

Core Options

interface AptaInitOptions {
  // Required
  partnerKey: string;
  
  // Optional
  container?: HTMLElement | string;
  containerStyle?: Record<string, string | number>;
  containerClass?: string | string[];
  mode?: 'default' | 'full' | 'popup' | 'drawer';
  theme?: 'light' | 'dark' | 'system';
  popupOptions?: PopupOptions;
  drawerOptions?: DrawerOptions;
  splashScreen?: boolean | { customHTML?: string | HTMLElement; };
  colors?: IColorOptions | { default?: IColorOptions; dark?: IColorOptions; };
  customLogo?: string | { dark: string; light: string };
}

Display Modes

Default Mode

Embeds the chat directly into a container element.

const chat = new Apta({
  partnerKey: 'your-partner-key',
  container: '#chat-container',
  mode: 'default'
});

Shows chat in a floating popup with a toggle button.

const chat = new Apta({
  partnerKey: 'your-partner-key',
  mode: 'popup',
  popupOptions: {
    width: '400px',
    height: '600px',
    position: 'bottom-right',
    customToggleButton: '#my-custom-button'
  }
});

Drawer Mode

Displays chat as a slide-in panel from the side.

const chat = new Apta({
  partnerKey: 'your-partner-key',
  mode: 'drawer',
  drawerOptions: {
    width: '350px',
    position: 'right'
  }
});

Full Mode

Takes over the entire screen for an immersive experience.

const chat = new Apta({
  partnerKey: 'your-partner-key',
  mode: 'full'
});

interface PopupOptions {
  width?: string;           // Default: '400px'
  height?: string;          // Default: '600px'
  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
  customToggleButton?: string | HTMLElement;
  containerClass?: string | string[];
}

Custom size and position:

popupOptions: {
  width: '500px',
  height: '700px',
  position: 'bottom-left'
}

Custom toggle button:

popupOptions: {
  customToggleButton: document.getElementById('help-button')
  // or
  customToggleButton: '#help-button'
}

Drawer Options

interface DrawerOptions {
  width?: string;           // Default: '400px'
  position?: 'left' | 'right';  // Default: 'right'
  closeButtonDisabled?: boolean; // NEW: disables the close button if true
  containerClass?: string | string[];
}

New Option:

  • closeButtonDisabled?: boolean — Set to true to hide/disable the close button in the drawer UI. Default is false (close button is shown).

Drawer Examples

Left-side drawer:

drawerOptions: {
  width: '300px',
  position: 'left'
}

Drawer with close button disabled:

drawerOptions: {
  width: '350px',
  position: 'right',
  closeButtonDisabled: true
}

Styling and Theming

Theme Options

const chat = new Apta({
  partnerKey: 'your-partner-key',
  theme: 'dark' // 'light', 'dark', or 'system'
});

Custom Colors

You can customize colors in two ways:

Single Color Scheme

Apply the same colors to both light and dark modes:

const chat = new Apta({
  partnerKey: 'your-partner-key',
  colors: {
    primary: '#3b82f6',
    secondary: '#64748b',
    background: '#ffffff',
    border: '#e2e8f0',
    text: '#1e293b',
    ring: '#3b82f6'
  }
});

Separate Light and Dark Color Schemes

Define different colors for light and dark modes:

const chat = new Apta({
  partnerKey: 'your-partner-key',
  colors: {
    default: {
      primary: '#3b82f6',
      secondary: '#64748b',
      background: '#ffffff',
      border: '#e2e8f0',
      text: '#1e293b',
      ring: '#3b82f6'
    },
    dark: {
      primary: '#60a5fa',
      secondary: '#94a3b8',
      background: '#0f172a',
      border: '#334155',
      text: '#f1f5f9',
      ring: '#60a5fa'
    }
  }
});

Add your own logo that will appear in the chat interface:

Use the same logo for both light and dark themes:

const chat = new Apta({
  partnerKey: 'your-partner-key',
  customLogo: 'https://example.com/logo.png' // PNG, SVG, or JPG
});

Theme-Specific Logos

Use different logos for light and dark themes:

const chat = new Apta({
  partnerKey: 'your-partner-key',
  customLogo: {
    light: 'https://example.com/logo-light.png',
    dark: 'https://example.com/logo-dark.png'
  }
});

Splash Screen

Control the splash screen behavior:

// Disable splash screen
const chat = new Apta({
  partnerKey: 'your-partner-key',
  splashScreen: false
});

// Enable with custom HTML
const chat = new Apta({
  partnerKey: 'your-partner-key',
  splashScreen: {
    customHTML: '<div class="custom-splash">Loading Crypto Assistant...</div>'
  }
});

Custom Container Styling

const chat = new Apta({
  partnerKey: 'your-partner-key',
  container: '#chat-container',
  containerStyle: {
    borderRadius: '12px',
    boxShadow: '0 4px 12px rgba(0,0,0,0.15)',
    border: '1px solid #e1e5e9'
  },
  containerClass: ['custom-chat', 'rounded-lg']
});

Advanced Configuration Examples

Crypto Trading Platform Integration

const cryptoChat = new Apta({
  partnerKey: 'crypto-platform-key',
  mode: 'popup',
  theme: 'dark',
  popupOptions: {
    width: '450px',
    height: '650px',
    position: 'bottom-right'
  },
  colors: {
    default: {
      primary: '#f59e0b',
      secondary: '#6b7280',
      background: '#ffffff',
      border: '#e5e7eb',
      text: '#111827'
    },
    dark: {
      primary: '#fbbf24',
      secondary: '#9ca3af',
      background: '#1f2937',
      border: '#374151',
      text: '#f9fafb'
    }
  },
  customLogo: {
    light: '/logo-light.png',
    dark: '/logo-dark.png'
  }
});

Mobile-First Crypto Assistant

const mobileChat = new Apta({
  partnerKey: 'mobile-crypto-key',
  mode: 'drawer',
  theme: 'system',
  drawerOptions: {
    width: '100%',
    position: 'right'
  },
  colors: {
    primary: '#10b981',
    secondary: '#6b7280',
    background: '#f9fafb',
    text: '#111827'
  }
});

Full-Screen Crypto Analysis Experience

const analysisChat = new Apta({
  partnerKey: 'analysis-platform-key',
  mode: 'full',
  theme: 'dark',
  colors: {
    primary: '#8b5cf6',
    secondary: '#6b7280',
    background: '#0f172a',
    border: '#1e293b',
    text: '#f1f5f9'
  },
  customLogo: 'https://example.com/analysis-logo.svg',
  splashScreen: {
    customHTML: '<div class="loading-spinner">Initializing AI Crypto Assistant...</div>'
  }
});

Configuration Validation

The SDK automatically validates your configuration and will throw helpful errors:

// ❌ This will throw an error
const chat = new Apta({
  // Missing partnerKey
  container: '#chat'
});
// Error: Partner Key is required for Apta initialization

// ❌ This will throw an error  
const chat = new Apta({
  partnerKey: 'partner-123',
  mode: 'default'
  // Missing container for default mode
});
// Error: Container is required for Apta initialization

Environment-Specific Configuration

Development

const chat = new Apta({
  partnerKey: 'dev-partner-key',
  container: '#chat-container',
  theme: 'light'
});

Production

const chat = new Apta({
  partnerKey: process.env.APTA_PARTNER_KEY,
  container: '#chat-container',
  mode: 'popup',
  theme: 'system',
  colors: {
    primary: '#your-brand-color',
    background: '#ffffff'
  },
  customLogo: 'https://yourdomain.com/logo.png'
});

Next Steps