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.

Note: for widget with banner the iframe must be set to a height of 713px to display the widget correctly.

Embed Code

<iframe
    src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles"
    width="100%"
    height="606px"
    frameborder="0"
></iframe>

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
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***
rooms	No	Room configuration. See Rooms configuration	1	2
hideDividers	No	Hides dividers and reduces widget height to 508px if "true"	true
label	No	Arbitrary string for tracking and reporting	VioWidgetLabel
title	No	Custom widget title (should be url-enconded string)	Los%20Angeles
withBanner	No	Determines if widget must include the banner on top	true	false

* 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.

** 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

<iframe
    src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles"
    width="100%"
    height="606px"
    frameborder="0"
></iframe>

Search by place id

<iframe
    src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeId=515497"
    width="100%"
    height="606px"
    frameborder="0"
></iframe>

Search by IATA code

<iframe
    src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&iataCode=LCY"
    width="100%"
    height="606px"
    frameborder="0"
></iframe>

Enabling marketing banner on top

<iframe
    src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles&withBanner=true"
    width="100%"
    height="713px"
    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.

<iframe
    loading="lazy"
    src="https://partners.vio.com/widgets/multipleHotelsWidget/index.html?partnerKey={PARTNER_KEY}&placeName=Los+Angeles"
    width="100%"
    height="606px"
    frameborder="0"
></iframe>