Troubleshooting

Solutions for common issues and frequently asked questions.

Common Errors

Component Not Rendering

Symptom: The <qariyb-checkout> element appears empty.

Solutions:

Script not loaded:

<script src="https://js.qariyb.com/v1/qariyb.min.js"></script>

Missing event-id:

<!-- Wrong -->
<qariyb-checkout></qariyb-checkout>

<!-- Correct -->
<qariyb-checkout event-id="01HWXYZ123ABC456"></qariyb-checkout>

Invalid event ID format:

<!-- Wrong - partial ID -->
<qariyb-checkout event-id="123"></qariyb-checkout>

<!-- Correct - full ULID -->
<qariyb-checkout event-id="01HWXYZ123ABC456DEF789"></qariyb-checkout>

"Event not found" Error

Causes:

Event doesn't exist - verify the ID in your Qariyb dashboard
Event is unpublished - events must be published to be accessible
Event was deleted - check if the event still exists

Debug:

const checkout = document.querySelector('qariyb-checkout');
console.log('Event ID:', checkout.getAttribute('event-id'));

checkout.addEventListener('qariyb:checkout:event-error', (e) => {
  console.error('Error loading event:', e.detail.data);
});

Payment Element Not Showing

Symptom: Checkout reaches payment step but Stripe form doesn't appear.

Solutions:

CSP blocking Stripe:

script-src 'self' https://js.qariyb.com https://js.stripe.com;
frame-src https://js.stripe.com;
connect-src https://api.qariyb.com https://api.stripe.com;

Ad blocker: Test in incognito mode or temporarily disable ad blockers.
API key issues:

console.log('Config:', window.QariybConfig);

Styles Not Applying

Symptom: Theme or custom styles aren't visible.

Solutions:

Config set after script loads:

<!-- Wrong -->
<script src="https://js.qariyb.com/v1/qariyb.js"></script>
<script>window.QariybConfig = { publishableKey: 'pk_live_...', theme: 'dark' };</script>

<!-- Correct -->
<script>window.QariybConfig = { publishableKey: 'pk_live_...', theme: 'dark' };</script>
<script src="https://js.qariyb.com/v1/qariyb.js"></script>

External CSS won't pierce Shadow DOM:

// This won't work
// qariyb-checkout .Button--primary { background: red; }

// Use configuration instead
window.QariybConfig = {
  publishableKey: 'pk_live_...',
  rules: {
    '.Button--primary': { background: 'red' },
  },
};

Modal Not Opening

Symptom: Clicking the button doesn't open the checkout modal.

Solutions:

Missing event-id:

<!-- Wrong -->
<qariyb-button>Get Tickets</qariyb-button>

<!-- Correct -->
<qariyb-button event-id="01HW...">Get Tickets</qariyb-button>

JavaScript errors: Check browser console for errors.
z-index conflict: The modal uses z-index: 10000.

Events Not Firing

Symptom: Event listeners aren't receiving events.

Solutions:

Wrong event name:

// Wrong - missing prefix
element.addEventListener('checkout:success', handler);

// Correct - full event name
element.addEventListener('qariyb:checkout:success', handler);

Listener attached too late:

// Use window for global listening
window.addEventListener('qariyb:checkout:success', handler);

Callback function not on window:

<!-- Wrong -->
<qariyb-checkout on-success="handleSuccess"></qariyb-checkout>
<script>
  const handleSuccess = (data) => {}; // Not on window!
</script>

<!-- Correct -->
<qariyb-checkout on-success="handleSuccess"></qariyb-checkout>
<script>
  function handleSuccess(data) {
    // This is on window
  }
</script>

TypeScript Errors

Symptom: TypeScript complains about unknown JSX elements.

Solution: Add type declarations:

// src/types/qariyb.d.ts
declare namespace JSX {
  interface IntrinsicElements {
    'qariyb-checkout': React.DetailedHTMLProps<
      React.HTMLAttributes<HTMLElement> & {
        'event-id': string;
        theme?: 'light' | 'dark' | 'flat' | 'minimal';
      },
      HTMLElement
    >;
    // Add other components...
  }
}

Next.js / SSR Issues

Symptom: "window is not defined" or hydration errors.

Solution: Use dynamic import with SSR disabled:

'use client';

import { useEffect, useState } from 'react';

export function Checkout({ eventId }: { eventId: string }) {
  const [loaded, setLoaded] = useState(false);

  useEffect(() => {
    import('@qariyb/js').then(() => setLoaded(true));
  }, []);

  if (!loaded) return <div>Loading...</div>;

  return <qariyb-checkout event-id={eventId}></qariyb-checkout>;
}

Or with Next.js dynamic:

import dynamic from 'next/dynamic';

const Checkout = dynamic(
  () => import('./Checkout').then(mod => mod.Checkout),
  { ssr: false }
);

FAQ

What browsers are supported?

Browser	Minimum Version
Chrome	67+
Firefox	63+
Safari	10.1+
Edge	79+
iOS Safari	10.3+
Chrome Android	67+

Internet Explorer is not supported as it lacks Web Components support.

Can I use multiple widgets on the same page?

Yes:

<!-- Multiple checkouts for different events -->
<qariyb-checkout event-id="01HWEVENT1"></qariyb-checkout>
<qariyb-checkout event-id="01HWEVENT2"></qariyb-checkout>

<!-- Multiple buttons for same event -->
<qariyb-button event-id="01HWEVENT1">Header CTA</qariyb-button>
<qariyb-button event-id="01HWEVENT1">Footer CTA</qariyb-button>

How do I get my event ID?

Event IDs are ULIDs like 01HWXYZ123ABC456DEF789GH.

Find it:

Log in to your Qariyb dashboard
Navigate to your event
The event ID is in the URL: qariyb.com/events/[EVENT_ID]/manage
Or find it in Event Settings → Embed Code

Is the widget mobile-responsive?

Yes. All components are built mobile-first and adapt to screen sizes. Minimum recommended container width: 300px.

Do I need an API key?

Yes — always, for every event, public or private. Your publishable key is what the SDK sends as the X-Widget-Key header; with no key configured it sends no auth header at all and every request fails with 401 (code 600, "No API key provided"), so the Element renders an error instead of your event.

window.QariybConfig = {
  publishableKey: 'pk_live_xxxxxxxxxxxx',
};

Set this before the SDK script tag. Publishable keys are safe in the browser — they are origin-restricted and cannot read or change your organization's data. Your sk_live_ secret key must never appear in browser code.

Why can't I style with external CSS?

The widget uses Shadow DOM to encapsulate styles and prevent conflicts. Use the variables and rules configuration instead.

Can I translate the widget?

Yes. Override any text using labels:

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  labels: {
    getTickets: 'احصل على التذاكر',
    selectTickets: 'اختر التذاكر',
    // ... more labels
  },
};

Not yet. The SDK does not mirror its layout for right-to-left languages, and setting dir="rtl" on your page does not change it. You can translate every string through labels, but the layout stays left-to-right. RTL layout support is not implemented.

Is the payment form PCI compliant?

Yes. The payment form is rendered by Stripe. Card data goes directly to Stripe's PCI DSS Level 1 certified servers. Card numbers never touch your server or ours.

Does the widget affect page load speed?

The script is optimized:

~35KB gzipped
Async loading
Lazy initialization
CDN-delivered with caching

For best performance, load the script at the end of <body>:

<body>
  <!-- Your content -->
  <qariyb-checkout event-id="01HW..."></qariyb-checkout>
  <script src="https://js.qariyb.com/v1/qariyb.min.js" async></script>
</body>

What data does the widget collect?

Only what's necessary for checkout:

Event information (from Qariyb API)
Attendee details (entered by user)
Payment information (handled by Stripe, never stored)

No tracking cookies, no analytics, no third-party data sharing.

Can I use the widget on HTTP pages?

No. The widget requires HTTPS for security. During local development, localhost is treated as secure.

Debugging Tips

Enable Debug Mode

window.QariybConfig = {
  publishableKey: 'pk_live_...',
  debug: true, // Logs all API calls and events
};

Check Component Registration

console.log('Checkout registered:', !!customElements.get('qariyb-checkout'));
console.log('Button registered:', !!customElements.get('qariyb-button'));

Monitor Events

// Log all Qariyb events
['checkout', 'tickets', 'button', 'card', 'list'].forEach(comp => {
  ['ready', 'loaded', 'error', 'success'].forEach(action => {
    window.addEventListener(`qariyb:${comp}:${action}`, (e) => {
      console.log(`[${comp}:${action}]`, e.detail);
    });
  });
});

Inspect Shadow DOM

In Chrome DevTools:

Open Elements panel
Click on qariyb-checkout element
Expand #shadow-root (open)
Inspect internal elements

Getting Help

Documentation: You're here!
Email: support@qariyb.com
Dashboard: In-app support chat

When reporting bugs, include:

Steps to reproduce
Expected vs actual behavior
Browser and OS version
Console errors (if any)
Event ID (if applicable)