SDK Initialization - Journium Documentation

Journium.init()

Initialize the Journium SDK with your project configuration.

Syntax

Journium.init(config)

Parameters

projectId

string

required

Your unique project identifier from the Journium dashboard

apiKey

string

required

Your public API key for client-side tracking

environment

string

required

Environment setting: 'development' or 'production'

config

object

Optional configuration object with additional settings

Show Configuration Options

trackPageViews

boolean

default:"true"

Automatically track page view events

trackClicks

boolean

default:"true"

Automatically track click events on buttons and links

trackScrolling

boolean

default:"true"

Track scroll depth and user engagement

trackFormSubmissions

boolean

default:"true"

Track form submissions and interactions

enableRecommendations

boolean

default:"true"

Enable AI-powered conversion recommendations

trackPerformance

boolean

default:"false"

Track performance metrics and Core Web Vitals

trackErrors

boolean

default:"false"

Automatically track JavaScript errors and exceptions

debugMode

boolean

default:"false"

Enable debug logging and verbose output

batchSize

number

default:"10"

Number of events to batch before sending to server

flushInterval

number

default:"5000"

Time in milliseconds between automatic event flushes

respectDoNotTrack

boolean

default:"true"

Respect the user’s Do Not Track browser setting

anonymizeIPs

boolean

default:"true"

Anonymize IP addresses for privacy compliance

Examples

Basic Initialization

Journium.init({
  projectId: 'proj_1234567890',
  apiKey: 'pk_live_abcdef123456',
  environment: 'production'
});

Advanced Configuration

Journium.init({
  projectId: 'proj_1234567890',
  apiKey: 'pk_live_abcdef123456',
  environment: 'production',
  
  config: {
    // Core tracking
    trackPageViews: true,
    trackClicks: true,
    trackScrolling: true,
    trackFormSubmissions: true,
    
    // Advanced features
    enableRecommendations: true,
    trackPerformance: true,
    trackErrors: true,
    
    // Performance optimization
    batchSize: 20,
    flushInterval: 3000,
    
    // Privacy settings
    respectDoNotTrack: true,
    anonymizeIPs: true,
    
    // Debug settings
    debugMode: false
  }
});

Environment-Specific Configuration

const isDevelopment = process.env.NODE_ENV === 'development';

Journium.init({
  projectId: isDevelopment ? 'proj_dev_123' : 'proj_prod_456',
  apiKey: isDevelopment ? 'pk_test_dev123' : 'pk_live_prod456',
  environment: isDevelopment ? 'development' : 'production',
  
  config: {
    debugMode: isDevelopment,
    trackClicks: !isDevelopment, // Reduce noise in development
    batchSize: isDevelopment ? 1 : 10, // Send immediately in dev
    flushInterval: isDevelopment ? 100 : 5000
  }
});

Return Value

The init() method returns a Promise that resolves when initialization is complete:

Journium.init(config)
  .then(() => {
    console.log('Journium initialized successfully');
    // Start tracking events
    Journium.track('app_initialized');
  })
  .catch((error) => {
    console.error('Failed to initialize Journium:', error);
  });

Error Handling

The initialization can fail for several reasons:

try {
  await Journium.init({
    projectId: 'proj_1234567890',
    apiKey: 'pk_live_abcdef123456',
    environment: 'production'
  });
} catch (error) {
  if (error.code === 'INVALID_API_KEY') {
    console.error('Invalid API key provided');
  } else if (error.code === 'NETWORK_ERROR') {
    console.error('Network connection failed');
  } else {
    console.error('Initialization failed:', error.message);
  }
}

Common error codes:

INVALID_API_KEY - API key is invalid or expired
INVALID_PROJECT_ID - Project ID not found
NETWORK_ERROR - Cannot connect to Journium servers
INVALID_CONFIG - Configuration object is malformed
ALREADY_INITIALIZED - SDK has already been initialized

Journium.ready()

Wait for the SDK to be fully initialized and ready to track events.

Syntax

Journium.ready(callback)
// or
Journium.ready().then(callback)

Parameters

callback

function

Function to execute when the SDK is ready

Examples

Callback Style

Journium.ready(() => {
  console.log('Journium is ready!');
  Journium.track('sdk_ready');
});

Promise Style

Journium.ready().then(() => {
  console.log('Journium is ready!');
  Journium.track('sdk_ready');
});

// Or with async/await
async function initApp() {
  await Journium.ready();
  console.log('Journium is ready!');
  Journium.track('sdk_ready');
}

With Timeout

Promise.race([
  Journium.ready(),
  new Promise((_, reject) => 
    setTimeout(() => reject(new Error('Timeout')), 5000)
  )
]).then(() => {
  console.log('Journium is ready!');
}).catch((error) => {
  console.warn('Journium initialization timeout:', error);
  // Continue without analytics
});

Journium.isReady()

Check if the SDK is currently ready to track events.

Syntax

const ready = Journium.isReady()

Return Value

Returns a boolean indicating whether the SDK is ready:

true - SDK is initialized and ready
false - SDK is not ready (still initializing or failed)

Examples

if (Journium.isReady()) {
  Journium.track('button_clicked', { button_id: 'signup' });
} else {
  console.log('Journium not ready yet');
}

Conditional Tracking

function trackEvent(eventName, properties) {
  if (Journium.isReady()) {
    Journium.track(eventName, properties);
  } else {
    console.warn('Journium not ready, event queued:', eventName);
    // Optionally queue events for later
    queueEvent(eventName, properties);
  }
}

Journium.getConfig()

Get the current SDK configuration.

Syntax

const config = Journium.getConfig()

Return Value

Returns the current configuration object:

{
  projectId: 'proj_1234567890',
  apiKey: 'pk_live_abcdef123456',
  environment: 'production',
  config: {
    trackPageViews: true,
    trackClicks: true,
    // ... other configuration options
  },
  version: '1.2.0',
  initialized: true
}

Examples

const config = Journium.getConfig();
console.log('Current environment:', config.environment);
console.log('Tracking page views:', config.config.trackPageViews);
console.log('SDK version:', config.version);

Debug Configuration

function debugConfiguration() {
  const config = Journium.getConfig();
  
  console.group('Journium Configuration');
  console.log('Project ID:', config.projectId);
  console.log('Environment:', config.environment);
  console.log('Version:', config.version);
  console.log('Initialized:', config.initialized);
  console.table(config.config);
  console.groupEnd();
}

// Call when debugging
if (config.config.debugMode) {
  debugConfiguration();
}

Journium.updateConfig()

Update configuration settings after initialization.

Syntax

Journium.updateConfig(newConfig)

Parameters

newConfig

object

required

Object containing configuration updates. Only includes changed settings.

Examples

// Enable additional tracking after user consent
Journium.updateConfig({
  trackClicks: true,
  trackScrolling: true,
  trackPerformance: true
});

// Update batch settings for better performance
Journium.updateConfig({
  batchSize: 50,
  flushInterval: 10000
});

Conditional Updates

function updateTrackingBasedOnConsent(consentGiven) {
  if (consentGiven) {
    Journium.updateConfig({
      trackClicks: true,
      trackScrolling: true,
      trackFormSubmissions: true,
      trackPerformance: true
    });
  } else {
    Journium.updateConfig({
      trackClicks: false,
      trackScrolling: false,
      trackFormSubmissions: false,
      trackPerformance: false
    });
  }
}

Journium.getStatus()

Get detailed status information about the SDK.

Syntax

const status = Journium.getStatus()

Return Value

Returns a status object with detailed information:

{
  initialized: true,
  ready: true,
  connected: true,
  lastFlush: 1640995200000,
  queueSize: 5,
  totalEvents: 1247,
  errors: 0,
  version: '1.2.0',
  uptime: 3600000
}

Examples

const status = Journium.getStatus();

console.log('SDK Status:', {
  ready: status.ready,
  queue: status.queueSize,
  total_events: status.totalEvents
});

// Health check
if (!status.connected) {
  console.warn('Journium connection lost');
}

Status Monitoring

function monitorSDKHealth() {
  setInterval(() => {
    const status = Journium.getStatus();
    
    // Alert if queue is getting too large
    if (status.queueSize > 100) {
      console.warn('Event queue is getting large:', status.queueSize);
    }
    
    // Alert if there are errors
    if (status.errors > 0) {
      console.error('SDK has encountered errors:', status.errors);
    }
    
    // Alert if not connected
    if (!status.connected) {
      console.error('SDK is not connected to servers');
    }
  }, 30000); // Check every 30 seconds
}

// Start monitoring in production
if (Journium.getConfig().environment === 'production') {
  monitorSDKHealth();
}

Best Practices

1. Initialize Early

// ✅ Initialize as early as possible in your app
document.addEventListener('DOMContentLoaded', () => {
  Journium.init({
    projectId: 'your-project-id',
    apiKey: 'your-api-key',
    environment: 'production'
  });
});

// ❌ Don't wait for user interactions
document.getElementById('button').addEventListener('click', () => {
  // Too late - you'll miss early page views and interactions
  Journium.init(config);
});

2. Handle Initialization Failures Gracefully

// ✅ Your app should work even if analytics fails
async function initializeApp() {
  try {
    await Journium.init(config);
    console.log('Analytics initialized');
  } catch (error) {
    console.warn('Analytics failed to initialize:', error);
    // App continues to work normally
  }
  
  // Continue with app initialization
  startApp();
}

3. Environment-Specific Configuration

// ✅ Use different settings for different environments
const getConfig = () => {
  const base = {
    projectId: process.env.JOURNIUM_PROJECT_ID,
    apiKey: process.env.JOURNIUM_API_KEY
  };
  
  if (process.env.NODE_ENV === 'development') {
    return {
      ...base,
      environment: 'development',
      config: {
        debugMode: true,
        trackClicks: false,
        batchSize: 1
      }
    };
  }
  
  return {
    ...base,
    environment: 'production',
    config: {
      debugMode: false,
      trackClicks: true,
      batchSize: 20
    }
  };
};

Journium.init(getConfig());

4. Progressive Enhancement

// ✅ Start with basic tracking, add features progressively
Journium.init({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  environment: 'production',
  config: {
    trackPageViews: true, // Start with essentials
    trackClicks: false,
    trackScrolling: false
  }
});

// After user grants consent or interacts with the app
function enableAdvancedTracking() {
  Journium.updateConfig({
    trackClicks: true,
    trackScrolling: true,
    trackPerformance: true
  });
}

5. Error Monitoring

// ✅ Monitor SDK health and performance
function setupSDKMonitoring() {
  // Log initialization success/failure
  Journium.init(config)
    .then(() => {
      console.log('✅ Journium initialized successfully');
      
      // Send success event to your error tracking
      yourErrorTracker.log('journium_init_success');
    })
    .catch((error) => {
      console.error('❌ Journium initialization failed:', error);
      
      // Send failure event to your error tracking
      yourErrorTracker.error('journium_init_failed', error);
    });
  
  // Periodic health checks
  setInterval(() => {
    const status = Journium.getStatus();
    
    if (!status.connected || status.errors > 0) {
      yourErrorTracker.warn('journium_health_issue', status);
    }
  }, 300000); // Every 5 minutes
}

Troubleshooting

Common Issues

“Journium is not defined” error

Ensure the SDK script is loaded before calling init()
Check that the CDN URL is correct and accessible

Initialization hangs or times out

Check your network connection
Verify your API key and project ID are correct
Check the browser console for error messages

Events not appearing in dashboard

Verify you’re using the correct environment (development/production)
Check that your project ID and API key match
Ensure events are being tracked after Journium.ready() resolves

“Already initialized” error

init() can only be called once per page load
Use updateConfig() to change settings after initialization

Next Steps

Event Tracking

Learn how to track custom events and user actions

User Identification

Identify and manage user data

SDK Methods

REST API

​Journium.init()

​Syntax

​Parameters

​Examples

​Basic Initialization

​Advanced Configuration

​Environment-Specific Configuration

​Return Value

​Error Handling

​Journium.ready()

​Syntax

​Parameters

​Examples

​Callback Style

​Promise Style

​With Timeout

​Journium.isReady()

​Syntax

​Return Value

​Examples

​Conditional Tracking

​Journium.getConfig()

​Syntax

​Return Value

​Examples

​Debug Configuration

​Journium.updateConfig()

​Syntax

​Parameters

​Examples

​Conditional Updates

​Journium.getStatus()

​Syntax

​Return Value

​Examples

​Status Monitoring

​Best Practices

​1. Initialize Early

​2. Handle Initialization Failures Gracefully

​3. Environment-Specific Configuration

​4. Progressive Enhancement

​5. Error Monitoring

​Troubleshooting

​Common Issues

​Next Steps

Event Tracking

User Identification

Journium.init()

Syntax

Parameters

Examples

Basic Initialization

Advanced Configuration

Environment-Specific Configuration

Return Value

Error Handling

Journium.ready()

Syntax

Parameters

Examples

Callback Style

Promise Style

With Timeout

Journium.isReady()

Syntax

Return Value

Examples

Conditional Tracking

Journium.getConfig()

Syntax

Return Value

Examples

Debug Configuration

Journium.updateConfig()

Syntax

Parameters

Examples

Conditional Updates

Journium.getStatus()

Syntax

Return Value

Examples

Status Monitoring

Best Practices

1. Initialize Early

2. Handle Initialization Failures Gracefully

3. Environment-Specific Configuration

4. Progressive Enhancement

5. Error Monitoring

Troubleshooting

Common Issues

Next Steps