Before you get started on your integration of the Bookit Technology it is important that you read and understand the below elements of the integration. Please also see our FAQs for more information.

Please ensure that you have obtained a clear project brief before you start the integration. We also recommend that you organise a meeting with us to discuss your project plan, to ensure you have not missed any key steps.

If you have any questions, or need further information not contained in this document, please ensure that you email support@bookit.co.nz

Bookit is a database of bookable inventory for the New Zealand tourism industry.

In order for destinations to be able to book local and national operators the operator has a ‘Bookit Member Console’ where they load rates/availability and content. This content is displayed internally to the destination via their ‘Bookit Staff Console’ and via the destination website, where you will be tasked with integrating the technology.

The main aspects of the Bookit Technology that you will need to understand are:

Booking Centre
The booking centre is the source of all the data. Each centre has a unique identifier that is used in various places. The identifier is usually displayed in the source code as q=XXXX EG ‘q=1234’ and is referred to as the VCID.
The Booking Centre also creates all of the configuration for operators, including: categories, operator category, business types, locations, facilities.

Operators
Operator consoles are created by the Booking Centre and the operator is assigned various configurations such as: operator category, business types, locations etc; this then allows a web developer to display them on the website effectively.

Operators are also responsible for loading their bookable product into Bookit to display via the gadgets. The operator console is also where they load images/descriptions. Each operator in Bookit contains a unique property ID which is important throughout the integration.

Bookit also have 5 main bookable operator types. Accommodation, Tours, Car Hire, Packages, and Tickets (AKA Events).

If operators are not mapped to one of these types then that type will not require the gadget integration built into the operator page, as they are a non-bookable operator.

Events
When referring to 'events' we are referring to a simple 'Whats On' event list. These often include events such as markets or community events and are not bookable.

You will need the following credentials before starting the integration:

• VCID
• Gadget and API keys (received after the client has submitted the items below)
• Test operators (Accommodation, Tours, Events, Car Hire)
• Ensure the Bookit Console configuration has been completed

The client must have also submitted the following:

• Initial Key Agreement form
• Gadget Supply Agreement
• Required staging and local domains

To obtain this information please contact Bookit via email: support@bookit.co.nz
Please also ensure all documentation has been fully read through and understood.

The gadgets are simply front end javascript widgets, which communicate to the Bookit system to display rates/availability for consumers to book.

There are 5 required gadgets to integrate; integrated in the following process flow: Search Gadget > Region Gadget > Item Details Gadget > Cart Gadget > Booking Gadget > Confirmation Gadget.

The Search Gadget
This gadget is integrated on the homepage of your website. This is the main call to action on the homepage of the website so we recommend that it be added within the first fold to encourage bookings. You can see a great example of a Search Gadget in action at https://book.isite.nz/

The documentation for the Search Gadget is found here.

The Region Gadget
The Region Gadget displays a list of properties produced by a search. This includes one type of product grouped together. For example, Accommodation, Tours, Car Hire, or Events.

You can find an example of a Region Gadget here or a custom Region Gadget here (please note that we cannot assist with custom integrations).

Parameters can also be set in the JavaScript code that interacts with this gadget. This can include things such as: the default sort order, types to display, number of nights, and number of pax.

The Gadget documentation for the Region Gadget can be found here.

The Item Detail Gadget
The Item Details Gadget is integrated within the operator pages and shows an operator’s Bookable product. If the operator is not of a Bookable type then a gadget is not required on the operator page.

Examples have been included so you can see how these are displayed on the operator page, included with the operator content

• https://book.isite.nz/lakeview-motel#/accom/88165
• https://book.isite.nz/maruata-rotorua#/accom/128720
• https://book.isite.nz/koru-native-wildlife-centre#/tours/137301

The Gadget Documentation can be viewed here.

The Booking Gadget
The Booking Gadget allows the customer to enter their details and credit card information. Please note there is no staging option available of this gadget. If you wish to make a test booking, the destination will need to provide a test operator and live credit card details.

This gadget must be included on HTTPS and only allows for minimum interactions through JavaScript. An example of this gadget can be viewed by proceeding through the booking process via any of the operator page examples above.

The documentation on this step can be found here.

The Confirmation Gadget
The Confirmation Gadget is the page that notifies the customer of their successful booking and provides a PDF summary of the booking details. From the previous gadget, you could direct users to your own custom confirmation page if required.

Please ensure you read all the supplied documentation through carefully before requesting assistance in managing gadget functionality for your development. There is an allocation of time included in the gadgets licence for technical assistance, however this does not extend to items that are already documented or are custom developments. Assistance provided for elements clearly documented may incur charges.

See https://developer.bookit.co.nz/gadgets

Ensure the gadgets are styled to best complement your site's theme (i.e. filters pane, action buttons, styling, borders, colour palette, etc) to provide a seamless experience for your users.

One of the primary advantages of inserted gadgets such as these is that you can use CSS on your site to change and mould the appearance of the gadgets to suit your site. The majority of styling requirements can be achieved only using CSS.

Responsiveness can be achieved in the same manner as Bootstrap, by using the same breakpoints (eg. http://getbootstrap.com/css/#grid-options).

To make it easy to figure out what CSS selector you need to address a particular part of a gadget, make a test page, then use Firefox and the add-on Firebug (the HTML tab). This tool is invaluable for figuring out what the DOM looks like after the gadget is running. Chrome, Safari, Opera and IE also have good developer tools.

We've created a sample CSS file that highlights the things you may want to re-style. This file is primarily a guide and only covers a few elements in each gadget, so if you're looking to restyle something that isn't in this file, check above for developer tools. You can download the sample css file here: View sample gadget restyling CSS file.

If you wish to create your own styling of the gadgets you can load the gadgets with minimal CSS or no CSS at all and build your own styling from scratch. Simply insert the below script above your gadget insertion on the page.

*Note: we have included spaces at the start of the opening and closing script tags, so that they show on the page.

< script type="text/javascript"> BEcssOverride = "none"; < /script>

Or

< script type="text/javascript"> BEcssOverride = "minimal"; < /script>

The ultimate goal with API integration is that you query the WebAPI, and store local copies of the data in your own database. From there you can hit your own API / Datastore.

This allows us to protect the system from excessive use, which means that this system is stable for all clients and allows you to manage your bandwidth on operator data. Failure to prevent excessive use of our systems may incur additional fees. See https://webapi.bookeasy.com.au/ for more information.

There are a few steps that need to occur before you build operator pages and start the development to the WebAPI. This is covered below.

This will require you to create an Import/Update Process, along with local storage, and determine how to serve that data on the site.

Step One: identify the VCID you are going to use, obtain a WebAPI key, and use those in HTTPS requests to the WebAPI.

If you are unsure which VCID to use, contact us at support@bookit.co.nz The WebAPI key should be used by making a GET request to a WebAPI HTTPS url, supplying the key in a header, e.g.

curl -X GET --header 'Accept: application/json' --header 'apiKey: 7edd898e69a14170b469fbf1eea98d41' 'https://webapi.bookeasy.com.au/api/getAccomAttributes?q=4'

Note: if you are using PHP, see an example of this in our Sample Web API class

Step Two: Get a list of operator IDs for the booking centre.

https://webapi.bookeasy.com.au/swagger/ui/index#!/Visitor32Centre/VcOperatorIds_Get

This call will get you a list of all the latest active/bookable operators in your system for that ID. You can use this to determine if there is a new operator or an operator has been removed as well.

Step Three: Check for modified dates

https://webapi.bookeasy.com.au/swagger/ui/index#!/Operators/OperatorModDates_Get

This call will give you a list of operators that have had their images/static data changed. This data will also need to be stored in your system, so you can pick up changes. The date format should be amended each time you poll for a list of updates.

We also suggest polling the WebAPI for changes to the data. Polling for changes can be done every 10 minutes or so. This will mean that your static data will be 5 mins or so out of date. That being said static data very rarely changes and some booking centres will only poll once a day without issue.

Step Four: Obtaining operator data

https://webapi.bookeasy.com.au/swagger/ui/index#!/Operators/OperatorsInformation_Get (Cap at 15 per string)

We ask for capping the amount of data in the string due to the potential size this call can be. If this is a major problem you could try to use the following call:

https://webapi.bookeasy.com.au/swagger/ui/index#!/Operators/OperatorsDetailsShort_Get

This call is much faster, however, contains less operator information than is contained in the full report.

Bookit reserves the right to review all integrations before they are published live.

Once you feel the development has been completed, please submit the certification form. Please note that this form must be submitted no later than 10 business days prior to your intended release date.

With all gadget integrations we offer 3 hours of support for external developers. This includes email support to try to assist with common integration issues that may arise.

If Bookit developers need to investigate external code due to errors, this time will be charged to the enquiring digital agency. Developer time is charged at $170 per hour.

To get in touch with us please email support@bookit.co.nz