Skip to main content

JavaScript API

XBuilder exposes a JavaScript API for programmatic control of popups. Use this API to integrate popups with your site's logic, custom triggers, and analytics.

Runtime Overview​

When XBuilder popups are deployed, they include a runtime script that:

  • Initializes popup configurations
  • Handles triggers and display logic
  • Provides API methods for control
  • Manages cookies and display rules

Accessing the API​

The API is available on the window object:

// Check if XBuilder is loaded
if (window.XBuilder) {
  // API is available
}

Core Methods​

Opening Popups​

XBuilder.open(popupId)​

Opens a specific popup by ID.

XBuilder.open('popup-123456789');

Parameters:

NameTypeDescription
popupIdstringThe popup's unique ID

Returns: void

XBuilder.openAll()​

Opens all popups on the page.

XBuilder.openAll();

Closing Popups​

XBuilder.close(popupId)​

Closes a specific popup.

XBuilder.close('popup-123456789');

Parameters:

NameTypeDescription
popupIdstringThe popup's unique ID

Returns: void

XBuilder.closeAll()​

Closes all open popups.

XBuilder.closeAll();

Toggle​

XBuilder.toggle(popupId)​

Toggles a popup open/closed.

XBuilder.toggle('popup-123456789');

State Methods​

XBuilder.isOpen(popupId)​

Check if a popup is currently open.

const isOpen = XBuilder.isOpen('popup-123456789');
// Returns: true or false

XBuilder.getPopups()​

Get list of all popup IDs on the page.

const popups = XBuilder.getPopups();
// Returns: ['popup-123', 'popup-456', ...]

XBuilder.getConfig(popupId)​

Get the configuration of a popup.

const config = XBuilder.getConfig('popup-123456789');
// Returns: PopupConfig object

Event Handling​

Event Types​

EventDescription
xbuilder:openFired when popup opens
xbuilder:closeFired when popup closes
xbuilder:readyFired when XBuilder initializes

Listening to Events​

// Popup opened
document.addEventListener('xbuilder:open', (e) => {
  console.log('Popup opened:', e.detail.popupId);
});

// Popup closed
document.addEventListener('xbuilder:close', (e) => {
  console.log('Popup closed:', e.detail.popupId);
});

// XBuilder ready
document.addEventListener('xbuilder:ready', () => {
  console.log('XBuilder initialized');
});

Event Detail​

Events include detail about the popup:

document.addEventListener('xbuilder:open', (e) => {
  const { popupId, trigger, timestamp } = e.detail;
  console.log(`Popup ${popupId} opened via ${trigger}`);
});

XBuilder.resetCookie(popupId)​

Reset the display cookie for a popup.

XBuilder.resetCookie('popup-123456789');
// Popup will show again on next trigger

XBuilder.resetAllCookies()​

Reset cookies for all popups.

XBuilder.resetAllCookies();

Custom Triggers​

Click Triggers​

Set up custom click triggers:

document.querySelector('#my-button').addEventListener('click', () => {
  XBuilder.open('popup-123456789');
});

Conditional Opening​

Open based on conditions:

// Open for logged-in users only
if (userIsLoggedIn) {
  XBuilder.open('popup-members-only');
}

// Open based on cart value
if (cartTotal > 100) {
  XBuilder.open('popup-free-shipping');
}

Custom Scroll Trigger​

window.addEventListener('scroll', () => {
  const scrollPercent = (window.scrollY / document.body.scrollHeight) * 100;
  
  if (scrollPercent > 75 && !hasShownPopup) {
    XBuilder.open('popup-end-of-page');
    hasShownPopup = true;
  }
});

Analytics Integration​

Google Analytics​

document.addEventListener('xbuilder:open', (e) => {
  gtag('event', 'popup_view', {
    'popup_id': e.detail.popupId,
    'trigger': e.detail.trigger
  });
});

document.addEventListener('xbuilder:close', (e) => {
  gtag('event', 'popup_close', {
    'popup_id': e.detail.popupId
  });
});

Generic Analytics​

document.addEventListener('xbuilder:open', (e) => {
  analytics.track('Popup Viewed', {
    popupId: e.detail.popupId,
    trigger: e.detail.trigger
  });
});

Form Integration​

Track Form Submissions​

// For popups with forms
document.addEventListener('submit', (e) => {
  if (e.target.closest('.xb-popup-module')) {
    const popupId = e.target.closest('[data-popup-id]')?.dataset.popupId;
    analytics.track('Popup Form Submit', { popupId });
  }
});

Close After Submit​

// Close popup after successful form submission
form.addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const response = await submitForm(form);
  
  if (response.success) {
    XBuilder.close('popup-123456789');
  }
});

A/B Testing​

Show Different Popups​

// Simple A/B test
const variant = Math.random() > 0.5 ? 'A' : 'B';

if (variant === 'A') {
  XBuilder.open('popup-variant-a');
} else {
  XBuilder.open('popup-variant-b');
}

// Track which variant
analytics.track('Popup AB Test', { variant });

Error Handling​

Check for Errors​

try {
  XBuilder.open('popup-123456789');
} catch (error) {
  console.error('Failed to open popup:', error);
}

Verify Popup Exists​

const popups = XBuilder.getPopups();

if (popups.includes('popup-123456789')) {
  XBuilder.open('popup-123456789');
} else {
  console.warn('Popup not found');
}

Initialization​

Wait for XBuilder​

// Method 1: Event listener
document.addEventListener('xbuilder:ready', () => {
  // XBuilder is ready
  XBuilder.open('popup-welcome');
});

// Method 2: Polling
function waitForXBuilder(callback) {
  if (window.XBuilder) {
    callback();
  } else {
    setTimeout(() => waitForXBuilder(callback), 100);
  }
}

waitForXBuilder(() => {
  console.log('XBuilder loaded');
});

Best Practices​

Performance​

// Don't open too many popups at once
// XBuilder handles this, but be careful with custom logic

// Bad
XBuilder.openAll(); // Opens everything

// Good
XBuilder.open('popup-primary'); // Open one at a time

User Experience​

// Respect user dismissal
document.addEventListener('xbuilder:close', (e) => {
  if (e.detail.closedByUser) {
    // User explicitly closed, maybe don't show again soon
    localStorage.setItem('popup-dismissed', Date.now());
  }
});

Debugging​

// Enable debug mode
XBuilder.debug = true;

// This will log internal operations to console

TypeScript Types​

For TypeScript projects:

interface XBuilderAPI {
  open(popupId: string): void;
  close(popupId: string): void;
  closeAll(): void;
  toggle(popupId: string): void;
  isOpen(popupId: string): boolean;
  getPopups(): string[];
  getConfig(popupId: string): PopupConfig;
  resetCookie(popupId: string): void;
  resetAllCookies(): void;
}

declare global {
  interface Window {
    XBuilder: XBuilderAPI;
  }
}