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

The Switchfly Search Widget is a comprehensive travel search solution that adapts to your brand and customer needs. It provides a consistent, accessible user experience across all product types while offering extensive customization options for visual styling, language support, and product availability.

Supported Languages

The widget includes built-in translations for English, French, Spanish, and Japanese. All UI text, labels, error messages, and validation prompts are automatically localized based on the locale parameter.

Custom Product Tabs

Product tabs are fully configurable—control which travel products appear (bundles, air, hotel, car, activities) and in what order. You can also inject custom external tabs (e.g., "Cruises" or "Deals") at specific positions within the tab row.

Branding & Theming

Colors, accents, and interactive states can be customized using branding tokens. The widget supports hex, RGB, HSL, and CSS variable formats, allowing seamless integration with your existing design system.

Search Errors & Validation

The widget includes comprehensive client-side validation and displays server-side errors returned from the booking platform. Error messages are localized and presented in accessible modal dialogs with clear messaging and recovery options.

Datepicker & UX Patterns

All date selection uses a consistent, compact datepicker interface with range highlighting, constraint enforcement (minimum/maximum dates, product-specific rules), and keyboard navigation support. Time selection is enabled for product types that require it (e.g., car rentals).

⚠️ IMPORTANT: targetUrl is Required

All Switchfly widgets require an explicit targetUrl parameter. Widgets will not function and will display a configuration error if targetUrl is not provided.

• targetUrl specifies your booking platform domain (e.g., https://your-booking-site.com)
• Widgets use targetUrl as the base URL for API calls and search result navigation
• Widgets do not default to any Switchfly environment - this prevents accidental requests to internal/test systems
• Both script embed and iframe embed modes require targetUrl

SSO-Gated Loyalty Clients: For booking platforms protected by SSO (Single Sign-On), widgets work seamlessly *when configured properly to do so within Switchfly). When a user submits a search, the platform preserves the originally requested search URL through the SSO authentication flow and automatically redirects the user back to their search results after successful login. NOTE This is currently only supported for Switchfly's Standard Loyalty SSO.

• **Minimum supported width: 300px (below that, layout may stack / truncate)
• **Recommended embed width: 360px+

Widget Host vs Target URL

When integrating Switchfly widgets, it's important to distinguish between two URLs:

• Widget Host (your-cdn.com): The domain where widget HTML pages and JavaScript assets (IIFE bundle) are served from. This is used in:

  • Script embed: <script src="https://your-cdn.com/dist/switchfly-widgets.iife.js">
  • Iframe embed: <iframe src="https://your-cdn.com/widgets/search/...">

• Target URL (targetUrl): The booking/search platform domain where the widget redirects users when they submit a search. This is configured as:

  • Script embed: targetUrl: 'https://your-booking-site.com' (JavaScript config property)
  • Iframe embed: targetUrl=https%3A%2F%2Fyour-booking-site.com (URL parameter, URL-encoded)

In most deployments, the widget host and target URL are the same domain (e.g., both https://your-booking-site.com). However, they can be different if widgets are hosted on a separate CDN.

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/?targetUrl=https%3A%2F%2Fyour-booking-site.com&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/?targetUrl=https%3A%2F%2Fyour-booking-site.com&locale=en&maxItems=6&accentColor=%23dc2626"
  width="100%"
  height="600"
  frameborder="0">
</iframe>

postMessage API

Widgets communicate with parent windows via postMessage for various events:

Widget → Parent Messages:

• SWF_WIDGET_HEIGHT - Height changed (for iframe auto-resize)
• swf.widgets.search.navigate - Navigation request (required for sandboxed iframes)
• swf.widgets.search.error.dismissed - User dismissed error dialog

Parent → Widget Messages:

• swf.widgets.search.configure - Inject error display (see Error Handling section)

Complete Parent Page Snippet (Iframe Embed):

var iframe = document.getElementById('search-widget-iframe');

// Parse ERROR_MESSAGE from URL on page load
var urlParams = new URLSearchParams(window.location.search);
var errorCode = urlParams.get('ERROR_MESSAGE');

// Send error to widget on load if present
if (errorCode) {
  iframe.addEventListener('load', function() {
    iframe.contentWindow.postMessage({
      type: 'swf.widgets.search.configure',
      payload: {
        error: {
          code: errorCode,
          clearOnDismiss: true
        }
      }
    }, '*');
  });
}

// Listen for widget messages
window.addEventListener('message', function(event) {
  // Validate origin matches iframe src
  try {
    var iframeOrigin = new URL(iframe.src).origin;
    if (event.origin !== iframeOrigin) return;
  } catch (e) {
    return;
  }

  var data = event.data;

  // Auto-resize iframe
  if (data && data.type === 'SWF_WIDGET_HEIGHT') {
    var height = parseInt(data.height, 10);
    if (height > 0) {
      iframe.style.height = height + 'px';
    }
  }

  // Handle navigation requests (required for sandboxed iframes)
  if (data && data.type === 'swf.widgets.search.navigate') {
    var targetUrl = data.payload && data.payload.url;
    var openInNewTab = data.payload && data.payload.openInNewTab;

    if (targetUrl) {
      if (openInNewTab) {
        window.open(targetUrl, '_blank');
      } else {
        window.location.assign(targetUrl);
      }
    }
  }

  // Clear error params when dismissed
  if (data && data.type === 'swf.widgets.search.error.dismissed') {
    var url = new URL(window.location);
    url.searchParams.delete('ERROR_MESSAGE');
    window.history.replaceState({}, '', url);
  }
});

Sandboxed Iframe Navigation (HubSpot, etc.)

Problem: Some CMS platforms (like HubSpot) render iframes in sandboxed contexts without the allow-top-navigation permission. When the widget tries to navigate via window.top.location.href, the browser throws a security error.

Solution: The widget automatically detects iframe mode and sends navigation requests via postMessage instead of attempting direct navigation. The parent page listener performs the actual navigation.

How It Works:

1. Widget detects it's running in an iframe (window.self !== window.top)
2. On search submit, widget sends swf.widgets.search.navigate message to parent
3. Parent listener validates origin and performs navigation via window.location.assign()

Message Format:

{
  type: 'swf.widgets.search.navigate',
  payload: {
    url: 'https://booking-site.com/shopping?...',  // Full search URL
    reason: 'submit',                               // Always 'submit' for now
    openInNewTab: false                             // true if Cmd/Ctrl+Click
  }
}

Configuration Options:

• useParentNavigation (boolean, default: auto-detect) - Force postMessage navigation even for non-iframe embeds
• postMessageOrigin (string, default: '*') - Target origin for postMessage (more secure than wildcard)

Example with Custom Origin:

SwitchflyWidgets.createSearchWidget({
  containerId: 'search-widget',
  targetUrl: 'https://your-booking-site.com',
  useParentNavigation: true,
  postMessageOrigin: 'https://your-parent-site.com'
});

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 (searchParam):
  • Text search: searchParam=San%20Francisco - no label needed, resolves via typeahead API
  • Airport codes: searchParam=|airport:LAX (URL-encoded: %7Cairport:LAX) - no label needed, resolves via typeahead
  • Numeric city IDs: searchParam=|city:7321 (URL-encoded: %7Ccity:7321) - REQUIRES prefillDestinationLabel=San%20Diego
    • Typeahead API cannot resolve numeric city IDs, so display label must be provided explicitly
    • Both parameters are required for numeric IDs to prefill correctly
• 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

For developers who need complete control over UI and want to build custom search interfaces, the Switchfly JavaScript SDK provides direct access to location APIs and URL building without using pre-built widgets.

When to Use SDK vs Widgets

Use Pre-built Widgets when:

• You want a ready-made, tested UI with minimal integration effort
• Standard search functionality meets your needs
• You prefer iframe or script embed without writing custom code
• You need multi-product search (air, hotel, car, activities, bundles) out of the box

Use JavaScript SDK when:

• You need complete UI control (custom forms, styling, frameworks)
• Building a highly customized search experience
• Integrating search into existing UI patterns or design systems
• Want to compose search functionality with other features (e.g., combining with your own filters, recommendation engine, etc.)

Installation

ES Modules (recommended):

import { createClient } from 'https://your-cdn.com/packages/sdk/src/index.js';

NPM (when published):

npm install @switchfly/sdk

import { createClient } from '@switchfly/sdk';

Quick Start Example (Hotel Search)

Complete working example showing location autocomplete and search URL generation:

<!DOCTYPE html>
<html>
<head>
  <title>Custom Hotel Search</title>
</head>
<body>
  <form id="hotelSearchForm">
    <input type="text" id="destination" placeholder="Enter city" autocomplete="off" required>
    <div id="autocompleteResults"></div>

    <input type="date" id="checkin" required>
    <input type="date" id="checkout" required>

    <button type="submit">Search Hotels</button>
  </form>

  <script type="module">
    import { createClient } from 'https://your-cdn.com/packages/sdk/src/index.js';

    // Initialize SDK client
    const sdk = createClient({
      targetUrl: 'https://your-booking-site.com',
      locale: 'en-US'
    });

    let selectedLocation = null;
    let debounceTimer = null;

    const destinationInput = document.getElementById('destination');
    const autocompleteResults = document.getElementById('autocompleteResults');
    const form = document.getElementById('hotelSearchForm');

    // Location autocomplete
    destinationInput.addEventListener('input', async (e) => {
      const query = e.target.value.trim();

      clearTimeout(debounceTimer);
      selectedLocation = null;

      if (query.length < 2) {
        autocompleteResults.innerHTML = '';
        return;
      }

      debounceTimer = setTimeout(async () => {
        try {
          const response = await sdk.locations.suggest({
            query,
            locationType: 'DESTINATION',
            productTypes: 'ROOM'  // Use 'ROOM' for hotel searches
          });

          const locations = response?.data?.locations || [];

          // Render results
          autocompleteResults.innerHTML = locations.map(loc => `
            <div class="autocomplete-item" data-location='${JSON.stringify(loc)}'>
              ${loc.nameDisplayValue || loc.displayValue}
            </div>
          `).join('');

          // Handle selection
          autocompleteResults.querySelectorAll('.autocomplete-item').forEach(item => {
            item.addEventListener('click', () => {
              const loc = JSON.parse(item.dataset.location);
              selectedLocation = loc;
              destinationInput.value = loc.nameDisplayValue || loc.displayValue;
              autocompleteResults.innerHTML = '';
            });
          });

        } catch (error) {
          console.error('Autocomplete error:', error);
        }
      }, 300);
    });

    // Form submission
    form.addEventListener('submit', (e) => {
      e.preventDefault();

      if (!selectedLocation) {
        alert('Please select a destination');
        return;
      }

      // Build search URL
      const searchInfo = {
        type: 'HOTEL',
        location: selectedLocation.search,  // Location token like '|city:7321'
        fromDate: document.getElementById('checkin').value,
        toDate: document.getElementById('checkout').value,
        rooms: [{ adults: 2, childAges: [] }]
      };

      const url = sdk.search.buildUrl(searchInfo);

      console.log('Search URL:', url.href);
      window.location.href = url.href;  // Navigate to search results
    });
  </script>
</body>
</html>

API Reference

createClient(config)

Create an SDK client instance.

Parameters:

• config.targetUrl (string, required): Target booking platform URL (e.g., 'https://your-booking-site.com')
• config.locale (string, optional): Locale string (e.g., 'en-US', 'fr', 'es', 'ja')
• config.cobrand (string, optional): Cobrand identifier for analytics/tracking
• config.apiPathPrefix (string, optional): Custom API path prefix (default: '')
• config.timeout (number, optional): Default request timeout in milliseconds (default: 10000)
• config.headers (object, optional): Custom headers for API requests
• config.fetch (function, optional): Custom fetch implementation

Returns: SDK client instance with locations, search, and utils modules

Example:

const sdk = createClient({
  targetUrl: 'https://your-booking-site.com',
  locale: 'en-US',
  cobrand: 'partner123',
  timeout: 15000
});

sdk.locations.suggest(options)

Search for location suggestions (autocomplete).

Parameters:

• options.query (string, required): Search query (minimum 2 characters recommended)
• options.locationType (string, required): Location type
  • 'ORIGIN' - Departure locations (airports)
  • 'DESTINATION' - Arrival/destination locations (cities, airports, hotels)
  • 'ORIGIN_DESTINATION' - Both origin and destination
• options.productTypes (string, required): Comma-separated product types
  • 'AIR' - Flights/airports
  • 'ROOM' - Hotels/accommodations (note: use ROOM, not HOTEL)
  • 'CAR' - Car rentals
  • 'ACTIVITY' - Activities/experiences
  • Examples: 'AIR', 'ROOM', 'AIR,ROOM'
• options.includeHotels (boolean, optional): Include individual hotel properties in results
• options.originLocation (string, optional): Origin location token for route-based filtering
• options.crsName (string, optional): Filter by CRS system name
• options.provider (string, optional): Filter by provider
• options.signal (AbortSignal, optional): AbortSignal for request cancellation

Returns: Promise