Switchfly Widgets Integration Guide (1.0.0)

• Search Widget: Full-featured travel search (air, hotel, car, activities, bundles)
• Hotel Deals Widget: Showcase featured hotel deals with click-through to booking

Direct Script Embed (Search Widget)

Load the widget bundle and call createSearchWidget():

<div id="search-widget"></div>
<script src="https://your-cdn.com/dist/switchfly-widgets.iife.js"></script>
<script>
  SwitchflyWidgets.createSearchWidget({
    containerId: 'search-widget',
    targetUrl: 'https://your-booking-site.com',
    locale: 'en',
    cobrand: 'partner123',
    searchParam: '|city:7321',
    prefillDestinationLabel: 'San Diego',
    searchDateFormat: 'dd/mm/yy',
    customTab1Label: 'Cruises',
    customTab1Url: 'https://example.com/cruises',
    customTab1Position: 'last',
    branding: {
      tokens: {
        accentColor: '#0a66c2'
      }
    }
  });
</script>

Iframe Embed (Search Widget)

<iframe
  src="https://your-cdn.com/widgets/search/?locale=en&searchParam=%7Ccity:7321&prefillDestinationLabel=San%20Diego&cobrand=partner123&searchDateFormat=dd/mm/yy&customTab1Label=Cruises&customTab1Url=https://example.com/cruises&customTab1Position=last&accentColor=%230a66c2"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

Direct Script Embed (Hotel Deals Widget)

<div id="hotel-deals"></div>
<script src="https://your-cdn.com/dist/switchfly-widgets.iife.js"></script>
<script>
  SwitchflyWidgets.createHotelDealsWidget({
    containerId: 'hotel-deals',
    targetUrl: 'https://your-booking-site.com',
    locale: 'en',
    maxItems: 6,
    showPrices: true,
    title: 'Featured Hotels',
    branding: {
      tokens: {
        accentColor: '#dc2626'
      }
    }
  });
</script>

Iframe Embed (Hotel Deals Widget)

<iframe
  src="https://your-cdn.com/widgets/hotelDeals/?locale=en&maxItems=6&accentColor=%23dc2626"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

postMessage API

Widgets send events to parent windows via postMessage:

window.addEventListener('message', (event) => {
  switch (event.data.type) {
    case 'SWF_WIDGET_HEIGHT':
      // Resize iframe to match widget height
      iframe.style.height = event.data.height + 'px';
      break;
    case 'SWF_WIDGET_NAVIGATE':
      // Widget is navigating to booking platform
      console.log('Navigating to:', event.data.url);
      break;
  }
});

Note: Parent → widget configuration messages are not currently supported. Configure via URL parameters or script config only.

URL Parameter Notes

• Colors must be URL-encoded (#0a66c2 → %230a66c2)
• cobrand parameter becomes nav=<value> in the final booking search URL
• Only include parameters you want to override (all are optional)
• Destination prefill with numeric city IDs:
  • Use searchParam=|city:7321 (URL-encoded: %7Ccity:7321) for the canonical token
  • Also provide prefillDestinationLabel=San%20Diego for display
  • Typeahead API cannot resolve numeric city IDs, so the label is required
  • Airport codes (e.g., |airport:LAS) don't need a label—they resolve via typeahead
• Custom tabs:
  • Supports up to 2 custom tabs with external URLs
  • Custom tab URL is required for tab to render; label defaults to "Link" if omitted
  • Position options: first, last, or after:<product> (e.g., after:air)
  • Custom tabs open in new tab with noopener,noreferrer
  • Custom tabs never become the active product tab
• Search date format:
  • Use searchDateFormat to control how dates are formatted in the Core deep-link URL (date1/date2 params)
  • Options: mm/dd/yy (default), dd/mm/yy, yy/mm/dd, yyyy/mm/dd
  • This ONLY affects the URL format sent to the booking platform
  • Does NOT change datepicker UI, on-screen date display, or locale-based formatting

API Configuration (apiPathPrefix)

The apiPathPrefix config option controls how widgets construct API URLs for location autocomplete and data fetching.

Production deployments (recommended):

• Omit apiPathPrefix or set to empty string ""
• Widgets will use root-relative URLs like /apps/api/locations/
• API calls go to the same origin as the hosting page

Local development:

• Set apiPathPrefix: "/core"
• Enables Vite dev proxy to forward API calls to QA environment
• Example: http://localhost:5173/core/apps/api/locations/ → https://qaone.uat.switchfly.com/apps/api/locations/

When to set apiPathPrefix:

• Never set it in production embed code
• Only set it when testing locally with npm run dev
• The builder UI defaults to "/core" for development convenience

Switchfly widgets support two integration methods:

• Iframe embed (recommended): simplest integration and maximum isolation from host page styles/scripts.
• Direct script embed (IIFE): renders inline on the host page for tighter visual integration.

Both methods are supported out of the gate. Hosting of the widget IIFE and the API proxy approach will be documented once finalized.

The notes below call out CMS-specific considerations. Unless stated otherwise, iframe embed is the recommended approach.

HubSpot

• Recommended: Iframe embed in a Custom HTML module
• Supported: Direct script embed (subject to HubSpot script/CSP restrictions)
• Allowlist the widget host domain (for example, your-cdn.com) in Content Security Policy (CSP) if needed
• Listen for SWF_WIDGET_HEIGHT to resize iframe dynamically
• URL-encode all color parameters (# → %23)

Wix

• Recommended: Iframe embed via HTML Embed or Custom Element
• Supported: Direct script embed
• For iframe: Set an explicit height (for example, 600px) or use an auto-height script
• Ensure the iframe src domain (or script source domain) is allowlisted
• URL-encode all color parameters (# → %23)

Webflow

• Recommended: Iframe embed via Custom Code component
• Supported: Direct script embed
• For iframe: Set an explicit height or add a resize listener via postMessage
• URL-encode all color parameters (# → %23)

Squarespace

• Recommended: Iframe embed using a Code Block
• Supported: Direct script embed
• For iframe: Set an explicit height (Squarespace does not support dynamic iframe resizing)
• Ensure the iframe src domain (or script source domain) is allowlisted
• URL-encode all color parameters (# → %23)

WordPress

• Recommended: Iframe embed using Custom HTML block
• Supported: Direct script embed
• For script embeds, some themes or security plugins may block inline scripts
• For iframe: Set an explicit height or handle resizing via postMessage
• URL-encode all color parameters (# → %23)

Shopify

• Recommended: Iframe embed using Custom HTML section or Liquid template
• Supported: Direct script embed
• Script embeds may require adding the widget domain to Shopify’s allowed script sources
• For iframe: Set an explicit height or implement postMessage-based resizing
• URL-encode all color parameters (# → %23)

Travel search widget

Hotel deals showcase widget