Witbooking Widgets

Modified on Wed, 20 May at 4:15 PM

Introduction

Witbooking Widgets SDK is a set of tools that allows integrating the booking engine into the establishment's website.

It offers a very simple way to integrate the booking engine into the website, allowing you to customize the appearance and design of the booking engine to match the website, but also gives the flexibility to customize the user experience according to needs.

Prerequisites

It is essential ensure that the engine you will be working with has our new v21 engine and loyalty system configured before starting the Witbooking Widgets setup. If this is not possible, the Witbooking Widgets setup will not be possible.

To use the SDK, you need basic knowledge of web programming and be familiar with the following languages and technologies:

HTML
JavaScript

It is important that before starting to configure Witbooking Widgets Our Widget system must respond under a subdomain of your website to ensure the correct behavior of cookies between systems. To do this, you must create the following CDM in the DNS zone of your domain and notify the Witbooking team of the generated CNAME:

Type Name Value CNAME wit-widgets cname.vercel-dns.com

*In the CNAME name you can indicate whatever you prefer, on our side we recommend wit-widgets.

This new domain is the value you must set in the hostWidgets specified in the Initialization.

Domains where the Widget will be used

The Witbooking team must be notified of the list of domains from which the Widgets will be used, in order to grant permissions to use them. That is, if the Widgets will be used within a landing page, you must notify us which domain responds to that landing page, for example https://www.witbooking.com. If this step is not done, the following error will appear:

Open image (2).png

Download and installation

To implement our SDK, you must use our CDN link:

https://widgets.dev.witbooking.com/beta/1.0.0-beta.1/sdk.js

The beta version is an early test of our software with new features. It may have minor issues, so we value your feedback to improve it before the official release.

To install the SDK, simply paste this code snippet into the <head> o <body> de su sitio web. Don't worry, it won't slow down your website's performance, we promise!

<script>       (function (w, d) {         if (w.WitBooking) {           console.error("WitBooking embed already included");           return;         }         w.WitBooking = { _c: [] };         [           "init",           "login",           "getCurrentUser",           "logout",           "showOptionsWidget",           "setOptionsWidgetConfig",           "setTheme",           "setCustomization",         ].forEach(           (me) =>             (w.WitBooking[me] = function () {               w.WitBooking._c.push([me, arguments]);             })         );         var sc = d.createElement("script");         sc.type = "text/javascript";         sc.async = true;         sc.src = "https://widgets.dev.witbooking.com/beta/1.0.0-beta.1/sdk.js";         var before = d.getElementsByTagName("script")[0];         before.parentNode.insertBefore(sc, before);       })(window, document); </ script> 

This ensures that the script loads asynchronously and that the SDK loads only once, even if the script is included multiple times on the website. The asynchronous part is important to ensure that the SDK does not block the loading of the website, as it may take some time to load, depending on the client's internet connection.

Additionally, it ensures that the SDK can be accessed immediately through the global WitBooking, even if the SDK is still loading. All public methods of the SDK are exposed through this property and in case the SDK has not yet loaded, method calls are queued and executed once the SDK loads.

Initialization

Before being able to use the Widgets, you must initialize the SDK. To initialize the SDK, you must call the init. This method accepts an object with the following properties:

hostWidgets: Domain of our widgets that must be a subdomain of the website domain.
hostLoyalty : Engine loyalty service domain
hostMain: Engine domain.
formType: Identifier of the form type to be displayed. Possible values are "company", "agency" or "customer". By default, the value is customer.
tierId: Identifier of the tier the user will have when registration is completed. It is required to create any organization, i.e., if the form type is agency or company, it is mandatory. If not included, the form will show an error.
organizationId: Identifier of the company or agency the user wants to associate with after registration. It is an optional parameter and can be combined with the tierId parameter. If both organizationId and tierId are provided, the user will register with these parameters. If tierId is not provided, the system will take the default progression tier.
uiLocales: Language in which the forms should be rendered.
propertyTicker: Hotel identifier.
brand: Brand name assigned to the hotel.
analyticsCodes (optional): Google Analytics UA code separated by commas.
analyticDomains (optional): Domain registered in Google Analytics.
isChain (optional): Identifies whether the engine corresponds to an individual property or a property aggregator. The value must be true or false and its default value is false.
tierCompanyId (optional): Id of the tier to be assigned by default to companies that register. This property enables the company option in the header menu.
tierAgencyId (optional): Id of the tier to be assigned by default to agencies that register. This property enables the agency option in the header menu.
gtmCodes (optional): Array containing the Google Tag Manager containers to be configured. It is an optional field and can be one or more. If you only want to include one ID, send it as follows:: gtmCodes:["GTM-123"].

This is an example of calling the init :

WitBooking.init({   hostWidgets : "https://widgets-dev.witbooking.com",   hostMain: "engine.devel.witbooking.com",    hostLoyalty: "auth-loyalty.devel.witbooking.com",   brand:  "witbrand",   propertyTicker: "petit_santabarbara",   formType : "customer",   uiLocales: "es",    tierCompanyId: "83c29a44-a4c6-43e6-9d0a-abbec0096173",   tierAgencyId:  "cb2d2cdd-fc4e-42f2-81ba-0c1641c57cd7",   isChain: false,   gtmCodes : ["GTM-123", "GTM-456"] } );

The data being used in this example is data from our development servers that you can use in your development environment, but it is important that it is not used in production.

We recommend calling the initmethod within the same <script>etiqueta que el script de instalación (incluido en el paso anterior), pero no es necesario. Puede llamar al método init desde cualquier parte de su código, siempre que se llame antes que cualquier otro método del SDK, o el SDK arrojará un error.

Additionally, you can also provide a onload callback, which will be called as soon as the SDK is ready to be used. This should not be necessary. SDK methods can be called at any time, without worrying about its state. However, if you still want to subscribe to this event, here is how to do it:

WitBooking.onload = ()  => {   console.log("WitBooking loaded" , WitBooking); };

Configurations

The SDK allows you to configure the appearance of the booking engine to match the website design. Currently, there are two ways to customize the booking engine, but we are working on adding more customization options. You can update the booking engine theme, but you can also customize individual widget properties (more information in the Widgets section).

Theme

You can update the theme elements of the engine by calling the setTheme. This method accepts an object with the following properties:

{   colors: {     primary : string;     secondary: string;   } } 

You can update the theme elements of the engine by calling the setTheme. This method accepts an object with the following properties:

Here is an example of how to update the theme:

WitBooking.setTheme({   colors : {     primary: "#ff0000",     secondary : "#0000ff"   } }); 

As with the init call, we recommend calling setTheme right after initialization, but it is not necessary. You can call this method at any time, but note that if a Widget is being displayed to the user, the changes will be applied to the Widget immediately, so the user may notice a sudden change in the Widget's appearance.

Authentication

The SDK allows you to authenticate users using the Loyalty API. It offers these methods to handle user authentication for you:

Are you logged in?

To check if the user is currently logged in, you can call the isLoggedIn. This method returns a boolean value indicating whether the user is logged in or not.

if (WitBooking.isLoggedIn( )) {   console.log( "El usuario está conectado"); } else {   console .log("El usuario no está conectado"); } 

Login

The login will open a popup with the login form. Users can log in or register from this form. This method returns a promise that will resolve with the user object if the user logs in, or will be rejected if the user closes the popup or some other problem occurs.

WitBooking.login()   . then(user => {     console.log ("Usuario conectado", user);   })    .catch(error => {     console .log("Ocurrió algún error.", error);    }); 

You don't need to manage the promise to successfully authenticate the user. The SDK will handle authentication for you and the next time you call the isLoggedIn, will return true. You can retrieve the authenticated user information at any time by calling the getCurrentUser a continuación.

We also have an onLogin el cual se ejecuta con la sección cuando el login es exitoso, puede ser útil dependiendo del flujo que se utilice (más información en la sección de Widgets), for example:

WitBooking.onLogin = (session)  => {     loadUser(session.guestData.name) ;     setCheckAvailability(session.id); } ; 

Get current user

The getCurrentUser returns a promise that will resolve with the current user information (the same user object received in the login method). If the user is not authenticated, it will be rejected with an error.

WitBooking.getCurrentUser()   . then(user => {     console.log ("Usuario conectado", user);   })    .catch(error => {     console .log("El usuario no está conectado", error);    }); 

Logout

You can log the user out by calling the logout. Este método returns a promesa que se resolverá cuando se haya realizado correctamente el cierre de sesión.

WitBooking.logout()   . then(() => {     console .log("Usuario desconectado");   } )   .catch(error => {     console .log("Ocurrió algún error.", error);    }); 

When the user logs out successfully, the onLogout event will also be executed to notify the parent that the session has been closed.

WitBooking.onLogout = ()  => {   console.log("onLogout" ) } 

Close Widget

The close, cierra el modal y cancela el flujo si esta ocurriendo en ese momento:

WitBooking.close();

Widgets

The SDK offers a set of widgets that you can use to display the booking engine on your website. Each widget has its own customization options that you can use to customize the appearance and behavior of the widget. However, you can also use the default configuration and the widget will work without issues.

Options Widget

The Options Widget displays a popup showing the user's profile details (name, email address, and category level). It also offers two options: allowing the user to log out or go to their booking page.

If the user is not authenticated, this widget will automatically prompt them to log in or register and then automatically display the user's profile details.

You can display the Options Widget by calling the showOptionsWidget method.

WitBooking.showOptionsWidget() ;

Additionally, you can choose to customize the Options Widget by calling the setOptionsWidgetConfig method. This method accepts an object with the following properties:

WitBooking.setOptionsWidgetConfig({   translations : {     greeting: "La traducción para el mensaje de saludo. Por defecto es 'Hola'",     tier : "La traducción para la etiqueta de nivel. Por defecto es 'Nivel'",     buttons: {       bookings : "La traducción para el botón de reservas. Por defecto es 'Ir a mis reservas'",       close: "La traducción para el botón de cerrar. Por defecto es 'Seguir navegando'",        signOff: "La traducción para el botón de cierre de sesión. Por defecto es 'Logout'"     }   },    actions: {     bookings: {        hostMain: "URL de hostMain. Por defecto es el valor pasado durante la inicialización",       propertyTicker:  "propertyTicker. Por defecto es el valor pasado durante la inicialización",     },     signOff: {        hostMain: "URL de hostMain. Por defecto es el valor pasado durante la inicialización",       brand:  "Marca. Por defecto es el valor pasado durante la inicialización",       sessionId: "propertyTicker. Por defecto es el valor pasado durante la inicialización"     }   }  });

You don't need to provide all the configuration parameters at once; you can update the settings as many times as you like, and only the parameters you provide will be updated. Here's an example of customizing the Options Widget:

WitBooking.setOptionsWidgetConfig({   translations : {     greeting: 'Hola',     tier : 'Nivel',     buttons: {       bookings : 'Ir a mis reservas',       signOff: 'Cerrar sesiòn'     }    } });

It should be noted that if the widget is currently being displayed to the user, the changes will be applied to the widget immediately, so the user may notice a sudden change in the widget's appearance. Therefore, you should make sure to call this method before showing the Widget.

Translations

Our Widget automatically detects the browser language and performs the corresponding translation by default. Currently, we support the following languages:

Spanish (es)
Basque (eu)
English (en)
German (de)
Catalan (ca)
Portuguese (pt)
Dutch (nl)
Russian (ru)
Italian (it)
French (fr)
Korean (ko)
Danish (da)

If you need to use a language that is not on this list, you can use the setOptionsWidgetConfig specified in the previous point and pass the corresponding translation. The Widget will prioritize the configuration you send through the setOptionsWidgetConfig.

Usage examples

We have a demo web page that simulates a hotel website and has our widgets implemented:

Demo

Example web page code:
examples.zip

Troubleshooting

If you have any questions, problems, or suggestions regarding Witbooking Widgets, do not hesitate to contact us at soporte@witbooking.com. Our support team will be happy to help you resolve any issues you may have. Remember, we are here to help you succeed in your lodging business and provide a seamless booking experience for your customers.