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:
- âś… 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:
- Check Script Loading
Open browser developer tools (F12) and verify the script is loaded:
// 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- Verify Data Attributes
Ensure your container has the correct attributes:
<!-- 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>- Manual Initialization
If adding containers dynamically:
// 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:
- CSS Conflicts
/* 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;
}- Theme Compatibility
/* 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:
- Lazy Loading Implementation
// 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));- Resource Optimization
<!-- 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:
- Viewport Configuration
<!-- Ensure proper viewport meta tag -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">- Mobile-Specific CSS
/* 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:
- HTTPS Requirement
Ensure your site uses HTTPS:
// 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));
}- Content Security Policy
<!-- 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
<?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
// 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 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
// 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:
- đź“§ Email: support@linkyt.io
- đź’¬ Discord: Join our community
- đź“‹ Include: Browser console errors, network tab screenshots, and your integration code
Prevention Tips
- • 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
```
```