Skip to main content

Common Errors & Troubleshooting

This guide covers the most frequently encountered issues when implementing biskoui and their solutions. Each section includes symptoms, root causes, and step-by-step fixes.

Symptoms​

  • Console shows no errors but banner doesn't appear
  • Banner appears intermittently
  • Banner shows briefly then disappears

Root Causes & Solutions​

1. Script Loading Issues​

Check script placement:

<!-- ❌ Wrong: In <head> without async -->
<head>
  <script src="https://cdn.biskoui.com/biskoui.js"></script>
</head>

<!-- ✅ Correct: Before closing </body> or async in <head> -->
<head>
  <script async src="https://cdn.biskoui.com/biskoui.js"></script>
</head>
<!-- OR -->
<body>
  <!-- Your content -->
  <script src="https://cdn.biskoui.com/biskoui.js"></script>
</body>

Verify script loading:

// Debug script loading
window.addEventListener('load', () => {
  if (typeof biskoui === 'undefined') {
    console.error('biskoui script failed to load');
    // Check network tab for 404 errors
  } else {
    console.log('biskoui loaded successfully');
  }
});

2. Content Security Policy (CSP) Blocking​

Common CSP errors:

Refused to load the script 'https://cdn.biskoui.com/biskoui.js' 
because it violates the following Content Security Policy directive

Solution - Update CSP headers:

<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self' https://cdn.biskoui.com; 
               connect-src 'self' https://api.biskoui.com;
               frame-src 'self' https://widget.biskoui.com;">

For strict CSP with nonces:

<script nonce="your-nonce" src="https://cdn.biskoui.com/biskoui.js"></script>

3. Domain Configuration Issues​

Verify domain setup:

// Check if current domain is configured
biskoui.debug.getDomainConfig().then(config => {
  if (!config) {
    console.error('Domain not configured in biskoui dashboard');
  } else {
    console.log('Domain config:', config);
  }
});

Common domain mismatches:

// ❌ Wrong: Subdomain not configured
// Banner configured for: example.com
// Current domain: app.example.com

// ✅ Solution: Add all subdomains in dashboard
// Or use wildcard: *.example.com

Symptoms​

  • Consent choices reset on page reload
  • Banner reappears after user dismissed it
  • Consent state differs across pages/sessions

Root Causes & Solutions​

Check cookie configuration:

// Debug cookie storage
biskoui.debug.getStorageInfo().then(info => {
  console.log('Storage method:', info.method);
  console.log('Cookie domain:', info.domain);
  console.log('Cookie path:', info.path);
  console.log('Secure flag:', info.secure);
});

Common cookie problems:

// ❌ Wrong: Restrictive cookie settings
// Domain: subdomain.example.com (too specific)
// Path: /app/ (too restrictive)
// Secure: true on HTTP site

// ✅ Solution: Configure proper cookie scope
biskoui.configure({
  cookie: {
    domain: '.example.com',  // Works for all subdomains
    path: '/',               // Works for entire site
    secure: location.protocol === 'https:', // Auto-detect
    sameSite: 'Lax'         // Cross-site compatibility
  }
});

2. LocalStorage Conflicts​

Check for storage conflicts:

// Debug localStorage usage
Object.keys(localStorage).forEach(key => {
  if (key.includes('biskoui') || key.includes('consent')) {
    console.log(`${key}: ${localStorage.getItem(key)}`);
  }
});

// Clear conflicting storage
localStorage.removeItem('old-consent-solution');
localStorage.removeItem('conflicting-key');

3. Cross-Domain Issues​

Debug cross-domain consent:

// Test cross-domain sync
biskoui.consent.onSync((data) => {
  console.log('Consent synced from:', data.origin);
  console.log('Consent data:', data.consent);
});

// Force sync if needed
biskoui.consent.sync();

Race Conditions & Timing Issues​

Symptoms​

  • Tags fire before consent is checked
  • Banner appears after tags have loaded
  • Inconsistent consent enforcement

Root Causes & Solutions​

1. Tag Manager Race Conditions​

Google Tag Manager timing:

<!-- ❌ Wrong: GTM loads before biskoui -->
<script async src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXX"></script>
<script async src="https://cdn.biskoui.com/biskoui.js"></script>

<!-- ✅ Correct: biskoui loads first -->
<script src="https://cdn.biskoui.com/biskoui.js"></script>
<script>
  biskoui.ready(() => {
    // Now safe to load GTM
    (function(w,d,s,l,i){
      w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime()});
      var f=d.getElementsByTagName(s)[0],j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';
      j.async=true;j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
      f.parentNode.insertBefore(j,f);
    })(window,document,'script','dataLayer','GTM-XXXXXX');
  });
</script>

2. SPA Route Change Issues​

React/Vue/Angular timing:

// ❌ Wrong: Not checking consent on route changes
useEffect(() => {
  // Component mounts but consent not verified
  loadAnalytics();
}, []);

// ✅ Correct: Wait for consent state
useEffect(() => {
  biskoui.consent.ready().then(consent => {
    if (consent.analytics) {
      loadAnalytics();
    }
  });
}, []);

// For route changes
useEffect(() => {
  const handleRouteChange = () => {
    biskoui.consent.checkConsent().then(consent => {
      if (consent.analytics) {
        trackPageView();
      }
    });
  };
  
  router.events.on('routeChangeComplete', handleRouteChange);
  return () => router.events.off('routeChangeComplete', handleRouteChange);
}, []);

3. Async Script Loading​

Ensure proper initialization order:

// ❌ Wrong: Assuming biskoui is ready
window.dataLayer = window.dataLayer || [];
gtag('consent', 'default', {
  'analytics_storage': 'denied'
});

// ✅ Correct: Wait for biskoui
biskoui.ready(() => {
  window.dataLayer = window.dataLayer || [];
  
  biskoui.consent.getConsent().then(consent => {
    gtag('consent', 'update', {
      'analytics_storage': consent.analytics ? 'granted' : 'denied',
      'ad_storage': consent.marketing ? 'granted' : 'denied'
    });
  });
});

Mixed HTTP/HTTPS Problems​

Symptoms​

  • Banner loads on HTTP but not HTTPS (or vice versa)
  • Console errors about mixed content
  • Consent sync failures between protocols

Root Causes & Solutions​

1. Protocol Mismatch​

Ensure protocol consistency:

<!-- ❌ Wrong: Hardcoded protocol -->
<script src="http://cdn.biskoui.com/biskoui.js"></script>

<!-- ✅ Correct: Protocol-relative or HTTPS -->
<script src="https://cdn.biskoui.com/biskoui.js"></script>
<!-- OR -->
<script src="//cdn.biskoui.com/biskoui.js"></script>

Fix secure cookie problems:

// Debug protocol and cookie settings
biskoui.configure({
  cookie: {
    secure: location.protocol === 'https:',
    sameSite: location.protocol === 'https:' ? 'None' : 'Lax'
  }
});

Symptoms​

  • Analytics/marketing tags fire immediately on page load
  • No consent check before data collection
  • GDPR/nFADP compliance violations

Root Causes & Solutions​

1. Improper Script Blocking​

Block scripts until consent:

<!-- ❌ Wrong: Script loads immediately -->
<script async src="https://www.google-analytics.com/analytics.js"></script>

<!-- ✅ Correct: Use type="text/plain" -->
<script type="text/plain" data-category="analytics">
  // Google Analytics code here
</script>

<!-- biskoui will change type to "text/javascript" when consent given -->

2. Conditional Loading Pattern​

Load scripts conditionally:

biskoui.consent.ready().then(consent => {
  if (consent.analytics) {
    // Dynamically load analytics
    const script = document.createElement('script');
    script.src = 'https://www.google-analytics.com/analytics.js';
    document.head.appendChild(script);
  }
  
  if (consent.marketing) {
    // Load marketing scripts
    loadFacebookPixel();
    loadGoogleAds();
  }
});

Debug Mode & Logging​

Enable Debug Mode​

// Enable debug logging
biskoui.configure({
  debug: true,
  logLevel: 'verbose'
});

// Check current state
biskoui.debug.getState().then(state => {
  console.log('biskoui state:', state);
});

// Monitor consent changes
biskoui.consent.onChange((consent, previous) => {
  console.log('Consent changed from:', previous);
  console.log('Consent changed to:', consent);
});

Network Debugging​

// Test API connectivity
fetch('https://api.biskoui.com/v1/health')
  .then(response => response.json())
  .then(data => console.log('API health:', data))
  .catch(error => console.error('API connection failed:', error));

// Test CDN connectivity
fetch('https://cdn.biskoui.com/biskoui.js')
  .then(response => {
    if (response.ok) {
      console.log('CDN accessible');
    } else {
      console.error('CDN response error:', response.status);
    }
  })
  .catch(error => console.error('CDN connection failed:', error));

Performance Issues​

Optimize loading performance:

<!-- Preload biskoui resources -->
<link rel="preload" href="https://cdn.biskoui.com/biskoui.js" as="script">
<link rel="preconnect" href="https://api.biskoui.com">

<!-- Load with high priority -->
<script src="https://cdn.biskoui.com/biskoui.js" 
        fetchpriority="high"></script>

Memory Leaks​

Prevent memory leaks in SPAs:

// Properly cleanup in React
useEffect(() => {
  const unsubscribe = biskoui.consent.onChange(handleConsentChange);
  
  return () => {
    unsubscribe(); // Cleanup subscription
  };
}, []);

Browser-Specific Issues​

Safari Private Mode​

// Check for storage availability
try {
  localStorage.setItem('test', 'test');
  localStorage.removeItem('test');
} catch (e) {
  // Fallback to cookie-only storage
  biskoui.configure({
    storage: {
      method: 'cookie'
    }
  });
}

Internet Explorer (Legacy Support)​

// Polyfills for IE11
if (!window.Promise) {
  // Load Promise polyfill
  document.write('<script src="https://cdn.polyfill.io/v3/polyfill.min.js?features=Promise"><\/script>');
}

// IE-safe configuration
biskoui.configure({
  compatibility: {
    ie11: true
  }
});

Quick Diagnosis Checklist​

When biskoui isn't working, check these items in order:

  1. ✅ Script Loading

    • biskoui script loads without 404 errors
    • No CSP blocking errors in console
    • Script loads before other analytics scripts

  2. ✅ Domain Configuration

    • Current domain matches dashboard configuration
    • Subdomain/wildcard settings correct
    • HTTPS/HTTP protocol matches

  3. ✅ Console Errors

    • No JavaScript errors in console
    • No network request failures
    • No mixed content warnings

  4. ✅ Storage & Cookies

    • Cookies can be set/read on current domain
    • LocalStorage available (not private mode)
    • No conflicting consent solutions

  5. ✅ Timing & Integration

    • biskoui loads before other scripts
    • Consent checked before data collection
    • Proper cleanup in single-page apps

Use the debug commands above to investigate any failing checklist items.