Widget events
The widget is "sandboxed", which means that it doesn't affect anything outside of its DOM container¹ or its scope (the
pbk
object) in the JavaScript.
Therefore, in order to facilitate interaction with the hosting page, the widget has an external API which allows the page to listen for events sent from the widget.
¹ This is mostly true, but the widget actually dynamically adds and removes a few DOM elements outside of its container.
Listeners
In order to receive an event sent from the Wiget there has to be something listening to it. Listeners can be created in two ways:
- Once the widget has loaded, the
pbk
object will have alisten()
method. It takes two parameters: the name of the event to listen for and the handler function that will be invoked with the data that was sent in the event, if any. Multiple listeners can be created for the same notification, they will be invoked in the order they were created. Thelisten()
method returns a listener object. It has a method calledunlisten()
which, when invoked, will remove the listener so that it will no longer receive any events. Using theunlisten()
method in the listener object returned when creating the listener is the only way to remove it, so don't throw away this object if you ever need to remove the listener. - Listeners can be pre-defined before the widget has loaded by extending the
pbk
object with alisteners
object containing key-value pairs where the key is the name of the event and the value is the handler function. When the widget loads, it will create listeners from these key-value pairs and then replace the value (the handler function) with the listener object so that theunlisten()
method will be available. This is, in practice, the only way a listener for theready
notification can be created since thelisten()
method doesn't exist before the widget is actually ready and that event has already been sent.
Examples
viewChanged
event and remove once the current step is "view-confirmation"
Add a listener for the var listener = pbk.listen('viewChanged', function(data) {
console.log('New step: ' + data.id);
if (data.id === 'view-confirmation') {
listener.unlisten();
listener = undefined;
}
});
ready
event that announces it in the console
Pre-define a listener for the var pbk = {
settings: { /* settings from your snippet. */ },
listeners: {
ready: function() {
console.log('Widget is ready!');
}
}
};
Remove the listener from the previous example
pbk.listeners.ready.unlisten();
dispatch()
function
The There's an alternative way to handle incoming events: adding a function called dispatch
to the pbk
object.
If this function exists when an event is sent by the widget, it will be invoked with the name of the event. It will not be passed the data sent in the event, but if the dispatch function returns a callback function, this callback function will in turn be invoked with the data. This allows the partner to have a more centralized handling of events and do things such as creating default behavior for all unhandled and unknown events.
The dispatch function can be created, removed and overwritten at any time, whatever is defined (or not defined) as
pbk.dispatch
when an event is being sent is what matters at that particular time. The dispatch function and any
callbacks it returns will be invoked before any listeners created with pbk.listen()
, but it doesn't prevent those from
being invoked as normal.
Example
Add a dispatch function that handles navigation notifications and invokes tracking behavior.
function trackProgress(data) {
addTrackingPixel(data.id);
}
function trackConversion(data) {
addConversionPixel(data.confirmationNumber, data.pricing.ratePerDay.amount);
}
pbk.dispatch = function(event) {
switch (event) {
case 'viewChanged':
return trackProgress;
case 'reservationCompleted':
return trackConversion;
default:
console.warn('Unknown event: ' + event);
}
}
Supported events
Some events have more data than listed here, but they aren't officially supported and may change with no warning.
ready
Sent when the widget is initialized and ready to be used.
It has no data.
viewChanged
Sent when the view has changed.
Data
{
id: string // The new step's ID.
}
Example
{
id: 'driver-details'
}
reservationCompleted
Sent when a new reservation is made.
Data
{
confirmationNumber: string, // The new reservation's ID.
pricing: {
ratePerDay: { // The base price per day.
total: number, // The price as an integer that includes decimals.
currency: string // The currency code.
},
rateTotalAmount: { // The base price for the entire rental.
total: number, // The price as an integer that includes decimals.
currency: string // The currency code.
}
}
}
Example
{
confirmationNumber: '1234567890',
pricing: {
ratePerDay: { // This means USD 99,95
total: 9995,
currency: 'USD'
},
rateTotalAmount: { // This means USD 299,85
total: 29985,
currency: 'USD'
}
}
}
reservationModified
Sent when a reservation is modified.
It has no data.
reservationCancelled
Sent when a reservation is cancelled.
It has no data.
localeChanged
Sent when the widget's locale changes.
Data
{
// A string containing an ISO 639-1 language code with
// an optional an ISO 3166-1 alpha 2 country code.
locale: string
}
Example
{
locale: 'es'
}
{
locale: 'en_GB'
}