Common Issues & Solutions

Installation Issues

SDK Not Loading

Problem: “Journium is not defined” error in browser console.

CDN Script Not Loading

Symptoms:

Console error: Uncaught ReferenceError: Journium is not defined
No network request to CDN visible in DevTools

Solutions:

<!-- ✅ Correct CDN URL -->
<script src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>

<!-- ❌ Common mistakes -->
<script src="https://cdn.journium.com/journium.js"></script> <!-- Wrong path -->
<script src="https://journium.com/sdk/journium.js"></script> <!-- Wrong domain -->

Debugging steps:

Check Network tab in DevTools for failed requests
Verify the CDN URL is accessible in a new browser tab
Check for Content Security Policy blocking external scripts
Try loading the script directly: curl -I https://cdn.journium.com/sdk/v1/journium.min.js

Script Loading Order

Problem: Trying to use Journium before the script has loaded.

// ❌ Wrong: Script hasn't loaded yet
<script src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>
<script>
  Journium.init({ ... }); // Error: Journium is not defined
</script>

// ✅ Correct: Wait for script to load
<script src="https://cdn.journium.com/sdk/v1/journium.min.js" onload="initJournium()"></script>
<script>
  function initJournium() {
    Journium.init({ ... });
  }
</script>

// ✅ Alternative: Check if loaded
<script>
  function waitForJournium() {
    if (typeof Journium !== 'undefined') {
      Journium.init({ ... });
    } else {
      setTimeout(waitForJournium, 100);
    }
  }
  waitForJournium();
</script>

NPM Installation Issues

Problem: Module not found after npm install @journium/sdk.

Import Path Issues

// ❌ Common import mistakes
import Journium from 'journium'; // Wrong package name
import { Journium } from '@journium/sdk'; // Wrong import syntax
import Journium from '@journium/sdk/dist/journium'; // Wrong path

// ✅ Correct imports
import Journium from '@journium/sdk';

// Or CommonJS
const Journium = require('@journium/sdk');

Build Tool Configuration

Webpack Configuration:

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      '@journium/sdk': path.resolve(__dirname, 'node_modules/@journium/sdk')
    }
  }
};

Vite Configuration:

// vite.config.js
export default {
  optimizeDeps: {
    include: ['@journium/sdk']
  }
};

Next.js Configuration:

// next.config.js
module.exports = {
  transpilePackages: ['@journium/sdk']
};

Authentication & Configuration Issues

Invalid API Key

Problem: Authentication fails with invalid API key error.

API Key Format Issues

Symptoms:

Console error: Invalid API key format
401 Unauthorized responses
Events not appearing in dashboard

Check your API key format:

// ✅ Correct API key formats
const publicKey = 'pk_live_abcd1234567890efgh';     // Live public key
const testKey = 'pk_test_abcd1234567890efgh';       // Test public key

// ❌ Common mistakes
const wrongKey1 = 'sk_live_abcd1234567890efgh';     // Secret key (server-only)
const wrongKey2 = 'abcd1234567890efgh';             // Missing prefix
const wrongKey3 = 'pk-live-abcd1234567890efgh';     // Wrong separators

Verification steps:

Check the Journium dashboard for correct keys
Ensure you’re using the public key (starts with pk_) for client-side
Verify the environment (live/test) matches your configuration

Environment Mismatch

// ❌ Common environment issues
Journium.init({
  projectId: 'proj_live_12345',
  apiKey: 'pk_test_abcd1234',  // Test key with live project
  environment: 'production'    // Environment doesn't match key
});

// ✅ Correct configuration
Journium.init({
  projectId: process.env.NODE_ENV === 'production' 
    ? 'proj_live_12345' 
    : 'proj_test_12345',
  apiKey: process.env.NODE_ENV === 'production'
    ? 'pk_live_abcd1234'
    : 'pk_test_abcd1234',
  environment: process.env.NODE_ENV === 'production' 
    ? 'production' 
    : 'development'
});

Project Not Found

Problem: Project ID not found error.

Project ID Issues

Common causes:

Typo in project ID
Using wrong project (development vs production)
Project has been deleted or suspended

Debugging:

// Log your configuration to verify
console.log('Journium Config:', {
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  environment: 'your-environment'
});

// Check if project exists
fetch(`https://api.journium.com/v1/projects/${projectId}`, {
  headers: { 'Authorization': `Bearer ${apiKey}` }
})
.then(response => {
  if (response.status === 404) {
    console.error('Project not found');
  } else if (response.status === 401) {
    console.error('Invalid API key');
  }
});

Event Tracking Issues

Events Not Appearing in Dashboard

Problem: Events are tracked but don’t show up in the dashboard.

Event Processing Delay

Normal processing times:

Real-time events: 10-30 seconds
Batch processed events: 1-5 minutes
Dashboard updates: 2-10 minutes

Check processing status:

// Enable debug mode to see event status
Journium.init({
  // ... other config
  config: {
    debugMode: true
  }
});

// Check queue status
console.log('Queue status:', Journium.getStatus());

Event Validation Errors

Common validation issues:

// ❌ Invalid event names
Journium.track('user signed up');      // Spaces not allowed
Journium.track('user-signed-up');      // Hyphens not recommended
Journium.track('USER_SIGNED_UP');      // All caps not recommended

// ✅ Valid event names  
Journium.track('user_signed_up');
Journium.track('userSignedUp');        // camelCase acceptable

// ❌ Invalid property values
Journium.track('purchase', {
  amount: 'twenty dollars',            // Should be number
  user: { complex: { object: true } }  // Too deeply nested
});

// ✅ Valid properties
Journium.track('purchase', {
  amount: 20.00,
  currency: 'USD',
  user_id: 'user123'
});

Environment Configuration

Check environment settings:

// Verify you're looking at the right environment in dashboard
const config = Journium.getConfig();
console.log('Current environment:', config.environment);
console.log('Project ID:', config.projectId);

// Events sent to 'development' won't appear in 'production' dashboard

Dashboard environment switcher:

Go to your Journium dashboard
Check the environment selector (top-right)
Make sure it matches your SDK environment setting

Duplicate Events

Problem: Same events being tracked multiple times.

Multiple SDK Initializations

// ❌ Common cause: Multiple init calls
Journium.init(config);
// ... later in code
Journium.init(config); // This creates duplicate tracking

// ✅ Solution: Check if already initialized
if (!Journium.isReady()) {
  Journium.init(config);
}

// ✅ Or use a flag
let journiumInitialized = false;
if (!journiumInitialized) {
  Journium.init(config);
  journiumInitialized = true;
}

React Component Re-renders

// ❌ Problem: Effect runs on every render
function MyComponent() {
  useEffect(() => {
    Journium.track('component_viewed'); // Tracks on every re-render
  });
}

// ✅ Solution: Add dependency array
function MyComponent() {
  useEffect(() => {
    Journium.track('component_viewed');
  }, []); // Empty array = run only once
}

// ✅ Alternative: Track only meaningful changes
function MyComponent({ productId }) {
  useEffect(() => {
    Journium.track('product_viewed', { product_id: productId });
  }, [productId]); // Only track when productId changes
}

Performance Issues

Slow Page Loading

Problem: Journium SDK is slowing down page load.

Script Loading Optimization

<!-- ❌ Blocking script load -->
<head>
  <script src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>
</head>

<!-- ✅ Non-blocking async load -->
<head>
  <script async src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>
</head>

<!-- ✅ Defer until page is parsed -->
<head>
  <script defer src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>
</head>

<!-- ✅ Load at end of body -->
<body>
  <!-- Your content -->
  <script src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>
</body>

Configuration Optimization

// ✅ Optimize for performance
Journium.init({
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  environment: 'production',
  
  config: {
    // Reduce tracking overhead
    trackScrolling: false,        // High-frequency events
    trackMouseMovement: false,    // Very high-frequency
    
    // Optimize batching
    batchSize: 50,               // Larger batches
    flushInterval: 10000,        // Less frequent flushes
    
    // Reduce payload size
    trackUserAgent: false,       // Only if needed
    trackReferrer: false,        // Only if needed
    
    // Sampling for high-traffic sites
    sampleRate: 0.1             // Track 10% of sessions
  }
});

Memory Leaks

Problem: Browser memory usage increases over time.

Event Listener Cleanup

// ❌ Event listeners not cleaned up
class MyComponent {
  componentDidMount() {
    window.addEventListener('scroll', this.trackScroll);
    window.addEventListener('click', this.trackClick);
  }
  
  // Missing: componentWillUnmount cleanup
}

// ✅ Proper cleanup
class MyComponent {
  componentDidMount() {
    this.trackScroll = this.trackScroll.bind(this);
    this.trackClick = this.trackClick.bind(this);
    
    window.addEventListener('scroll', this.trackScroll);
    window.addEventListener('click', this.trackClick);
  }
  
  componentWillUnmount() {
    window.removeEventListener('scroll', this.trackScroll);
    window.removeEventListener('click', this.trackClick);
  }
}

Queue Management

// Monitor queue size to prevent memory buildup
setInterval(() => {
  const status = Journium.getStatus();
  
  if (status.queueSize > 1000) {
    console.warn('Event queue is getting large:', status.queueSize);
    
    // Force flush
    Journium.flush();
    
    // Or reduce tracking temporarily
    Journium.updateConfig({ 
      trackScrolling: false,
      trackClicks: false 
    });
  }
}, 30000); // Check every 30 seconds

React Integration Issues

Hook Dependencies

Problem: React hooks causing unnecessary re-renders or stale closures.

useEffect Dependencies

// ❌ Missing dependencies
function ProductCard({ product, userId }) {
  useEffect(() => {
    Journium.track('product_viewed', {
      product_id: product.id,
      user_id: userId
    });
  }, []); // Missing dependencies!
}

// ✅ Correct dependencies
function ProductCard({ product, userId }) {
  useEffect(() => {
    Journium.track('product_viewed', {
      product_id: product.id,
      user_id: userId
    });
  }, [product.id, userId]); // All dependencies included
}

// ✅ Alternative: Memoize the tracking function
function ProductCard({ product, userId }) {
  const trackProductView = useCallback(() => {
    Journium.track('product_viewed', {
      product_id: product.id,
      user_id: userId
    });
  }, [product.id, userId]);
  
  useEffect(() => {
    trackProductView();
  }, [trackProductView]);
}

Context Provider Issues

// ❌ Provider re-creating context value
function AnalyticsProvider({ children }) {
  const [user, setUser] = useState(null);
  
  // This object is re-created on every render!
  const contextValue = {
    user,
    trackEvent: (event, props) => Journium.track(event, props)
  };
  
  return (
    <AnalyticsContext.Provider value={contextValue}>
      {children}
    </AnalyticsContext.Provider>
  );
}

// ✅ Memoize context value
function AnalyticsProvider({ children }) {
  const [user, setUser] = useState(null);
  
  const trackEvent = useCallback((event, props) => {
    Journium.track(event, props);
  }, []);
  
  const contextValue = useMemo(() => ({
    user,
    trackEvent
  }), [user, trackEvent]);
  
  return (
    <AnalyticsContext.Provider value={contextValue}>
      {children}
    </AnalyticsContext.Provider>
  );
}

Network & Connectivity Issues

Request Failures

Problem: Analytics requests are failing.

CORS Issues

Symptoms:

Console error: CORS policy: No 'Access-Control-Allow-Origin' header
Network requests show as failed in DevTools

Solutions:

// This shouldn't happen with Journium's CDN, but if using a proxy:

// Server-side proxy configuration (Express.js example)
app.use('/journium-proxy', (req, res) => {
  res.header('Access-Control-Allow-Origin', '*');
  res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE');
  res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization');
  
  // Proxy request to Journium
  // ... proxy logic
});

// Client-side: Use the proxy
Journium.init({
  // ... config
  config: {
    apiEndpoint: '/journium-proxy'
  }
});

Ad Blockers

Problem: Ad blockers preventing analytics requests.Detection:

// Detect if Journium requests are being blocked
const detectAdBlocker = () => {
  return new Promise((resolve) => {
    const testImg = new Image();
    testImg.onload = () => resolve(false);
    testImg.onerror = () => resolve(true);
    testImg.src = 'https://cdn.journium.com/test-pixel.gif?t=' + Date.now();
  });
};

detectAdBlocker().then(blocked => {
  if (blocked) {
    console.warn('Analytics may be blocked by ad blocker');
    // Implement fallback tracking or show user message
  }
});

Workarounds:

// Use first-party subdomain proxy
Journium.init({
  // ... config
  config: {
    apiEndpoint: 'https://analytics.yoursite.com/api'
  }
});

// Or implement server-side tracking as backup
const trackServerSide = (event, properties) => {
  fetch('/api/analytics', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ event, properties })
  });
};

Offline Handling

Problem: Events are lost when users go offline.

Offline Queue

// Enable offline queueing
Journium.init({
  // ... config
  config: {
    offlineQueue: true,
    maxOfflineEvents: 1000,
    offlineRetryInterval: 30000 // 30 seconds
  }
});

// Monitor connection status
window.addEventListener('online', () => {
  console.log('Back online, flushing queued events');
  Journium.flush();
});

window.addEventListener('offline', () => {
  console.log('Gone offline, queueing events locally');
});

Browser Compatibility Issues

Older Browser Support

Problem: SDK doesn’t work in older browsers (IE11, older Safari).

Polyfills

<!-- Add polyfills before Journium script -->
<script src="https://polyfill.io/v3/polyfill.min.js?features=fetch,Promise,Object.assign"></script>
<script src="https://cdn.journium.com/sdk/v1/journium.min.js"></script>

<!-- Or include specific polyfills -->
<script>
  // Fetch polyfill for IE11
  if (!window.fetch) {
    document.write('<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/fetch.umd.js"><\/script>');
  }
  
  // Promise polyfill for IE11
  if (!window.Promise) {
    document.write('<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/es6-promise.auto.min.js"><\/script>');
  }
</script>

Browser Detection

// Graceful degradation for unsupported browsers
const isSupported = () => {
  return !!(
    window.fetch &&
    window.Promise &&
    window.Object.assign &&
    window.JSON
  );
};

if (isSupported()) {
  Journium.init(config);
} else {
  console.warn('Browser not supported, analytics disabled');
  // Implement server-side fallback or basic img pixel tracking
  
  window.Journium = {
    track: (event, props) => {
      // Fallback tracking via image pixel
      const img = new Image();
      img.src = `/analytics-fallback?event=${encodeURIComponent(event)}&props=${encodeURIComponent(JSON.stringify(props))}`;
    }
  };
}

Debugging Tools

Debug Mode

Enable detailed logging to diagnose issues:

Journium.init({
  // ... config
  config: {
    debugMode: true,
    logLevel: 'verbose' // 'error', 'warn', 'info', 'debug', 'verbose'
  }
});

// Check SDK status
console.log('Journium status:', Journium.getStatus());
console.log('Journium config:', Journium.getConfig());

// Monitor events
Journium.on('event_tracked', (event) => {
  console.log('Event tracked:', event);
});

Journium.on('event_failed', (event, error) => {
  console.error('Event failed:', event, error);
});

Health Check Function

function journiumHealthCheck() {
  const status = Journium.getStatus();
  const config = Journium.getConfig();
  
  const health = {
    initialized: status.initialized,
    connected: status.connected,
    queueSize: status.queueSize,
    errorCount: status.errors,
    lastFlush: new Date(status.lastFlush),
    
    // Configuration checks
    validApiKey: config.apiKey?.startsWith('pk_'),
    validProjectId: config.projectId?.startsWith('proj_'),
    environmentSet: !!config.environment,
    
    // Performance checks
    memoryUsage: performance.memory?.usedJSHeapSize || 'unavailable',
    queueSizeHealthy: status.queueSize < 100,
    errorRateHealthy: status.errors / status.totalEvents < 0.01
  };
  
  console.table(health);
  
  // Warnings
  if (!health.validApiKey) console.warn('Invalid API key format');
  if (!health.connected) console.warn('Not connected to Journium servers');
  if (!health.queueSizeHealthy) console.warn('Event queue is getting large');
  
  return health;
}

// Run health check
journiumHealthCheck();

Browser DevTools Integration

// Add Journium to window for debugging
if (Journium.getConfig().debugMode) {
  window.JourniumDebug = {
    status: () => Journium.getStatus(),
    config: () => Journium.getConfig(),
    healthCheck: journiumHealthCheck,
    clearQueue: () => Journium.clearQueue(),
    flushNow: () => Journium.flush(),
    testEvent: () => Journium.track('debug_test_event', { timestamp: Date.now() })
  };
  
  console.log('Journium debug tools available at window.JourniumDebug');
}

Getting Help

If you’re still experiencing issues after trying these solutions:

Contact Support

Email our support team with your specific issue

Community Forum

Ask questions and get help from other developers

GitHub Issues

Report bugs or request features on GitHub

Status Page

Check if there are any ongoing service issues

Support Information to Include

When contacting support, please include:

SDK Version: Check Journium.getConfig().version
Browser & OS: Include version numbers
Error Messages: Copy exact error text from console
Configuration: Your init config (remove sensitive keys)
Steps to Reproduce: Detailed steps to recreate the issue
Expected vs Actual Behavior: What you expected vs what happened

// Generate debug info for support
function generateSupportInfo() {
  const info = {
    sdk_version: Journium.getConfig().version,
    browser: navigator.userAgent,
    url: window.location.href,
    timestamp: new Date().toISOString(),
    status: Journium.getStatus(),
    config: {
      ...Journium.getConfig(),
      apiKey: '[REDACTED]' // Don't include sensitive info
    }
  };
  
  console.log('Support Info:', JSON.stringify(info, null, 2));
  return info;
}

Getting Started

Installation

Configuration

Features

Troubleshooting

Installation Issues

SDK Not Loading

NPM Installation Issues

Authentication & Configuration Issues

Invalid API Key

Project Not Found

Event Tracking Issues

Events Not Appearing in Dashboard

Duplicate Events

Performance Issues

Slow Page Loading

Memory Leaks

React Integration Issues

Hook Dependencies

Network & Connectivity Issues

Request Failures

Offline Handling

Browser Compatibility Issues

Older Browser Support

Debugging Tools

Debug Mode

Health Check Function

Browser DevTools Integration

Getting Help

Contact Support

Community Forum

GitHub Issues

Status Page

Support Information to Include

Next Steps

FAQ

Best Practices

Getting Started

Installation

Configuration

Features

Troubleshooting

​Installation Issues

​SDK Not Loading

​NPM Installation Issues

​Authentication & Configuration Issues

​Invalid API Key

​Project Not Found

​Event Tracking Issues

​Events Not Appearing in Dashboard

​Duplicate Events

​Performance Issues

​Slow Page Loading

​Memory Leaks

​React Integration Issues

​Hook Dependencies

​Network & Connectivity Issues

​Request Failures

​Offline Handling

​Browser Compatibility Issues

​Older Browser Support

​Debugging Tools

​Debug Mode

​Health Check Function

​Browser DevTools Integration

​Getting Help

Contact Support

Community Forum

GitHub Issues

Status Page

​Support Information to Include

​Next Steps

FAQ

Best Practices

Installation Issues

SDK Not Loading

NPM Installation Issues

Authentication & Configuration Issues

Invalid API Key

Project Not Found

Event Tracking Issues

Events Not Appearing in Dashboard

Duplicate Events

Performance Issues

Slow Page Loading

Memory Leaks

React Integration Issues

Hook Dependencies

Network & Connectivity Issues

Request Failures

Offline Handling

Browser Compatibility Issues

Older Browser Support

Debugging Tools

Debug Mode

Health Check Function

Browser DevTools Integration

Getting Help

Support Information to Include

Next Steps