Getting started
By using the Booking Engine Widget, your users can book directly from your website. To use the Booking Engine Widget, follow these steps:
In addition, you also have the following options:
Warning: In order to embed the booking engine into your webpage, your site must be securely served over HTTPS. Any Booking Engine Widget that is implemented on an insecure HTTP site will be redirected to the Booking Engine Standalone.
To use the Booking Engine Widget, you need to install the booking engine loader script with a code snippet provided in the Installation section below. The script will asynchronously prepare global object
Mews.Distributor
which you're going to use in further steps to initialize the Booking Engine Widget.Use the code snippet 'as is' and as described, doing otherwise may cause unexpected problems and is not supported.
- Do not place the code snippet anywhere else than in the
<head>
- Do not modify the code snippet in any way and do not attach the
async
attribute - Do not use the code snippet inside an
iframe
- Do not add the Booking Engine Standalone URL (e.g.
https://app.mews.com/distributor/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
) to theiframe
- Do not pack the contents of the script files that the code snippet references into your own JavaScript bundle
- Do not use a booking engine script cached by your server, use the one from this Guide
The script file size is kept as minimal as possible (approx 11 kB gzipped) to allow quick web page initialization. Also, serving the script from our CDN servers ensures seamless releases of new features, bug fixes and improvements.
- If you have a Content Security Policy (CSP) set up on your website, you need to enable the domains that the booking engine uses - see Content Security Policy under Installation below
Place the following
<script>
code snippet in the <head>
of your web page's HTML, preferably as close to the opening <head>
tag as possible.Correct:
<script src="https://api.mews.com/distributor/distributor.min.js"></script>
Incorrect - DO NOT DO THIS:
<script src="https://www.your_domain.tld/wp-content/cache/min/1/distributor/distributor.min.js?ver=1628071961"></script>
<script async src="https://api.mews.com/distributor/distributor.min.js"></script>
<script src="https://apps.mews.com/distributor/prerelease/production/3.924.4/distributor.js"></script>
<iframe src="https://api.mews.com/distributor/distributor.min.js"></iframe>
<iframe src="https://api.mews.com/distributor/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"></iframe>
Warning: Please double-check that you've added the script as instructed and followed all the requirements above. If the script tag is not used correctly, it can cause unexpected problems even when it seems everything is working.
If you have a Content Security Policy (CSP) set up on your website, the following domains should be enabled for the booking engine to function correctly:
*.mews.com
https://pay.datatrans.com/upp/payment/js/secure-fields-1.0.0.js
The last URL (pay.datatrans.com) is for PCI Proxy, which is the secure, PCI-DSS compliant solution that is used by Mews Payments to process payment cards.
After the website has loaded, and the booking engine loader script has prepared the global
Mews.Distributor
object, you can initialize the Booking Engine Widget by calling global Mews.Distributor
with some arguments.Warning: Make sure you initialize the Booking Engine Widget by callingMews.Distributor
only after the website is loaded, otherwise the initialization will fail or will not fully complete. The easiest way to achieve this is to place the initialization code inside a<script>
tag just before the closing</body>
tag, but you can use a different approach if you want.
In the following snippet, replace the placeholder
Your booking engine Configuration ID
with a real Mews Booking Engine Configuration ID from the correct environment. For details of how to obtain your booking engine Configuration ID, see the FAQ.<!-- booking engine's initialization call, it creates a new instance of the booking engine. Use your booking engine Configuration ID. -->
<script>
Mews.Distributor({
configurationIds: [
'Your booking engine Configuration ID',
],
openElements: '.distributor-open',
});
</script>
This call creates an isolated (iframe based) overlay on your website and loads the booking engine into it.
Note: The overlay and booking engine is not visible by default - we're going to solve this in the next section.
To display the booking engine overlay, you should bind its opening to some action, e.g. clicking on a button. The booking engine can set this binding automatically for you, if you provide the second option
openElements
to Mews.Distributor
and prepare the HTML elements which will be binded. You can find more information about openElements
in the Options Reference.The binding is delegated, so the elements and selectors don't need to exist during load of the website, but you still need to add the HTML elements yourself. Knowing that, you can for example add the following HTML button with class
distributor-open
(the class name we've used in the initialization code from the previous section), and it will open the Booking Engine Widget overlay upon a click:<!-- Example of button for opening the booking engine when openElements is set to '.distributor-open' -->
<button class="distributor-open">Book Now</button>
This is just an example, the automatic binding can attach a click event listener to any HTML element.
Note: Closing of the booking engine is provided in the overlay by default, no configuration is needed from your side.
This is all you need for the basic setup of the Mews Booking Engine. Here's a summary of what you've done:
- On the web page with this setup, the loader script will prepare
Mews.Distributor
- After the web page loads, your code will call
Mews.Distributor
- this will initialize the Booking Engine Widget, create an overlay (hidden for now) and bind opening actions to selected HTML elements such as buttons - When users click these HTML elements, the Booking Engine Widget overlay will open, and they can book through it
- Users can close the overlay at any time and see your web page again
This step is optional
If you want to have a more customized setup, or you want to call some Javascript API functions on a booking engine instance to control it, you can provide a callback function as the second argument to the initialization call.
This callback is later called asynchronously with an argument - booking engine instance. By calling methods on this instance you can control the booking engine.
A very common example of this is using custom start and end date selectors that are part of your website and then passing the user’s selection to the booking engine - see Using your own date inputs:
<!-- Example of setting custom dates, useful if you have e.g. your own calendars on your website -->
<script>
Mews.Distributor(
{
configurationIds: [
'Your booking engine Configuration ID'
],
openElements: '.distributor-open',
},
function (api) {
// you can call API functions on a booking engine instance here
// set different start and end date
api.setStartDate(new Date(2022, 1, 1));
api.setEndDate(new Date(2022, 1, 3));
}
);
</script>
Note: To see a list of all available Javascript API functions, please consult the Booking Engine Widget Javascript API reference.
This step is optional
The booking engine can run in two basic modes - single enterprise or multiple enterprise. The mode is chosen automatically during initialization, based on the count of configuration ids you have provided in the options. Whenever two or more hotels are loaded, the booking engine will start in the multi-enterprise mode. That means that it will add one more step to the booking flow - hotel selection. To add more hotels, simply pass their Configuration IDs into the
configurationIds
array option, as follows. For details of how to obtain booking engine Configuration ID, see the FAQ.<script>
Mews.Distributor({
configurationIds: [
'First configuration id',
'Second configuration id',
// and more...
],
});
</script>
Last modified 4mo ago