External Book Now - v2

Summary of Usage and Methods

This page contains a summary of the key parts of the external widget library

Installation

Simply add the following line to the web page head to load the javascript which loads the required resources.

Javascript Public Interface

The widget library will instance a public interface by which the user can configure and interact with the widget. This interface is booxiController, the following methods are available.

configure

This method performs the required initialization which allows the book now widget to work. The details on configuration are described below.

Params:

Object containing an assortment of configuration properties.

Returns:

A dynamic interface object will be returned which will provide the user a series of methods to interact with the initialized widget code. Described in the Dynamic Widget Handler section.

book

This method will launch book now based on the current configuration. This method expects no parameters. Will not work if configure was not already called.

Params:

None

open

This method will launch book now with a specific profile. While this method is meant as an onclick function to be used internally it can called by the user.

Params:

#1 String The profile ID to open

#2 Object Optional Parameter used ro pass special data to the book now session that will be opened. The following object properties are supported :

language (string): This setting will set the language of the book now experience. Supported values are : eng, fre, spa, por, nld, deu.

serviceCategoryId (int): This setting will pre-select the service category matching this id, in the id is invalid no action is taken.

serviceId (int): This setting will pre-select the service matching this id, in the id is invalid no action is taken.

staffId (int): This setting will pre-select the staff matching this id, in the id is invalid no action is taken.

customRequest (string) : This properties is used to assign custom information to a specific booking request. The contents of this field will be appended to the custom request field and on appointment record, viewable from the merchant tool.

clientData (Object) : See Book Now - Pushing Client Data

Configuration Options (booxiController.configure)

All of the supported configuration options are described below

enableConsoleLogging

This system will activate console logs which will display warning and errors in the browser console. This feature is meant to assist the user during the installation process. It is recommended that this feature be disabled once the installation working.

(boolean)

True to enable and false to disable.

apiKey

A valid booxi api_key, this is the primary key. Secondary keys can also be added. The key is validated with the booxi server.

(string)

A 32 character string, ex : 03458r5o2964M92A873w96wHFyJf06py

timeoutDelay

This value allows the user to set an alternate timeout until the js code considers the book now load as failed, at which point the iframe overlay will be closed. Default is 10 Seconds.

(int)

Number respresenting time in MS. (1000 == 1 second)

usePopup

This property controls wheter book now is displayed in an iframe or external popup.

(boolean)

True for external popup and the default is false.

useIframeOnMobile

This property controls whether the booknow is displayed in an iframe or in an external window on mobile devices.

(boolean)

True for open it as an iframe and the default is false.

redirectUriBooked

Defines a page url where client will be navigated on successful booking. May contain extra url parameters such as: refferer_url and booking_data. refferer_url represents the document that loaded the widget. booking_data is base64 encoded json object that contains booking data. See Callback Function Data.

(string)

Must be a valid URL ex: https://www.booxi.com

redirectUriClosed

This parameter is similar to redirectUriBooked but is trigged on user closing the widget. May contain extra url parameters such as: refferer_url and booking_data. refferer_url represents the document that loaded the widget. booking_data is base64 encoded json object that contains booking data. See Callback Function Data.

(string)

Must be a valid URL ex: https://www.booxi.com

gaCode

The user can provide a google analytic id which is instanced by book now as a secondary tracker.

(string)

A valid google analytic tracker id ex: UA-XXXX-Y

onClosed

This is a callback that is called on the closure of book now, also triggered by service unavailable. The callback will be provided an object with details on the close event.

(function)

A data object will be provided as an argument to the callback function. See Callback Function Data

buttonTargetId

This parameter is used to define a DOM Element ID into which a book now button will be created. Once the api_key has been validated.

(string)

The ID value of an existing DOM Element.

useDefaultButton

This option controls the automating creation of a book now button. buttonTargetId must contain a valid element ID.

(boolean)

Default value : true. If true a button will be created in the element container the buttonTargetId. If false no button will be created on load.

localizedButtonText

The property allows the user to define button labels for all of the supported languages. The values will override internal default labels.

(object)

Example value : {eng:'some text', fre:'some text', spa:'some text', por:'some text', nld:'some text', deu:'some text'}

language

The is the default language value used, if not defined the default is english.

(string)

Supported values : eng | fre | spa | por | nld | deu

buttonText

This is a default booking button label that is associated to the default language. This is basically a shortcut to set a custom label.

(string)

showIcon

Global display setting to manage displaying the icon on the book button.

(boolean)

Set true to hide icon, internal default is false.

Callback Function Data

The callback function will received a data object that will contain some information. A brief breakdown down of the response :

bookingSuccessful (boolean) : true if booking was successfully complete, otherwise false.
bookingStatus (string) : A textual status indicator, possible values :
- Booking Success Booking successfully completed, expect bookingSuccessful to be true
- Booking Canceled Booking was termianted prior to completion, expect bookingSuccessful to be false
- Not Available Book Now was not able to complete its loading process, various reasons such as invalid api key.
bookingType (string) : if bookingSuccessful is true then this value will contain the type of booking. Can be appointment, reservation or rental
bookingId (int) : This is the ID that is associated with a successful booking. This value is only set if bookingSuccessful is true. Ex: 1234
apiBookingId (string) : This is the ID of the successful booking that is used in the Booking API. This value is only set if bookingSuccessful is true. Ex: A00001234
eventCalId (int) : ID of a valid group event that is available for booking. Ex: 123456.
staffId (int) : Staff member ID associated with selected an appointment or reservation. Ex: 123456.
serviceId (int) : Service ID associated with selected an appointment or reservation. Ex: 123456.
serviceName (string) : Service name associated with selected an appointment or reservation. Ex: Service 1.
staffFirstname (string) : Staff member first name associated with selected an appointment or reservation. Ex: John.
staffLastname (string) : Staff member last name associated with selected an appointment or reservation. Ex: Doe.
datetime (string) : Appointment date and time in RFC 3339. Ex: 2018-12-18T18:59:16.209Z
attendeeCount (int) : Number of attendees Ex: 3.
serviceCategoryName (string) : Category name. Ex: Category 1.
serviceDuration (int) : Service duration in minutes. Ex: 60.
serviceCurrencyCode (string) : ISO 4217 currency code. Ex: USD.
servicePrice (string) : String representaion of a service price, formatted according to the merchant country and language, with 2 fixed digits. Available after choosing a service. Ex: $10.00 + ($3.00 / person).
totalPrice (string) : Decimal string representaion of a total cost, formatted according to the merchant country and language, with 2 fixed digits. Available after contact information section. Ex: 199.00, 99.99, 1.23, 0.99. 0.00. Total price only available after "Contact Information" step.
totalPay (string) : Decimal string representaion of a total amount to pay online, formatted according to the merchant country and language, with 2 fixed digits. Appears only if online payment is set for the service. Ex: 199.00, 99.99, 1.23, 0.99. 0.00. Total price only available after "Contact Information" step.
productId (string) : If the booking requires a shopping cart payment, the id of the product to include in the shopping cart. Ex: 978-3-16.
paymentId (string) : If the booking requires a shopping cart payment, the id of the payment. Can be used with the Booking API to record the payment collection in booxi. Ex: P000123.
clientData (object) : Client data object.

address (string) : Client's address (not validated). Ex: 1234 Hot Soup str.
city (string) : Client's city (not validated). Ex: Montreal.
country (string) : Client's country (validated). Ex: CA.
pczip (string) : Client's postal code or zip code (validated). Ex: A1AB2B
provState (string) : Client's province or state (validated). Ex: QC.
customRequest (string) : Client's request (not validated). Ex: Extra spicy please.
email (string) : Client's email (validated). Ex: pho@hotsoup.com
firstname (string) : Client's first name (not validated). Ex: Jayne.
lastname (string) : Client's last name (not validated). Ex: Doe.
phone (string) : Client's phone number in E.164 format (validated). Ex: +15141111111.
phoneCC (string) : Client's phone country code (validated). Ex: CA.
emailReminder (boolean) : Client is requesting reminder notification by email. Ex: true, false
smsReminder (boolean) : Client is requesting reminder notification by sms. Ex: true, false

Javascript Dynamic Interface

Called the booxiController configure method will return a sigleton instance of a public handler to the active book now widget code. The Handler will provide the following methods to the user.

addingBookingProfile

This method will allow you to define a custom book button definition. Selections by staff / service can be defined only in custom buttons.

Params:

#1 (string), #2 (object)
#1 Button Profile ID
#2 Button Config (see below)

removeBookingProfile

This method will remove a specific button profile, as well as remove any buttons created through the handler. Removal does not apply to any click events.

Params:

(string) Button Profile ID

openWithBookingProfile

This will launch book now with the settings of a specific button profile.

Params:

(string) Button Profile ID

generateButtonByProfile

This method will generate a book now button based on a specific button profile. The button will be inserted into the html element with the appropriate ID. If the element does not exist the operation is aborted.

Params:

#1 (string), #2 (string)
#1 DOM ID of element where button is created
#2 Button Profile ID

createBookingButton

This method will directly create a book now button without the need of a profile. The same button config options apply and a DOM element with the provided id must exist.

Params:

#1 (string), #2 (object)
#1 DOM ID of element where button is created
#2 Button Config (see below)

Return:

(string) A dynamically generated profile id will be return. Capturing the return value is optional, the value can be used in any method that expects a profile ID as a param.

Button Config Parameters

The dynamic widget handler has several methods which require an object containing properties for a custom button configuration. The config options are described below.

apiKey

A specific api key for this button, allows buttons to open booking for different businesses

(string)

language

The language setting, will apply the lang specific label. Also sets the lang of book now

(string)

Valid values are (eng | fre | spa | por | nld | deu)

serviceCategoryId

(int)

Must be the booxi service category ID of the selected service, if invalid book now will ignore the value.

serviceId

(int)

Must be the booxi service ID of the selected service, if invalid book now will ignore the value.

staffId

(int)

Must be the booxi staff ID of the selected service, if invalid book now will ignore the value.

eventCalId

(int)

Must be the id of a valid group event that is available for booking.

attendeeCount

(int)

Must be a number between 1 and 10, the value is only used in combination with eventCalId and will preset the number of attendees. Invalid values and values out of renage are ignored.

buttonText

This value will be set as the button label.

(string)

showIcon

This value will hide or display the icon. The setting will override the configuration level hide icon setting.

(boolean)

Set to true to hide, and false to display.

bookingFlow

This value will activate the merchant location selection flow.

(string)

Set to "locations" to activate the flow.

locationTags

Filter merchants for booking flow "locations" by tag or tags (comma separated values i.e tag1,tag2,tag3).

(string)

tag1,tag2,tag3

serviceTags

Filter which services that will be available using the service tags.

(string)

One or more tags separated by comma(,) or pipe(|)

tag1: only list service that contains tag1
tag1,tag2: use comma(,) to list services that contains multiple tags (tag1 AND tag2)
tag1|tag2: use pipe(|) to list services that contains eat least one of the given tags (tag1 OR tag2)
tag1,tag2|tag3: both separators can be used at once ((tag1 AND tag 2) OR (tag3))

eventDate

This value will filter envets by specific date for the merchant location selection flow.

(string)

Date format: yyyy-mm-dd

primaryColor

Will set primary widget color.

(string)

A hexadecimal value: #RRGGBB, ie #44CE5E.

secondaryColor

Will set secondary widget color.

(string)

A hexadecimal value: #RRGGBB, ie #33BCF2