Multi Hotels Carousel Widget with optional Banner
Description
The Multi Hotels Carousel (MHC) widget is a carousel feature that displays multiple hotel options to users. It retrieves data from an API by searching for hotels based on location, city, country and hotel names and hotel ids parameters passed through the URL. This widget is designed to assist users in finding the best hotel deals, especially when they are engaged with content provided by our affiliate partners. Optionally, a marketing banner can be added to the top of the widget.
Use Case
The MHC widget enables users to effortlessly explore a wide range of hotels that match their desired location. With customization options, seamless API integration, and a user-friendly booking process, the MHC widget ensures a convenient and enjoyable experience, ultimately driving hotel bookings and customer satisfaction.
The widget acts as an entry point to the white label website. It is used to display the best deals from a specific place and to explore hotel deals. Interacting with the widget will redirect the user to the white label website where they can complete the booking process.
Adding the Widget to Your Website
It can be added to your page by embedding it with an iframe. Use query params as explained below to configure the widget correctly. Query params must be url encoded.
Embed Code
<script src="https://partners.vio.com/js/set-iframe-height/setIframeHeight.min.js"/>
<iframe
src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles"
width="100%"
frameborder="0"
></iframe>
Note: <script> tag can be added nearby <iframe> tag or in the <head> section of your page.
Parameters
| Name | Required | Description | Example | Default |
|---|---|---|---|---|
partnerKey | Yes | Public key used to embed the widget in client-side applications. Request it from your Account Manager | ||
placeId | Yes* | Search hotels based on the place id | 123 | |
placeName | Yes* | Search hotels based on the place name | Los+Angeles | |
hotelIds | Yes* | Hotel ids. For MHC Widget, multiple hotel ids are supported | 123,321,231 | |
hotelIdsProvider | No | Used to specify the source of the list of Hotel IDs provided in the hotelIds parameter, which affiliate it should be mapped from (Expedia -> EXP, etc). | EXP | VIO |
hotelNames | Yes* | Hotel names. For MHC Widget, multiple hotel names are supported | Beverly+Wilshire+A+Four+Seasons+Hotel,Casa+Camper+Barcelona,Park+Plaza+London | |
iataCode | Yes* | Search hotels based on the airport IATA code | LCY | |
country | No | Search for hotels only in this country if using placeName or hotelNames in search. See countries | United+States | |
checkIn | No** | Check-In Date | 2024-01-20 | |
checkOut | No** | Check-Out Date | 2024-01-21 | |
currency | No | Currency used to display prices. See supported currencies | EUR | USD*** |
language | No | Widget language. See supported languages | es | en*** |
userDevice | No | The type of the user's device: desktop,mobile,tablet. If not specified then API determines it based on the caller's User-Agent header. | "desktop" | |
userCountry | No | The 2-char ISO 3166 country code of a user. If not specified then API determines it based on the caller's IP address. | "US" | |
rooms | No | Room configuration. See Rooms configuration | 1 | 2 |
label | No | Arbitrary string for tracking and reporting | VioWidgetLabel | |
hideDividers | No | Hides dividers and reduces widget height to 508px if "true" | true | |
title | No | Custom widget title (should be url-enconded string) | Los%20Angeles | |
features | No | List of enabled features divided by comma: allDeals, results, banner, dividers. To disable all features pass empty string. | banner,dividers | allDeals,results,banner |
* You should provide at least one of the placeId, placeName, iataCode, hotelIds or hotellNames to trigger the
hotels search. If all parameters are provided, the search will be based on placeId. If only hotelIds is used, you can also provide hotelIdsProvider (has VIO value by default).
** Dates with availability will be selected automatically. To force search by accurate dates you should provide both check-in and check-out dates. Dates should be in the future and gap between check-in and check-out should be more or equal to one day and less or equal to 31 days.
*** Widget will detect this parameter automatically or apply default value
CSP Policy
If you are using Content Security Policy on your website, make sure that iframe url is whitelisted with frame-src
directive:
frame-src https://partners.vio.com
Widget Message Posting
Our widgets utilize the native Post Message API to communicate with the parent page. Below are the supported events that trigger a message to the parent.
No Offers Available on First Search
If the user has not interacted with the search box and the initial search returns no results, the widget sends the following message:
"landingSearchSoldOut"
This message is typically used to:
- Hide the widget to prevent a poor user experience.
- Adjust the search parameters to a broader scope.
Example script for intercepting the posted messages
// Listen for messages from the specific iframe
window.addEventListener("message", (event) => {
if (event.origin !== "https://partners.vio.com") {
console.warn("Blocked message from unexpected origin:", event.origin);
return;
}
// Hide the widget, or change the params of the src attribute in the iFrame to broaden the search
console.log(">>> Received message from iframe:", event.data); // This can be removed, as it's only made for testing that the message is received
});
Live Examples
Search by place name
<script src="https://partners.vio.com/js/set-iframe-height/setIframeHeight.min.js"/>
<iframe
src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles"
width="100%"
frameborder="0"
></iframe>
Search by place id
<script src="https://partners.vio.com/js/set-iframe-height/setIframeHeight.min.js"/>
<iframe
src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeId=515497"
width="100%"
frameborder="0"
></iframe>
Search by IATA code
<script src="https://partners.vio.com/js/set-iframe-height/setIframeHeight.min.js"/>
<iframe
src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&iataCode=LCY"
width="100%"
frameborder="0"
></iframe>
Enabling marketing banner on top
<script src="https://partners.vio.com/js/set-iframe-height/setIframeHeight.min.js"/>
<iframe
src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles&features=banner"
width="100%"
frameborder="0"
></iframe>
Optimizations
You can enable widget iframe lazy loading by adding loading="lazy" attribute to widget iframe HTML tag. See more
detailed explanation on MDN website.
<script src="https://partners.vio.com/js/set-iframe-height/setIframeHeight.min.js"/>
<iframe
loading="lazy"
src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles"
width="100%"
frameborder="0"
></iframe>