Skip to Content
Linkyt is released 🎉
DocumentationTroubleshooting Guide

Troubleshooting Guide

Having issues with your Linkyt integration? This comprehensive guide covers the most common problems and their solutions.

Quick Diagnostics

Before diving into specific issues, run through this quick checklist:

Quick Checklist:
  • âś… Scripts are loaded correctly
  • âś… Container elements have correct data attributes
  • âś… Store/Shop IDs are valid
  • âś… No JavaScript errors in browser console
  • âś… Network requests are successful

Common Issues

1. Widget Not Loading

Symptoms: Empty container, no content appears

Most Common Cause: Script not loaded or incorrect data attributes

Solutions:

  1. Check Script Loading

Open browser developer tools (F12) and verify the script is loaded:

console-check.jsjavascript
// In browser console, check if scripts are loaded
console.log('Booking script:', typeof window.LinkytBooking);
console.log('Storefront script:', typeof window.LinkytStorefront);

  // Should return 'object' if loaded, 'undefined' if not
  1. Verify Data Attributes

Ensure your container has the correct attributes:

correct-attributes.htmlhtml
<!-- Booking Form - Check these attributes -->
<div
data-linkyt-booking          <!-- âś… Correct -->
data-shop-id="your-shop-id"  <!-- âś… Must be valid -->
data-booking-id="booking-id" <!-- âś… Must be valid -->
></div>

  <!-- Storefront - Check these attributes -->
  <div
    data-linkyt-storefront       <!-- âś… Correct -->
    data-store-id="your-store-id" <!-- âś… Must be valid -->
  ></div>
  1. Manual Initialization

If adding containers dynamically:

manual-init.jsjavascript
// After adding containers to DOM
if (window.LinkytBooking && window.LinkytBooking.init) {
window.LinkytBooking.init();
}

  if (window.LinkytStorefront && window.LinkytStorefront.init) {
    window.LinkytStorefront.init();
  }

2. Styling Issues

Symptoms: Widget appears but looks broken or doesn’t match your site

Solutions:

  1. CSS Conflicts
fix-conflicts.csscss
/* Override conflicting styles */
.linkyt-container * {
box-sizing: border-box !important;
}

  /* Reset common conflicting properties */
  .linkyt-widget {
    font-family: inherit !important;
    line-height: 1.5 !important;
    color: inherit !important;
  }

  /* Fix layout issues */
  .linkyt-storefront {
    width: 100% !important;
    max-width: none !important;
    margin: 0 !important;
    padding: 0 !important;
  }
  1. Theme Compatibility
theme-fixes.csscss
/* Common theme fixes */
.linkyt-widget img {
max-width: 100% !important;
height: auto !important;
}

  .linkyt-widget button {
    border: none !important;
    outline: none !important;
    background: var(--linkyt-primary-color) !important;
  }

  /* Fix for themes that override all links */
  .linkyt-widget a {
    text-decoration: none !important;
    color: inherit !important;
  }

3. Performance Issues

Symptoms: Slow loading, page freezing, high resource usage

Solutions:

  1. Lazy Loading Implementation
lazy-loading.jsjavascript
// Implement intersection observer for lazy loading
const observerOptions = {
root: null,
rootMargin: '50px',
threshold: 0.1
};

  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        loadLinkytWidget(entry.target);
        observer.unobserve(entry.target);
      }
    });
  }, observerOptions);

  function loadLinkytWidget(container) {
    // Load script only when needed
    const script = document.createElement('script');
    script.src = container.dataset.linkytBooking ?
      'https://booking.linkyt.com/embed.js' :
      'https://cdn.linkyt.io/linkyt-storefront.umd.cjs';
    script.async = true;
    document.body.appendChild(script);
  }

  // Observe all Linkyt containers
  document.querySelectorAll('[data-linkyt-booking], [data-linkyt-storefront]')
    .forEach(container => observer.observe(container));
  1. Resource Optimization
optimized-loading.htmlhtml
<!-- Preload critical resources -->
<link rel="preload" href="https://cdn.linkyt.io/style.css" as="style">
<link rel="preconnect" href="https://api.linkyt.io">

  <!-- Load scripts with proper attributes -->
  <script
    src="https://cdn.linkyt.io/linkyt-storefront.umd.cjs"
    async
    defer
  ></script>

4. Mobile Responsiveness

Symptoms: Widget doesn’t work properly on mobile devices

Solutions:

  1. Viewport Configuration
mobile-viewport.htmlhtml
<!-- Ensure proper viewport meta tag -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
  1. Mobile-Specific CSS
mobile-responsive.csscss
/* Mobile-first responsive design */
.linkyt-container {
width: 100%;
max-width: 100vw;
overflow-x: hidden;
}

  @media (max-width: 768px) {
    .linkyt-storefront {
      min-height: 500px !important;
      padding: 10px !important;
    }

    .linkyt-booking {
      font-size: 14px !important;
    }

    /* Fix touch interactions */
    .linkyt-widget button {
      min-height: 44px !important;
      min-width: 44px !important;
    }
  }

5. Payment Issues

Symptoms: Checkout not working, payment errors

Security Note: Payment issues often relate to HTTPS requirements and security policies.

Solutions:

  1. HTTPS Requirement

Ensure your site uses HTTPS:

https-check.jsjavascript
// Check if site is using HTTPS
if (location.protocol !== 'https:') {
console.warn('Linkyt requires HTTPS for payment processing');
// Redirect to HTTPS version
location.replace('https:' + window.location.href.substring(window.location.protocol.length));
}
  1. Content Security Policy
csp-headers.htmlhtml
<!-- Add to your HTML head or server headers -->
<meta http-equiv="Content-Security-Policy" content="
default-src 'self';
script-src 'self' 'unsafe-inline' https://cdn.linkyt.io https://booking.linkyt.com;
style-src 'self' 'unsafe-inline' https://cdn.linkyt.io;
connect-src 'self' https://api.linkyt.io;
frame-src https://checkout.linkyt.io;
">

Platform-Specific Issues

WordPress

wordpress-fixes.phpphp
<?php
// Fix for WordPress themes that defer all scripts
function linkyt_fix_script_loading() {
  ?>
  <script>
  // Ensure scripts load in correct order
  document.addEventListener('DOMContentLoaded', function() {
      if (typeof window.LinkytBooking === 'undefined') {
          console.warn('Linkyt booking script not loaded');
      }
      if (typeof window.LinkytStorefront === 'undefined') {
          console.warn('Linkyt storefront script not loaded');
      }
  });
  </script>
  <?php
}
add_action('wp_footer', 'linkyt_fix_script_loading');
?>

React/Next.js

react-fixes.tsxtsx
// Fix for React strict mode and hydration issues
import { useEffect, useRef, useState } from 'react';

const LinkytWidget = ({ storeId, type = 'storefront' }) => {
const containerRef = useRef<HTMLDivElement>(null);
const [isLoaded, setIsLoaded] = useState(false);

useEffect(() => {
  // Prevent double initialization in React strict mode
  if (isLoaded) return;

  const loadScript = () => {
    const script = document.createElement('script');
    script.src = type === 'booking'
      ? 'https://booking.linkyt.com/embed.js'
      : 'https://cdn.linkyt.io/linkyt-storefront.umd.cjs';
    script.async = true;
    script.onload = () => setIsLoaded(true);
    document.body.appendChild(script);
  };

  // Check if script already exists
  const existingScript = document.querySelector(`script[src*="linkyt"]`);
  if (!existingScript) {
    loadScript();
  } else {
    setIsLoaded(true);
  }

  return () => {
    // Cleanup if needed
  };
}, [type, isLoaded]);

return (
  <div
    ref={containerRef}
    data-linkyt-storefront={type === 'storefront' ? '' : undefined}
    data-linkyt-booking={type === 'booking' ? '' : undefined}
    data-store-id={storeId}
    style={{ width: '100%', minHeight: '500px' }}
  />
);
};

Debugging Tools

Browser Console Commands

debug-commands.jsjavascript
// Debug Linkyt integration
function debugLinkyt() {
console.log('=== Linkyt Debug Info ===');

// Check if scripts are loaded
console.log('Booking script loaded:', typeof window.LinkytBooking !== 'undefined');
console.log('Storefront script loaded:', typeof window.LinkytStorefront !== 'undefined');

// Find all Linkyt containers
const containers = document.querySelectorAll('[data-linkyt-booking], [data-linkyt-storefront]');
console.log('Found containers:', containers.length);

containers.forEach((container, index) => {
  console.log(`Container ${index + 1}:`, {
    type: container.dataset.linkytBooking !== undefined ? 'booking' : 'storefront',
    storeId: container.dataset.storeId || container.dataset.shopId,
    bookingId: container.dataset.bookingId,
    dimensions: {
      width: container.offsetWidth,
      height: container.offsetHeight
    }
  });
});

// Check for common issues
if (location.protocol !== 'https:') {
  console.warn('⚠️ Site not using HTTPS - may cause payment issues');
}

if (containers.length === 0) {
  console.warn('⚠️ No Linkyt containers found');
}
}

  // Run debug function
  debugLinkyt();

Network Diagnostics

network-check.jsjavascript
// Check API connectivity
async function checkLinkytAPI() {
try {
  const response = await fetch('https://api.linkyt.io/health');
  console.log('API Status:', response.ok ? '✅ Online' : '❌ Offline');
} catch (error) {
  console.error('API Connection Error:', error);
}
}

  checkLinkytAPI();

Getting Help

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

Contact Support:

Prevention Tips

Best Practices:
  • • Always test in multiple browsers and devices
  • • Use browser developer tools to check for errors
  • • Keep your integration code updated
  • • Monitor your site’s performance after integration
  • • Test payment flows in a staging environment first

```

```

Last updated on