¶ Introduction

The Widget SDK provides pre-made user interfaces that help speed up the integration with Uber APIs. This guide will focus on the Ride Booking Widget which allows Uber partners to book rides without having to implement a booking form from scratch. The SDK will eventually support more use cases.

¶ Concepts

• Partner frontend: The application that will expose Uber features to an end user.
• Partner backend: A backend service for secure communication between the partner and Uber systems.
• Uber API: This is the collection of Uber REST endpoints that can be used directly or in conjunction with the Widget SDK.

¶ Authentication

Two authentication tokens are required.

¶ Business-to-business aka B2B (OAuth 2.0) token

This token is extensively documented in our authentication docs and it’s needed to call Uber APIs whether you decide to use the widget or not. It will be used to:

• Secure communications between the partner backend and Uber APIs.
• Obtain a Widget Transient token that will grant access to the widget.

¶ Widget Transient token

This is a new token. It will be used to:

• Instantiate the widget UI.

¶ Use case

Use this endpoint to create a widget transient token.

If the request is from a third party (3P) app, please add x-uber-organizationuuid header and the Organization UUID as the value or the request will be denied.

¶ Authorization

OAuth 2.0 Bearer token with the guests.trips scope.

¶ Request

¶ Example request

Try It

curl -X POST \
  -H "authorization: Bearer <access_token>" \
  -H 'content-type: application/json' \
  -d '{
        "external_user_id": "<fill with external user uuid>"
      }' \
      'https://api.uber.com/u4b/v1/widget/transienttoken'

¶ Request headers

¶ Request body parameters

¶ Response

¶ Example response

{
  "token": "<validtoken>"
}

¶ Response body parameters

¶ Endpoint Possible Errors

¶ Booking Widget Frontend

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/booking-widget/U4bApiWidgets-v_1_0_0.js"></script>

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

¶ Usage

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

const bookingWidget = U4bApiWidgets.createBookingWidgetSDK({
  fetchTransientToken: async () => 'your-transient-token',
  BookingWidgetPayloadHandler: (data) => {
    // Handle the booking payload
    console.log('Booking payload:', data.creteaRidePayload);
    console.log('Additional info:', data.additionalInfo);
  },
  orgUUID: 'your-organization-uuid',
  WidgetEventHandler: (event) => {
    console.log('Widget event received:', event);
  },
});

¶ API Reference

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

The additionalInfo object in the BookingWidgetPayloadHandler 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; // Fare value with 2 decimal precision
    currency_code: string; // Standard 3-letter currency code (e.g., 'USD', 'EUR')
  } | undefined
}

• outbound represents the one-way trip fare information
• inbound represents return trip; key is always present in the object, but its value is undefined if only one-way trip is created.
• fare_value is a number with 2 decimal precision (e.g. 5.00, 6.32)
• currency_code is a standard 3-letter currency code (e.g., ‘USD’, ‘EUR’)

¶ createBookingWidgetSDK({ fetchTransientToken, BookingWidgetPayloadHandler, orgUUID, WidgetEventHandler }): BookingWidgetSDKInstance

Initializes a new instance of the Booking Widget SDK.

¶ Parameters:

• fetchTransientToken (function) – A function that returns a transient token required for authentication. It must return a Promise<string | undefined | null>.
• BookingWidgetPayloadHandler (function) – A function that handles booking payloads. Receives an object with creteaRidePayload and additionalInfo.
• orgUUID (string) – A unique identifier for the organization.
• WidgetEventHandler (function) – A callback function to handle widget events.

¶ Returns:

A BookingWidgetSDKInstance 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.createBookingWidgetSDK({
  fetchTransientToken: async () => 'your-transient-token',
  BookingWidgetPayloadHandler: (data) => {
    // Handle the booking payload
    console.log('Booking payload:', data.creteaRidePayload);
    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 Booking 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 createBookingWidgetSDK

¶ Missing fetchTransientToken

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

¶ Missing BookingWidgetPayloadHandler

throw new Error('BookingWidgetPayloadHandler 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 unmountBookingWidget

¶ 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/booking-widget/U4bApiWidgets-v_1_0_0.js"></script>
</head>
<body>
  <div id="widget-container" style="width: 100%; height: 500px;"></div>
  <script>
    const bookingWidget = U4bApiWidgets.createBookingWidgetSDK({
      fetchTransientToken: async () => 'your-transient-token',
      BookingWidgetPayloadHandler: (data) => {
        // Handle the booking payload
        console.log('Booking payload:', data.creteaRidePayload);
        console.log('Additional info:', data.additionalInfo);
      },
      orgUUID: 'your-organization-uuid',
      WidgetEventHandler: (event) => {
        console.log('Widget event:', event);
      }
    });

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