Skip to main content

Integration

Touch points​

There are different ways where the integration between a partner's website and the WhiteLabel product can happen, each one with its own benefits and perks.

It is fundamental to identify the correct list of touch points and their placement to obtain the most seamless user experience and maximize the conversion. We offer a diversity of touch points that the partner can choose to utilize and customize.

The desired touch points shall be communicated upon starting the development phase.

HomePage (Search Bar) integration​

Search_bar_screenshot

If your website already offers the possibility of searching for other products (i.e. flight tickets or car rentals), it is possible to integrate the Search Bar with accommodation deals too. Vio.com can also provide guidance and recommendations for building a custom Search Bar, for the purpose of directing the users for a search on the WhiteLabel.

A Search Bar widget will also soon be available.

The mandatory parameters that need to be searched for are number of guests and an area definition (e.g. a single hotel, a city, a region or a country), while check-in and check-out dates are not mandatory (default dates will be applied) but strongly recommended, in order to show more relevant offers. There are other optional parameters (e.g. language, currency and userCountry) that can be added to refine the search, at Partner's discretion. we always recommend sending all the parameters, whenever possible, to increment the relevancy for the users and maximize the conversion rate.

There are two possible solutions for integrating a Search Bar:

  • Dynamic, through our Partners API (recommended)
  • Static, generating a DeepLink

We strongly recommend to integrate our Partners API for a better experience and to avoid place mapping issues between Vio.com and Partner's area definitions.

Detailed documentation for integrating our Partners API is available here. A point of contact in Vio.com will assist the Partner throughout the integration process.

The static generation of DeepLinks is covered in a separate section below.

Widgets​

Widgets are a powerful way to integrate and guide the flow between the Partner's website and the White Label; they can show the best deals for a selected hotel, a list of hotels or a specified city, region or country, thus focusing either on a single structure or rather an area/list.

Widgets can be customized in what they show: you have the power to define the outcome with parameters such as check-in and check-out dates, currency, language and room configuration.

The process of integrating a widget in a Partner's website is as easy as copy-pasting; we provide an automatic code snippet generator where the Partner can build their own widget, with their preferred parameters and copy-paste the output HTML directly in their platform.

Example:

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

We offer different types of widgets, based on the content that need to be shown:

Widgets can be virtually integrated anywhere on the Partner's website (given that the mandatory parameters are properly set), but there are some places that are more recommended to increase their visibility and effectiveness.

Some examples are:

  • Booking confirmation page: imagine a user has just completed the checkout for a flight from Seattle to Toronto, it would probably effective to present the user with a list of accommodations in Toronto during the same period.
  • Search Results page: as for the above, if a user is searching/planning to move to a different place for a period of time or if their examining a hotel, it would be fruitful to present the best deals for the place for the specified period of time.
  • Blog posts: it is usually effective to present the user with the best deals for a specified place (e.g. a city) on a blog post that talks about the city beauties or the great food you can find in that city.

To integrate a widget you can follow this 3-steps guide:

  1. Generate the desired type of widget with the detailed instruction on our Developers Guide. Remember to include (at least) the mandatory parameters.
  2. Copy and paste the widget HTML in your website, where you see it fitting the best, changing the API key to fit the one provided by Vio.com to you. Your branding will be applied automatically, based on the API key used.
  3. Test the widget appearance: is it showing what you expect? Does it need different parameters? If so, you can check the parameters on the Developers Guide.

Back-Tab integration​

A very convenient way to suggest accommodation deals is to show them when a user triggers a search for another product (e.g. flights or concert tickets). The original search will be opened in a new tab, while on the previous tab another search for accommodations will be automatically triggered on the WhiteLabel website or on Vio.com directly.

While not being disruptive to the user flow, it offers the possibility for the user to be presented automatically with the best deals for accommodation during their trip or event stay, generating some extra conversion.

The Back-Tab integration process is also very simple, as simple as generating a URL; more details can be found in the next section: DeepLinks.

A DeepLink is simply a URL pointing to the WhiteLabel with some defined parameter. DeepLinks can be a very powerful tool, as they allow to reach the WhiteLabel from any point in time, at any level of the user experience flow, and can be integrated anywhere (e.g. a custom banner, a classic HREF link, a more complex widget and so on).

In order to generate a DeepLink, some mandatory parameters are necessary (tracking label, check-in and check-out dates, number of guests and area definition) but some others are optional and allow for better refinement of the Search Result Page (e.g. language, currency and room configuration). To present users with the best offer plateau, our recommendation is to use the maximum amount of parameters, including the optional ones, whenever possible.

An example of a generated URL for a simple search in Amsterdam for 2 nights and (2 guests, 1 room):

https://example.com/Hotel/Search?label=HomepageClickTracking&placeId=47319&checkIn=2025-01-28&checkOut=2025-01-30&rooms=2&curr=EUR&forceCurrencyChange=1&lang=EN&forceLanguageChange=1

Another example of a generated URL for a specific hotel search for 3 nights and (3 guests, 2 rooms):

https://example.com/Hotel/Search?label=HomepageClickTracking&hotelId=1263313&checkIn=2025-01-28&checkOut=2025-01-31&rooms=2%7C1&curr=USD&language=de&forceLanguageChange=1&forceCurrencyChange=1

If the URL is malformed (i.e., missing mandatory parameters or providing a nonexistent Hotel ID), the link will redirect to the homepage. Our team can regularly analyze redirect errors to optimize the user experience and conversion.

Although some parameters are optional (e.g. language, currency and room configuration), we recommend to use them every time possible, to increase the offer accuracy and maximize the conversion.

Hotel or Place ID parameter​

To create a deeplink to the Search Results Page on the Whitelabel, matching the location (or hotel) searched by the customer on the Partner's website, you will first need to get the Place or Hotel ID of that entity at Vio.com.

The easiest way to get the Place or Hotel ID is to use the Vio.com Partners API, as detailed in the next section. With the API you will be able to search for a location or hotel by name, and get the corresponding ID, which you can then use in the deeplink.

Alternatively, we can also investigate the possibility of mapping your hotel or location data to our database and share the direct mappings with you in advance, so that you can have the IDs ready at hand. If you prefer this route, please let your Vio.com team representative know so that we can investigate the possibility.

Label parameter​

You can add a label parameter to the URL to track any information that is relevant to your use case. The information added to the label will be available in the data reports you will receive, allowing you to properly segment user traffic and optimize your usage.

A label is a URL encoded string, and can contain multiple values. Example:

  • To add a simple string like foobar: label=foobar
  • To add a variable like userId=123: label=userId%3D123
  • To add multiple variables, like userId=123&hotelId=456: label=userId%3D123%26hotelId%3D456

Given the last example, a final URL would look like this:

https://example.com/Hotel/Search?label=userId%3D123%26hotelId%3D456&placeId=47319&checkIn=2025-01-28&checkOut=2025-01-30&rooms=2&curr=EUR&forceCurrencyChange=1&lang=EN&forceLanguageChange=1

If you need recommendations or guidance on how to use the tracking label parameter you can ask your Vio.com team representative.

Language and currency​

It is possible to land on the White Label forcing a specific language and/or currency, by simply adding some parameters to the URL:

  • To force a specific language, add the parameters lang=LANGUAGE&forceLanguageChange=1
  • To force a specific currency, add the parameters curr=CURRENCY&forceCurrencyChange=1

Example:

https://hotels.example.com/?lang=es&forceLanguageChange=1&curr=EUR&forceCurrencyChange=1

For the list of supported languages and currencies, you can consult the Dictionaries page.

Vio.com Partners API​

In the context of WhiteLabel, the Vio.com Partners API makes it possible to unlock the full potential of the Search feature and enable more refined and precise Search Results.

The APIs are especially recommended when integrating a search bar or generating deeplinks to seamlessly map the property/location IDs in our database and avoid manual mapping procedures.

Example of Vio.com /suggest API in action:

suggest_api_animation

To make use of the Partners API, you can request an API key from our Partnership Team. The detailed documentation for the Partners API integration is available on the Developers Documentation.