The Booking Widget SDK allows organizations to embed a ride-booking widget into their web applications.

¶ Installation

The SDK is available via a CDN and can be included in your project using a <script> tag.

<script src="https://tb-static.uber.com/prod/u4b-external-api/U4bApiWidgets-v_1_0_0.js"></script>

Once loaded, the SDK is available as a global variable U4bApiWidgets.

¶ Usage

The SDK exposes a function WidgetsSDK that must be invoked to initialize an instance of the widget.

const bookingWidget = U4bApiWidgets.WidgetsSDK({
  fetchWidgetToken: async () => 'your-transient-token',
  WidgetPayloadHandler: (data) => {
    // Handle the booking payload
    console.log('Booking payload:', data.createRidePayload);
    console.log('Additional info:', data.additionalInfo);
  },
  orgUUID: 'your-organization-uuid',
  WidgetEventHandler: (event) => {
    console.log('Widget event received:', event);
  },
  widgetHydration: {
    firstName: 'John',
    lastName: 'Doe',
    phoneNumber: '1234567890',
    phonePrefix: '+1',
    pickupAddress: '1 Market St, San Francisco',
    dropoffAddress: 'SFO Airport'
  }
});

¶ API Reference

For detailed information about the createRidePayload structure, please refer to the Guest Trips API documentation.

The additionalInfo object in the WidgetPayloadHandler contains fare information for the trip(s):

{
  outbound: {
    fare_value: number; // Fare value with 2 decimal precision
    currency_code: string; // Standard 3-letter currency code (e.g., 'USD', 'EUR')
  },
  inbound: { // Key is always present, value is undefined if no return trip
    fare_value: number;
    currency_code: string;
  } | undefined
}

• outbound → one-way trip fare information
• inbound → return trip; key is always present, but value may be undefined if no return
• fare_value → number with 2 decimal precision (e.g., 5.00, 6.32)
• currency_code → standard 3-letter currency code (e.g., ‘USD’, ‘EUR’)

¶ WidgetsSDK({ fetchWidgetToken, WidgetPayloadHandler, orgUUID, WidgetEventHandler, widgetHydration? }): WidgetInstance

Initializes a new instance of the Widget SDK.

¶ Parameters

• fetchWidgetToken (function) – Required. Returns a transient token for authentication. Must return a Promise<string | undefined | null>.

• WidgetPayloadHandler (function) – Required. Handles booking payloads. Receives an object with createRidePayload and additionalInfo.

• orgUUID (string) – Required. Organization UUID.

• WidgetEventHandler (function) – Required. Callback to handle widget events. Receives { type, payload }. For Booking widget payload is always null

• widgetHydration (object, optional) – Prefills the booking form.

  • firstName, lastName, phoneNumber, phonePrefix, pickupAddress, dropoffAddress
  • If phoneNumber is provided, phonePrefix is required.

¶ Returns

A WidgetInstance with the following methods:

• mountBookingWidget(id: string): void – Mounts the widget inside the specified HTML container.
• unmountBookingWidget(id: string): void – Unmounts the widget from the specified container.

¶ Example

const bookingWidget = U4bApiWidgets.WidgetsSDK({
  fetchWidgetToken: async () => 'your-transient-token',
  WidgetPayloadHandler: (data) => {
    console.log('Booking payload:', data.createRidePayload);
    console.log('Additional info:', data.additionalInfo);
  },
  orgUUID: 'your-organization-uuid',
  WidgetEventHandler: (event) => {
    console.log('Widget event received:', event);
  }
});

¶ mountBookingWidget(id: string): void

Mounts the booking widget inside the specified HTML container.

¶ Parameters:

• id (string) – The ID of the HTML element where the widget should be mounted.

¶ Example:

document.addEventListener('DOMContentLoaded', () => {
  bookingWidget.mountBookingWidget('widget-container');
});

¶ unmountBookingWidget(id: string): void

Removes the booking widget from the specified HTML container.

¶ Parameters:

• id (string) – The ID of the HTML element where the widget is currently mounted.

¶ Example:

bookingWidget.unmountBookingWidget('widget-container');

¶ Events

¶ Security

The widget implements several security measures:

• The iframe uses referrerPolicy="strict-origin-when-cross-origin" for enhanced security
• All communication between the parent window and iframe is done through the secure postMessage API
• Messages are only accepted from trusted origins based on the environment
• The widget validates all required parameters and functions before initialization

¶ Error Handling

The Widget SDK throws explicit errors when invalid arguments are passed or if any required function fails. Additionally, it sends error events via WidgetEventHandler for better tracking.

¶ Errors in WidgetsSDK

¶ Missing fetchWidgetToken

throw new Error('fetchWidgetToken must be a function');

¶ Missing WidgetPayloadHandler

throw new Error('WidgetPayloadHandler must be a function');

¶ Invalid orgUUID

throw new Error('orgUUID must be a valid string');

¶ Duplicate SDK Instance

throw new Error('An instance of BookingWidgetSDK already exists.');

¶ Errors in mountBookingWidget

¶ Invalid Element ID

throw new Error('An element ID is required to mount the widget');

¶ Element Not Found

throw new Error(`No element found with id ${id}`);

¶ Token Required

throw new Error('Token is required to mount the widget');

¶ Errors in widgetHydration

¶ widgetHydration is not an Object

throw new Error('widgetHydration must be an object');

¶ phoneNumber provided but phonePrefix is missing

throw new Error('phonePrefix must be provided if phoneNumber is provided');

¶ Errors in unmountBookingWidget

throw new Error('An element ID is required to unmount the widget');

¶ Invalid Element ID

throw new Error('An element ID is required to unmount the widget');

¶ Element Not Found

throw new Error(`No element found with id ${id}`);

¶ Example Integration

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Booking Widget Example</title>
  <script src="https://tb-static.uber.com/prod/u4b-external-api/U4bApiWidgets-v_1_0_0.js"></script>
</head>
<body>
  <div id="widget-container" style="width: 100%; height: 500px;"></div>
  <script>
    const bookingWidget = U4bApiWidgets.WidgetsSDK({
      fetchWidgetToken: async () => 'your-transient-token',
      WidgetPayloadHandler: (data) => {
        // Handle the booking payload
        console.log('Booking payload:', data.createRidePayload);
        console.log('Additional info:', data.additionalInfo);
      },
      orgUUID: 'your-organization-uuid',
      WidgetEventHandler: (event) => {
        console.log('Widget event:', event);
      }
    });

    bookingWidget.mountBookingWidget('widget-container');
  </script>
</body>
</html>