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:

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';

Invalid zone path

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

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:

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/...';

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:

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 */
  }
}

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:

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:

Verify analytics parameter

// ❌ Analytics disabled
url.searchParams.set('analytics', 'false');

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

Ensure user ID is provided

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

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:

Remove # from hex colors

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

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

Verify valid hex color format

// Valid formats
const validColors = ['FF6B35', '004E89', 'F00', '0A8'];

// ❌ Invalid formats
const invalidColors = ['#FF6B35', 'red', 'rgb(255,0,0)', 'GGHHII'];

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:

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>

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

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

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:

Browser information

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

Embed configuration

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

Console errors
- Screenshots of browser console
- Network tab errors
- Any JavaScript exceptions
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

PreviousConfiguration Options NextCustom Theming

Good night

Common Issues

Embed Not Loading

Blank iframe or "Page not found" error

CORS or Mixed Content Errors

Sizing and Display Issues

Embed doesn't fit on mobile

Incorrect aspect ratio

Analytics and Tracking Issues

User interactions not being tracked

Custom Theming Issues

Custom colors not applied

Performance Issues

Slow loading times

Debug Mode

Browser Compatibility

Supported Browsers

Legacy Browser Issues

Internet Explorer Support

Error Handling

Implementing Error Boundaries

React Error Boundary

JavaScript Error Handling

Testing Checklist

Basic Functionality

Responsive Design

URL Parameters

Performance

Browser Testing

Error Handling

Getting Help

Debug Information to Collect

Contact Support

Useful Resources