Booking Widget

Accommodation: Testhotel Webseitentool HGV (hotelhgv.it) (9002)

Installation

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

<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", function() {
        BookingSüdtirol.Widgets.Booking("#Bs-BookingWidget", {
            accommodationId: 9002,
            lang: 'de',
            onBookingSuccess: function(reservation) {
                // Called after successful booking
            },
            onEnquirySuccess: function(reservation) {
                // Called after successful enquiry
            }
        });
    });
</script>

Please note: Do not include the script in a bundle or host a copy of it yourself.


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.

  • accommodationId
  • 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.URL.com/?lang=it&arrival=2021-02-20&departure=2021-02-23&guests=[[18,18],[18,4]]

API

accommodationId: number

ID of the accommodation

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

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

Please note: 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)
  • 4-steps
  • compact

defaultOfferList: string?

Determines which offer list is displayed by default.

  • rooms (default)
  • specials (If no specials are available, it automatically fallbacks to rooms)

offerId: number?

Enables you to display a specific special via its ID.

ID Special name
1942598 Nicht ohne meinen besten Freund
1942603 Weiße Wochen
3125446 Weihnachtszauber in Südtirols Süden

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.

ID Room name
25722 Einbettzimmer
25723 Doppelzimmer Deluxe
25724 Doppelzimmer
25725 Dreibettzimmer

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 campaign offer the possibility to submit the fields individually.

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

Please note: 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 accommodations. 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;
    guests: number[][];
}

onBookingSuccess: (reservation: object)? => void

Function called after successful booking.

onBookingError: (reservation: object)? => void

Function called after failed booking.

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

Deprecated. Use onEnquirySuccess instead.

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

Function called after successful enquiry.

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

Reservation structure

{
    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
    }[];
    // Guest data
    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;
        company: {
            name: string;
            taxnumber: string;
            street: 'string;
            city: string;
            zipcode: string;
            country: string; // ISO 3166-1
        }
    }
}

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: function() {
        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 2021-02-04
departure Departure Date 2021-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_2021
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

Google Universal Analytics (deprecated)

event eventCategory eventAction eventLabel eventValue
BsWidgetEvent HGV-Buchungswidget Zimmerbelegung hinzugefügt
BsWidgetEvent HGV-Buchungswidget Zimmerbelegung entfernt
BsWidgetEvent HGV-Buchungswidget Erwachsene ausgewählt Number of selected adults
BsWidgetEvent HGV-Buchungswidget Kinder ausgewählt Number of selected children
BsWidgetEvent HGV-Buchungswidget Monat im Kalender geändert Year and month i.e. 2020-06
BsWidgetEvent HGV-Buchungswidget Reisedaten ausgewählt Travel dates i.e. 2020-06-14 bis 2020-06-18
BsWidgetEvent HGV-Buchungswidget Weiter zu Anfrage
BsWidgetEvent HGV-Buchungswidget Angebotsliste gewechselt rooms, specials
BsWidgetEvent HGV-Buchungswidget Verfügbarkeit geprüft
BsWidgetEvent HGV-Buchungswidget Angebot ausgewählt Offer name Offer ID
BsWidgetEvent HGV-Buchungswidget Zimmer ausgewählt Room name Room ID
BsWidgetEvent HGV-Buchungswidget Verpflegung ausgewählt Board Board ID
BsWidgetEvent HGV-Buchungswidget Zimmerdetails geöffnet Room name Room ID
BsWidgetEvent HGV-Buchungswidget Angebotsdetails geöffnet Offer name Offer ID
BsWidgetEvent HGV-Buchungswidget Bildergalerie geöffnet
BsWidgetEvent HGV-Buchungswidget Zusatzleistung hinzugefügt Name of additional service Number of additional services
BsWidgetEvent HGV-Buchungswidget Schritt "Reisedaten" geöffnet
BsWidgetEvent HGV-Buchungswidget Schritt "Angebotsliste" für 1. Belegung geöffnet
BsWidgetEvent HGV-Buchungswidget Schritt "Angebotsliste" für 2. Belegung geöffnet
BsWidgetEvent HGV-Buchungswidget Schritt "Angebotsliste" für 3. Belegung geöffnet
BsWidgetEvent HGV-Buchungswidget Schritt "Persönliche Daten" geöffnet
BsWidgetEvent HGV-Buchungswidget Schritt "Zusammenfassung" geöffnet
BsWidgetEvent HGV-Buchungswidget Buchung erfolgreich Language ID Total price
BsWidgetEvent HGV-Buchungswidget Buchung fehlgeschlagen Language ID Total price
BsWidgetEvent HGV-Buchungswidget Anfrage erfolgreich Language ID