Trip Tracking Widget
The Trip Tracking Widget SDK allows organizations to embed a 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 trackingWidget = U4bApiWidgets.WidgetsSDK({
fetchWidgetToken: async () => 'your-transient-token',
orgUUID: 'your-organization-uuid',
WidgetEventHandler: (event) => {
console.log('Tracking widget event:', event);
},
tripUUID: 'existing-trip-uuid', // required for tracking an existing trip
});
¶ WidgetsSDK({ fetchWidgetToken, orgUUID, WidgetEventHandler, tripUUID }): WidgetInstance
Initializes a new instance of the Widget SDK.
¶ Parameters
fetchWidgetToken(function) – Required. Returns a transient token for authentication. Must return aPromise<string | undefined | null>.orgUUID(string) – Required. Organization UUID.WidgetEventHandler(function) – Required. Callback to handle widget events. Receives{ type, payload }. Payload will have tripUUID in case tracking widget sendsTRIP_STATE_UNTRACKABLEandTRACKING_ERROReventstripUUID(string) – Required. The trip identifier for the trip to be tracked.
¶ Returns
A WidgetInstance with the following methods:
mountBookingWidget(id: string): void– Mounts the tracking widget inside the specified HTML container.unmountBookingWidget(id: string): void– Unmounts the tracking widget from the specified container.
¶ Events
| Event Type | Description |
|---|---|
WIDGET_CLOSED |
Triggered when the widget is closed. |
TRIP_STATE_UNTRACKABLE |
Triggered when an existing trip becomes untrackable. |
TRACKING_ERROR |
Triggered when tracking fails for an existing trip. |
¶ 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
postMessageAPI - 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 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>Tracking 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 trackingWidget = U4bApiWidgets.WidgetsSDK({
fetchWidgetToken: async () => 'your-transient-token',
orgUUID: 'your-organization-uuid',
WidgetEventHandler: (event) => {
console.log('Tracking widget event:', event);
},
tripUUID: 'existing-trip-uuid'
});
trackingWidget.mountBookingWidget('widget-container');
</script>
</body>
</html>
Installation
Usage
WidgetsSDK({ fetchWidgetToken, orgUUID, WidgetEventHandler, tripUUID }): WidgetInstance
Parameters
Returns
Events
Security
Error Handling
Errors in WidgetsSDK
Missing fetchWidgetToken
Missing WidgetPayloadHandler
Invalid orgUUID
Duplicate SDK Instance
Errors in mountBookingWidget
Invalid Element ID
Element Not Found
Token Required
Errors in unmountBookingWidget
Invalid Element ID
Element Not Found
Example Integration