Troubleshooting Guide

Common issues and solutions for Plaros embed integration.

Common Issues

Embed Not Loading

Blank iframe or "Page not found" error

Symptoms:

• Iframe appears but shows blank white page

• "404 Not Found" error message

• Loading spinner that never completes

Causes & Solutions:

1. Incorrect tenant slug

   // ❌ Wrong
   const url = 'https://play.plaros.com/v1/embed/wrong-tenant/playbooks';
   
   // ✅ Correct - check your dashboard account settings
   const url = 'https://play.plaros.com/v1/embed/your-actual-tenant/playbooks';

2. Invalid zone path

   // Verify zone exists in your dashboard
   url.searchParams.set('zonePath', 'existing-zone-path');

3. Missing required parameters

   // ❌ Missing zonePath
   const url = new URL('https://play.plaros.com/v1/embed/tenant/playbooks');
   
   // ✅ Include required zonePath
   url.searchParams.set('zonePath', 'your-zone');

CORS or Mixed Content Errors

Symptoms:

• Browser console shows CORS errors

• "Mixed content" warnings in HTTPS sites

Solutions:

1. Ensure HTTPS usage

   // ❌ HTTP on HTTPS sites will fail
   const url = 'http://play.plaros.com/v1/embed/...';
   
   // ✅ Always use HTTPS
   const url = 'https://play.plaros.com/v1/embed/...';

2. Content Security Policy (CSP) configuration

   <!-- Add to your page head -->
   <meta http-equiv="Content-Security-Policy" 
         content="frame-src https://play.plaros.com; script-src 'unsafe-inline';">

Sizing and Display Issues

Embed doesn't fit on mobile

Symptoms:

• Embed appears too wide on mobile devices

• Horizontal scrolling required

• Content cut off on small screens

Solutions:

1. Use responsive CSS

   .playbook-embed-container {
     position: relative;
     width: 100%;
     max-width: 600px;
     margin: 0 auto;
   }
   
   @media (max-width: 600px) {
     .playbook-embed-container {
       max-width: 100% !important;
       padding: 0 16px;
     }
     
     .playbook-embed-wrapper {
       padding-bottom: 177.78% !important; /* 16:9 for mobile */
     }
   }

2. Set proper viewport meta tag

   <meta name="viewport" content="width=device-width, initial-scale=1.0">

Incorrect aspect ratio

Symptoms:

• Embed appears squished or stretched

• Content doesn't fit properly within iframe

Solutions:

1. Calculate proper padding-bottom

   /* For 4:3 aspect ratio */
   .playbook-embed-wrapper {
     padding-bottom: 75%; /* (3/4) * 100 */
   }
   
   /* For 16:9 aspect ratio */
   .playbook-embed-wrapper {
     padding-bottom: 56.25%; /* (9/16) * 100 */
   }
   
   /* For 3:4 aspect ratio (mobile-friendly) */
   .playbook-embed-wrapper {
     padding-bottom: 133.33%; /* (4/3) * 100 */
   }

Analytics and Tracking Issues

User interactions not being tracked

Symptoms:

• Analytics dashboard shows no data

• User engagement metrics missing

Solutions:

1. Verify analytics parameter

   // ❌ Analytics disabled
   url.searchParams.set('analytics', 'false');
   
   // ✅ Analytics enabled (default)
   url.searchParams.set('analytics', 'true');

2. Ensure user ID is provided

   // For authenticated users
   if (currentUser && currentUser.id) {
     url.searchParams.set('userId', currentUser.id);
   }
   // Anonymous users will be auto-tracked

3. Check browser privacy settings

   • Some ad blockers may interfere with analytics

   • Private browsing modes may block tracking

   • Test in different browsers

Custom Theming Issues

Custom colors not applied

Symptoms:

• Embed uses default colors instead of custom ones

• Theme mode override not working

Solutions:

1. Remove # from hex colors

   // ❌ Include # symbol
   url.searchParams.set('primaryColor', '#FF6B35');
   
   // ✅ Remove # symbol
   url.searchParams.set('primaryColor', 'FF6B35');

2. Verify valid hex color format

   // Valid formats
   const validColors = ['FF6B35', '004E89', 'F00', '0A8'];
   
   // ❌ Invalid formats
   const invalidColors = ['#FF6B35', 'red', 'rgb(255,0,0)', 'GGHHII'];

3. Check theme mode values

   // ✅ Valid values (lowercase)
   url.searchParams.set('themeMode', 'light');
   url.searchParams.set('themeMode', 'dark');
   
   // ❌ Invalid values
   url.searchParams.set('themeMode', 'Light'); // Case sensitive
   url.searchParams.set('themeMode', 'auto');  // Not supported

Performance Issues

Slow loading times

Symptoms:

• Embed takes long time to appear

• Poor user experience on slower connections

Solutions:

1. Implement lazy loading

   <iframe 
     src="about:blank"
     data-src="https://play.plaros.com/v1/embed/..."
     loading="lazy"
     class="plaros-embed-lazy">
   </iframe>
   
   <script>
   // Load when in viewport
   const observer = new IntersectionObserver((entries) => {
     entries.forEach(entry => {
       if (entry.isIntersecting) {
         const iframe = entry.target;
         iframe.src = iframe.dataset.src;
         observer.unobserve(iframe);
       }
     });
   });
   
   document.querySelectorAll('.plaros-embed-lazy').forEach(iframe => {
     observer.observe(iframe);
   });
   </script>

2. Optimize embed placement

   // Load critical embeds first
   const criticalEmbeds = document.querySelectorAll('.embed-above-fold');
   const nonCriticalEmbeds = document.querySelectorAll('.embed-below-fold');
   
   // Load critical embeds immediately
   criticalEmbeds.forEach(loadEmbed);
   
   // Lazy load non-critical embeds
   setTimeout(() => {
     nonCriticalEmbeds.forEach(loadEmbed);
   }, 1000);

Debug Mode

Enable debug mode to troubleshoot issues during development:

const debugUrl = new URL('https://play.plaros.com/v1/embed/your-tenant/playbooks');
debugUrl.searchParams.set('zonePath', 'your-zone');
debugUrl.searchParams.set('debug', 'true');

// Check browser console for detailed logs
console.log('Debug URL:', debugUrl.toString());

Debug mode provides:

• Detailed console logging

• Parameter validation messages

• Load time information

• Error stack traces

Remember: Always disable debug mode in production!

Browser Compatibility

Supported Browsers

Browser	Minimum Version	Notes
Chrome	60+	Full support
Firefox	55+	Full support
Safari	12+	Full support
Edge	79+	Full support
iOS Safari	12+	Mobile optimized
Chrome Mobile	60+	Mobile optimized

Legacy Browser Issues

Internet Explorer Support

Plaros embeds do not support Internet Explorer. For legacy environments:

// Detect IE and show fallback
if (navigator.userAgent.indexOf('MSIE') !== -1 || navigator.appVersion.indexOf('Trident/') > -1) {
  document.getElementById('embed-container').innerHTML = `
    <div class="browser-upgrade-notice">
      <h3>Browser Update Required</h3>
      <p>This interactive content requires a modern browser. Please upgrade to:</p>
      <ul>
        <li>Chrome 60+</li>
        <li>Firefox 55+</li>
        <li>Safari 12+</li>
        <li>Edge 79+</li>
      </ul>
    </div>
  `;
}

Error Handling

Implementing Error Boundaries

React Error Boundary

class EmbedErrorBoundary extends React.Component {
  constructor(props) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  componentDidCatch(error, errorInfo) {
    console.error('Embed Error:', error, errorInfo);
    
    // Report to analytics
    if (window.analytics) {
      window.analytics.track('Embed Error', {
        error: error.message,
        tenantSlug: this.props.tenantSlug,
        zonePath: this.props.zonePath
      });
    }
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="embed-error-fallback">
          <h3>Unable to load interactive content</h3>
          <p>Please try refreshing the page or contact support if the issue persists.</p>
          <button onClick={() => window.location.reload()}>
            Refresh Page
          </button>
        </div>
      );
    }

    return this.props.children;
  }
}

// Usage
<EmbedErrorBoundary tenantSlug="your-tenant" zonePath="your-zone">
  <PlarosEmbed {...embedProps} />
</EmbedErrorBoundary>

JavaScript Error Handling

function loadEmbedWithFallback(container, config) {
  try {
    const iframe = document.createElement('iframe');
    iframe.src = buildEmbedUrl(config);
    iframe.style.cssText = 'width: 100%; height: 100%; border: 0;';
    iframe.allow = 'fullscreen';
    iframe.title = 'Interactive Playbook';
    
    // Handle load errors
    iframe.onerror = () => {
      showErrorFallback(container, 'Failed to load embed');
    };
    
    // Timeout fallback
    const loadTimeout = setTimeout(() => {
      showErrorFallback(container, 'Embed load timeout');
    }, 10000);
    
    iframe.onload = () => {
      clearTimeout(loadTimeout);
    };
    
    container.appendChild(iframe);
    
  } catch (error) {
    console.error('Embed creation failed:', error);
    showErrorFallback(container, error.message);
  }
}

function showErrorFallback(container, message) {
  container.innerHTML = `
    <div class="embed-error" style="
      padding: 40px 20px;
      text-align: center;
      background: #fee;
      border: 1px solid #fcc;
      border-radius: 8px;
      color: #c33;
    ">
      <h3>Content Unavailable</h3>
      <p>${message}</p>
      <button onclick="location.reload()" style="
        background: #c33;
        color: white;
        border: none;
        padding: 8px 16px;
        border-radius: 4px;
        cursor: pointer;
      ">Try Again</button>
    </div>
  `;
}

Testing Checklist

Use this checklist to verify your embed implementation:

Basic Functionality

• Embed loads without errors

• Content is visible and interactive

• iframe has proper title attribute

• No console errors in browser

Responsive Design

• Works on desktop (1920x1080)

• Works on tablet (768x1024)

• Works on mobile (375x667)

• No horizontal scrolling

• Proper aspect ratio maintained

URL Parameters

• Required zonePath parameter present

• Optional parameters work as expected

• Custom colors apply correctly

• Analytics tracking functions

• Debug mode works (development only)

Performance

• Loads within 3 seconds on fast connection

• Graceful degradation on slow connections

• Lazy loading implemented (if applicable)

• No memory leaks on page navigation

Browser Testing

• Chrome (latest)

• Firefox (latest)

• Safari (latest)

• Edge (latest)

• Mobile browsers

Error Handling

• Graceful fallback for load failures

• Error boundaries implemented

• User-friendly error messages

• Retry functionality available

Getting Help

If you're still experiencing issues after following this guide:

Debug Information to Collect

When reporting issues, please include:

1. Browser information

   console.log('User Agent:', navigator.userAgent);
   console.log('Viewport:', window.innerWidth + 'x' + window.innerHeight);

2. Embed configuration

   console.log('Embed URL:', embedUrl);
   console.log('Container dimensions:', container.getBoundingClientRect());

3. Console errors

   • Screenshots of browser console

   • Network tab errors

   • Any JavaScript exceptions

4. Steps to reproduce

   • Exact steps that lead to the issue

   • Expected vs actual behavior

   • Frequency of the issue

Contact Support

• Discord: Join our developer community for real-time help

• Email: [email protected] with debug information

• Dashboard: Check status.plaros.com for service status

Useful Resources

• Browser Developer Tools Guide

• MDN iframe Documentation

• CSS Responsive Design Guide