KorreroJS Reference

The official JavaScript/TypeScript SDK for integrating Korrero notifications into your website or web application. Supports both automatic rendering and custom integration modes.

Quick start

Get started in minutes with our Developer Quick Start guide, or dive into the full API reference below.

Installation

Using npm (recommended)

npm install korrero-js
# or
bun add korrero-js

Using CDN

<script src="https://cdn.jsdelivr.net/npm/korrero-js/dist/korrero-js.umd.min.js"></script>

Configuration

Initialize the SDK with your project API key and optional settings:

import { KorreroJS } from 'korrero-js';

const korrero = new KorreroJS({
  apiKey: 'your_project_api_key_here',
  environment: 'development', // 'production' | 'development'
  baseUrl: 'https://api.korrero.com', // Optional custom API URL
  colorSchema: 'auto' // 'light' | 'dark' | 'auto'
});

Option	Required	Type	Default	Description
apiKey	✅	string	-	Your project's public API key from the console
environment	❌	'production' | 'development'	'production'	Controls console logging level
baseUrl	❌	string	'https://api.korrero.com'	Custom API endpoint
colorSchema	❌	'light' | 'dark' | 'auto'	'auto'	Theme for auto-rendered components

Auto-Rendering Mode

Automatically fetch and display system notifications (modals, banners) with zero configuration.

Basic Usage

import { KorreroJS } from 'korrero-js';

const korrero = new KorreroJS({
  apiKey: 'your_project_api_key_here'
});

// Automatically renders active notifications
await korrero.renderAuto();

With CDN

<script src="https://cdn.jsdelivr.net/npm/korrero-js/dist/korrero-js.umd.min.js"></script>
<script>
  const korrero = new KorreroJS({
    apiKey: 'your_project_api_key_here'
  });

  // This single method handles everything
  korrero.renderAuto();
</script>

What happens in auto mode

• Fetches currently active notifications from your project
• Renders system presets (modal, top-banner, bottom-banner)
• Shows only one notification per preset type (newest if multiple)
• Automatically tracks impressions
• Handles user interactions and click tracking
• Respects user preferences (session-based dismissal)

Manual Integration Mode

Fetch notification data and integrate it into your own custom UI components.

Fetching Notifications

// Get all notifications for your project
const allNotifications = await korrero.getNotifications();

// Get only currently active notifications
const activeNotifications = await korrero.getActiveNotifications();

Custom Rendering

import { KorreroJS } from 'korrero-js';

const korrero = new KorreroJS({
  apiKey: 'your_project_api_key_here'
});

const notifications = await korrero.getActiveNotifications();

notifications.forEach(notification => {
  // Create your own custom UI
  const card = document.createElement('div');
  card.className = 'my-notification-card';

  // Render rich text content
  card.innerHTML = korrero.renderText(notification.message);

  // Track when user sees it
  await korrero.track(notification.id, 'impression');

  // Handle clicks
  card.addEventListener('click', async () => {
    await korrero.track(notification.id, 'click');
    // Your custom action logic
  });

  document.body.appendChild(card);
});

Rich Text Rendering

Convert notification messages (JSON or plain text) to styled HTML.

Full Rich Text

const html = korrero.renderText(notification.message);
// Supports: paragraphs, headings, links, text styling, highlights

Single Line Text

const html = korrero.renderTextOneLine(notification.message);
// Strips block elements, keeps inline formatting only

Rich text features

• Text formatting: Bold, italic, underline, colors
• Highlights: Background colors for emphasis
• Links: Clickable URLs with hover effects
• Responsive: Uses clamp() for smooth scaling across devices
• Theme-aware: Automatically adapts to light/dark themes

Theme Management

Control the visual theme for auto-rendered components.

Automatic Theme Detection

const korrero = new KorreroJS({
  apiKey: 'your_project_api_key_here',
  colorSchema: 'auto' // Follows system preference
});

Manual Theme Control

// Set initial theme
const korrero = new KorreroJS({
  apiKey: 'your_project_api_key_here',
  colorSchema: 'dark' // Force dark theme
});

// Change theme dynamically
korrero.updateColorSchema('light'); // Switch to light theme
korrero.updateColorSchema('auto');  // Back to system preference

Theme behavior

• Auto mode: Listens for system theme changes and updates automatically
• Manual mode: Fixed theme that doesn't change with system settings
• Dynamic updates: Can be changed at runtime without reinitializing

Interaction Tracking

Track user engagement with notifications for analytics.

Manual Tracking

// Track when user sees a notification
await korrero.track(notificationId, 'impression');

// Track when user clicks a notification
await korrero.track(notificationId, 'click');

Tracking details

• Automatic in auto mode: Impressions and clicks are tracked automatically
• Manual mode requirement: Must call track() yourself for analytics
• No personal data: Only tracks interaction events, no user identification
• Error handling: Fails silently if tracking endpoint is unavailable

Advanced Usage

Custom Configuration

const korrero = new KorreroJS({
  apiKey: 'your_project_api_key_here',
  environment: 'development', // Enable debug logging
  baseUrl: 'https://my-custom-api.com', // Custom API endpoint
  colorSchema: 'dark' // Force dark theme
});

Cleanup

// Remove event listeners when component unmounts (SPA)
korrero.destroy();

Error Handling

try {
  await korrero.renderAuto();
} catch (error) {
  console.error('Failed to render notifications:', error);
  // Graceful fallback - show nothing or custom error UI
}

API Reference

Constructor

new KorreroJS(config: KorreroConfig): KorreroJS

Creates a new SDK instance with the provided configuration.

Methods

renderAuto(): Promise<void>

Automatically fetches and renders active system notifications (modals, banners).

getNotifications(): Promise<PublicNotification[]>

Fetches all notifications for the configured API key.

getActiveNotifications(): Promise<PublicNotification[]>

Fetches only currently active notifications (within start/end dates).

track(notificationId: string, type: 'impression' | 'click'): Promise<void>

Tracks an interaction event for analytics.

renderText(message: string): string

Converts a notification message to styled HTML with full rich text support.

renderTextOneLine(message: string): string

Converts a notification message to single-line HTML (removes block elements).

updateColorSchema(schema: 'light' | 'dark' | 'auto'): void

Updates the color theme for auto-rendered components.

destroy(): void

Removes event listeners and cleans up resources.

TypeScript Support

The SDK includes full TypeScript definitions for better development experience.

import type {
  KorreroConfig,
  PublicNotification,
  NotificationAction
} from 'korrero-js';

Browser Support

• Modern browsers: Chrome 90+, Firefox 88+, Safari 14+, Edge 90+
• Mobile: iOS Safari 14+, Chrome Mobile 90+
• No dependencies: Pure JavaScript, no external libraries required

Troubleshooting

Common issues

• Notifications not appearing? Check your API key is correct and the project has active notifications
• Styling issues? Ensure no conflicting CSS rules, or use manual mode for full control
• Theme not updating? Check if you're using 'auto' mode and the system supports media queries
• Tracking failing? Verify your API key has permission to track interactions
• Browser compatibility? Ensure you're using a modern browser (Chrome 90+, Firefox 88+, Safari 14+)

For detailed troubleshooting, contact support.

Examples

See our Quick Start for Developers for complete working examples of both auto and manual integration modes.

For advanced customisation examples, check the GitHub Example.