Booking Widget

Loading property data …

Installation

Create a widget instance by embedding the following code within your webpage inside the <body> element:

<div id="Bs-BookingWidget"></div>
<script
id="booking-suedtirol-js"
src="https://widget.bookingsuedtirol.com/v2/bundle.js"
defer
></script>
<script>
document
  .querySelector("#booking-suedtirol-js")
  .addEventListener("load", () => {
    BookingSüdtirol.Widgets.Booking("#Bs-BookingWidget", {
      id: undefined,
      propertyId: undefined,
      lang: "de",
      privacyURL: "/path/to/privacy/page",
      termsURL: "/path/to/terms/page",
      onBookingSuccess: (reservation) => {
        // Called after successful booking
      },
      onEnquirySuccess: (reservation) => {
        // Called after successful enquiry
      },
    });
  });
</script>

warning

Include the <script … src="https://example.com/v2/bundle.js" …></script> element exactly as specified. Do not self-host a copy of the script and do not include its code into a JavaScript bundle file. Otherwise the widget will not work correctly.

Configuration

Use BookingSüdtirol.Widgets.Booking(domElement, settings) to create new widget instances.

Method arguments

`domElement`: string | DOM element

The CSS selector or DOM element where your widget will be mounted.

`settings`: object

Initialization options. See API below. Each widget instance can have it's own settings.

URL parameters

The following list of settings can also be passed over the URL.

propertyId
lang
arrival
departure
currentMonth
layout
guests
defaultOfferList
offerId
roomId
utm_medium
utm_source
utm_campaign

Notice that URL parameters always overwrite widget instance settings.

// Example
https://www.example.com/?lang=it&arrival=2022-02-20&departure=2022-02-23&guests=[[18,18],[18,4]]

API

`id`: string

The widget ID

info

Mandatory field

`propertyId`: number

ID of the property/accommodation

info

Mandatory field. The property must already have been activated for the widget.

`accommodationId`: number

Deprecated. Use propertyId instead.

`privacyURL`: string

Defines the URL to the privacy policy page of the website where the widget is embedded. The language used on the page must match the lang field.

Examples:

/en/privacy
https://example.com/en/privacy

info

Mandatory field

`termsURL`: string

Defines the URL to the general terms and conditions page of the website where the widget is embedded. The language used on the page must match the lang field.

Examples:

/en/terms
https://example.com/en/terms

info

Mandatory field

`lang`: string?

Language

de: German (default)
it: Italian
en: English
fr: French

`arrival`: string?

Defines the arrival date in ISO 8601 format (yyyy-MM-dd)

2020-02-20

`departure`: string?

Defines the departure date in ISO 8601 format (yyyy-MM-dd)

2020-02-23

`currentMonth`: string?

Defines the displayed calendar month in ISO 8601 format (yyyy-MM-dd)

2020-04-01

`guests`: number[][]?

Determines the number of rooms and their occupancy in the form of the age of each person.

18: adult
0-17: child

// Examples

// room 1: 2 adults
[[18, 18]];

// room 1: 2 adults, 2 children (14 - and 5 years)
[[18, 18, 14, 5]];

// room 1: 2 adults
// room 2: 1 adult, 1 child (4 years)
[
  [18, 18],
  [18, 4],
];

// room 1: 2 adults
// room 2: 1 adult
// room 3: 2 adults, 1 child (3 years)
[[18, 18], [18], [18, 18, 3]];

// Produces error because no adults were submitted
[[12]];

// Produces error because more than three rooms were submitted
[[18], [18, 14], [18], [18]];

Default value: 2 adults [[18,18]]

info

You can add a maximum of three rooms.

`occupations`: number[][]?

Deprecated. Use guests instead.

`layout`: string?

Determines the layout of the extended widget

one_pager (default)
four_steps
compact

`defaultOfferList`: string?

Determines which offer list is displayed by default.

rooms (default)
specials (If no specials are available, it automatically falls back to rooms.)

`offerId`: number?

Enables you to display a specific special via its ID.

Loading specials …

`roomId`: number?

Enables you to display a specific room via its ID. The ID can be read either via the MSS interface or the following chart.

Loading rooms …

`promotion`: [string | null, string | null, string | null]?

Enables you to customize the advertising fields medium (ResID_SourceContext), source (ResID_Source) und campaign (ResID_Value) and submit them to the PMS.

How exactly the fields are to be filled has been precisely defined in the AlpineBits Standard and can be read in the corresponding documentation in section 4.2.5 Implementation tips and best practice.

["Advertising medium", "Advertising source", "Advertising campaign"];

Default value: [null, null, null]

ASA promotion fields

The Google Analytics parameters utm_medium, utm_source, and utm_campaign offer the possibility to submit the fields individually.

For example, the URL https://www.example.com/?utm_medium=metasearch&utm_source=tripadvisor.com&utm_campaign=tripadvisor_desktop would submit ['metasearch', 'tripadvisor.com', 'tripadvisor_desktop'] to the PMS.

info

Using this feature will set a 30-day tracking cookie. In this case, add the cookie bs_widget_promotion to your Privacy Policy. If you want to prevent the cookie from being set, insert the code window.BookingSüdtirolTrackingConsent = false; before the widget is loaded.

`source`: string?

Enables the widget to be installed on portals with multiple properties. For this functionality, please contact support directly.

`onOccupanciesChange`: (guests: number[][])? => void

Function called after guest occupancies were changed / added / removed.

`onStaySelection`: (stay: object)? => void

Function called after a stay was selected in the calendar.

{
    arrival: string; // ISO 8601
    departure: string; // ISO 8601
    isValid: boolean; // Is selected stay bookable
    guests: number[][];
}

`onBookingSuccess`: (reservation: object)? => void

Function called after successful booking.

`onBookingError?: Function`

Function called after failed booking.

type OnBookingError = (
  reservation: Reservation,
  error: { code: number; message: string },
) => void;

`onRequestSuccess`: (reservation: object)? => void?

Deprecated. Use onEnquirySuccess instead.

`onEnquirySuccess`: (reservation: object)? => void?

Function called after successful enquiry.

info

onEnquirySuccess uses the same reservation object as onBookingSuccess, with the exception that price information and detailed offer infos can be missing.

Reservation structure

interface Reservation {
  bookingId: number;
  arrival: string; // ISO 8601
  departure: string; // ISO 8601
  nights: number;
  price: number | null;
  offers: {
    id: number;
    title: string | undefined;
    price: number | null;
    service: 0 | 1 | 2 | 3 | 4 | 5;
    room: {
      id: number;
      title: string | undefined;
      code: string | undefined;
      roomSeq: 1 | 2 | 3;
      roomType: 1 | 2 | undefined;
      adults: number[];
      children: number[];
    };
  }[];
  extras: {
    id: number;
    title: string;
    amount: number;
    price: number; // price per additional service
  }[];
  property: {
    id: number;
    name: string;
  };
  guest: {
    gender: "" | "m" | "f";
    firstname: string;
    lastname: string;
    email: string;
    phone: string;
    street: string;
    city: string;
    zipcode: string;
    country: string; // ISO 3166-1
    note: string;
    payment: {
      invoice: boolean;
      method: 1 | 2 | 4 | 8 | 16 | 32 | 256 | 512 | undefined;
    };
    company: {
      name: string;
      taxnumber: string;
      street: string;
      city: string;
      zipcode: string;
      country: string; // ISO 3166-1
    };
  };
  /** @deprecated use property instead */
  accommodation: {
    id: number;
    name: string;
  };
}

Example with Google Adwords

The example shows the tracking of a booking with Google Adwords.

${CONVERSION_ID} and ${CONVERSION_LABEL} are placeholders.

BookingSüdtirol.Widgets.Booking("#Bs-BookingWidget", {
  // ...
  onBookingSuccess: () => {
    var img = document.createElement("img");
    img.setAttribute(
      "src",
      "//www.googleadservices.com/pagead/conversion/${CONVERSION_ID}/?label=${CONVERSION_LABEL}&amp;guid=ON&amp;script=0",
    );
    img.setAttribute("alt", "");
    img.setAttribute("height", 1);
    img.setAttribute("width", 1);
    img.style.borderStyle = "none";
    document.body.appendChild(img);
  },
});

Events

As the user interacts with the widget, events are generated in the background for the following interactions:

Google Analytics 4

`search`

The user selects travel dates in the calendar.

Parameter	Description	Value
search_term	Hardcoded search term	`Search booking availability`
arrival	Arrival Date	`2022-02-04`
departure	Departure Date	`2022-02-11`
affiliation	Widget type	`HGV Booking Widget`

`view_item`

Available rooms and additional services are shown to the user.

Parameter	Description	Value
items.item_list_id	Rateplan ID	`49143`
items.list_name	Rateplan title	`Zimmer Preise`
items.item_id	Room ID	`25723`
items.item_name	Room title	`Doppelzimmer Deluxe`
items.quantity	Selected items	`0`
affiliation	Widget type	`HGV Booking Widget`

`view_items`

The user views the room list of a specific offer.

Parameter	Description	Value
items.*	See `view_item` event
affiliation	Widget type	`HGV Booking Widget`

`select_item`

The user opens a rateplan for a specific room.

Parameter	Description	Value
items.*	See `view_item` event
affiliation	Widget type	`HGV Booking Widget`

`add_to_cart`

The user adds rooms or additional services to the cart.

Parameter	Description	Value
items.item_list_id	Rateplan ID	`49143`
items.list_name	Rateplan title	`Zimmer Preise`
items.item_id	Room ID	`25723`
items.item_name	Room title	`Doppelzimmer Deluxe`
items.quantity	Selected items	`1`
items.adults	Number of adults	`2`
items.children	Number of children	`0`
items.price	Price without discount	`550`
items.discount	Discount value	`170`
items.currency		`EUR`
items.category		`Rooms`
items.item_variant	Board ID	`2`
currency		`EUR`
affiliation	Widget type	`HGV Booking Widget`

`remove_from_cart`

The user removes rooms or additional services from the cart.

Parameter	Description	Value
items.*	See `add_to_cart` event
currency		`EUR`
affiliation	Widget type	`HGV Booking Widget`

`begin_checkout`

The user starts to enter his personal informations.

Parameter	Description	Value
items.*	See `add_to_cart` event
currency		`EUR`
affiliation	Widget type	`HGV Booking Widget`

`add_payment_info`

The user adds payment informations.

Parameter	Description	Value
payment_type	Payment method ID	`2`
items.*	See `add_to_cart` event
currency		`EUR`
affiliation	Widget type	`HGV Booking Widget`

`purchase`

The user completes a purchase.

Parameter	Description	Value
value	Reservation price	`380`
transaction_id	Unique reservation ID	`1234567`
coupon	Coupon title	`WINTER_2022`
items.*	See `add_to_cart` event
currency		`EUR`
affiliation	Widget type	`HGV Booking Widget`

`generate_lead`

The user completes an enquiry.

Parameter	Description	Value
transaction_id	Unique reservation ID	`1234567`
affiliation	Widget type	`HGV Booking Widget`

Installation​

Configuration​

Method arguments​

domElement: string | DOM element​

settings: object​

URL parameters​

API​

id: string​

propertyId: number​

accommodationId: number​

privacyURL: string​

termsURL: string​

lang: string?​

arrival: string?​

departure: string?​

currentMonth: string?​

guests: number[][]?​

occupations: number[][]?​

layout: string?​

defaultOfferList: string?​

offerId: number?​

roomId: number?​

promotion: [string | null, string | null, string | null]?​

source: string?​

onOccupanciesChange: (guests: number[][])? => void​

onStaySelection: (stay: object)? => void​

onBookingSuccess: (reservation: object)? => void​

onBookingError?: Function​

onRequestSuccess: (reservation: object)? => void?​

onEnquirySuccess: (reservation: object)? => void?​

Reservation structure​

Example with Google Adwords​

Events​

Google Analytics 4​

search​

view_item​

view_items​

select_item​

add_to_cart​

remove_from_cart​

begin_checkout​

add_payment_info​

purchase​

generate_lead​

Installation

Configuration

Method arguments

`domElement`: string | DOM element

`settings`: object

URL parameters

API

`id`: string

`propertyId`: number

`accommodationId`: number

`privacyURL`: string

`termsURL`: string

`lang`: string?

`arrival`: string?

`departure`: string?

`currentMonth`: string?

`guests`: number[][]?

`occupations`: number[][]?

`layout`: string?

`defaultOfferList`: string?

`offerId`: number?

`roomId`: number?

`promotion`: [string | null, string | null, string | null]?

`source`: string?

`onOccupanciesChange`: (guests: number[][])? => void

`onStaySelection`: (stay: object)? => void

`onBookingSuccess`: (reservation: object)? => void

`onBookingError?: Function`

`onRequestSuccess`: (reservation: object)? => void?

`onEnquirySuccess`: (reservation: object)? => void?

Reservation structure

Example with Google Adwords

Events

Google Analytics 4

`search`

`view_item`

`view_items`

`select_item`

`add_to_cart`

`remove_from_cart`

`begin_checkout`

`add_payment_info`

`purchase`

`generate_lead`