External Developer Guide

MVC Enhancement

Developer Integration Information

The complete guide to integrating the Bookeasy Destination Management Solution into your website.

Before You Get Started

Before you get started on your integration of the Bookeasy Technology it is important that you read and understand the below elements of the integration.

This page will allow you to understand

  • What is Bookeasy?
  • What are beGadgets
  • Building Operator Pages
  • Recommended Parameters
  • Styling
  • The Bookeasy SJP
  • Getting Your Site Live

Wordpress Integration

The beGadgets can be integrated with Wordpress and other Content Management Systems however, it is important to note that these are not plugins. As such, a decent level of development knowledge is required, including Javascript, PHP, and API Integration.

ATDW Integration

ATDW integration is possible, however a consideration must first be made as to whether you wish to pull and manage the content from ATDW directly, or import your content into Bookeasy and then display from there. You can find further information on ATDW integration within this page should you require more details.

API Integration

Bookeasy do not allow direct "push" connections to our API. We simply provide an option which allows you to call our system for information. We have also included a suggested path to follow. If you choose to go outside of these bounds, we will not support errors or conflicts you may receive.

Operator Pages

The operator pages must include content. When integrating the gadgets, we will not provide content for you.

Styling

You, as the website developer, will be responsible for the styling of the beGadgets. The gadgets do have a default styling, however this will not work when implemented within your site.

Project Brief

Please ensure that you have obtained a clear project brief before you start the integration. We also recommend that you organise a meeting with Bookeasy 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@bookeasy.com

Understanding Bookeasy

What is Bookeasy and Why is it Integrated?

Bookeasy is the leading destination management system for the Tourism Industry. The system is currently being used by over 200 destinations encompassing Visitor Information Centres, National Parks, Property Managers, and Specialised Tourism Providers across Australia, New Zealand, and Asia. We also have over 45,000 active tourism operator consoles currently being used, making it one of Australia's largest content providers for the tourism industry.

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

Bookeasy allows a destination to access the system from an Operator’s perspective, and is broken up into six major objects:

Below should allow for you to get a high level understanding of the hierarchy of data in Bookeasy

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"
The Booking Centre also creates all of the configuration for operators, including: categories, 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 Bookeasy to display via the beGadgets. The operator console is also where they load images/descriptions. Each operator in Bookeasy contains a unique property ID which is important throughout the integration.

Bookeasy also have 4 main bookable operator types. Accommodation, Tours, Car Hire, and Tickets (aka Events)

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

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

Credentials Required

You will need the following credentials before starting the integration:

  • Staging domains
  • VCID (q=1234)
  • Auth Key for gadgets
  • Test operators (Accommodation, Tours, Events, Car Hire)
  • Gadget documentation
  • Ensure the beConsole configuration has been completed

The client must have also submitted the following:

  • beGadget Supply Agreement

To obtain this information please contact beDigital via email: bedigital@bookeasy.com

What are the beGadgets?

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

There is help documentation on the beGadgets available here.

There are technically 5 gadgets to integrate; however there is a process flow which is contained below

The Search Gadget
This is the gadget which is on the homepage of the website. This is the main call to action on the homepage of the website and should be front and centre so the website user knows that bookings can be made on the site. The documentation for the search gadget is found here.

  • We have included some great examples of search gadget integration below:

    Tourism Whitsundays
    Bendigo Tourism
    Visit Newcastle

    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.

    Examples have been included below:

    Tourism Whitsundays
    Bendigo Tourism
    Visit Newcastle

    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 people.

    The Gadget documentation for the region gadget can be found here

    The Item Detail Gadget
    The Item Detail Gadget is the gadget which sits on the operator page. This gadget shows the operators 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

    Example 1
    Example 2
    Example 3

    The Gadget Documentation can be viewed here

    The Booking Gadget
    The Booking Gadget is where the customer enters their customer and credit card details. 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.

    The documentation on this step can be found here

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

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

    The "beGadget" (Bookeasy Gadget) is the 'out-of-the box' booking engine that can be integrated and styled on destination websites. As seen on sites such as visitnewcastle.com.au, tourismwhitsundays.com.au, bendigotourism.com, byronbayaccom.net, and many more.

    The gadgets leverage the data provided via Bookeasy's Soap >> Json Proxy (SJP).

    The beGadgets come with a generic/standard styling that can be restyled using CSS. There are 5 main gadgets that make up the process of a booking, each with their unique specific function. Each gadget also includes a number of "parameters" that can be introduced in order to enhance the user experience.

    The Search Gadget

    The Search Gadget

    Simply put, this is the gadget that can "kick off" a search, generally found on a homepage and other generic pages.

    The Region Gadget

    The Region Gadget

    This is the gadget that displays search results for all tourism operators of a specific category (i.e. accommodation/tours). Search results are either displayed as a direct result of search parameters entered via the Search Gadget, or due to default parameters set for when a guest lands directly on this page.

    The Item Details and Cart Gadgets

    The Item Details and Cart Gadgets

    The Item Details Gadget displays a tourism operator's specific product, and also allows the guest to add a product item to the shopping cart. As a result, the Item Details gadget requires the presence of the Cart Gadget, which is the gadget that can display items in a guest's shopping cart.

    The Booking Gadget

    The Booking Gadget

    This is the gadget that summarises a guest's cart items and allows them to finalise their sale by entering in their personal information and credit card details.

    The Confirmation Gadget

    The Confirmation Gadget

    If used, the Confirmation Gadget is a gadget that allows for the display of a a summary PDF and "thank you" messaging.

    Best practice for the beGadgets

    To ensure the site is designed to attract optimal viewing and maximise conversion rates, we encourage the following guidelines to the beGadget integration:

    • Position the Search Gadget in a prominent position within the first fold of the homepage, ensuring a strong and clear 'call to action'
    • Implement a Search Gadget on most if not all pages within your site (this should always be within the first fold of the page to attract action).

    • Ensure the beGadgets 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.
    • Default the Results Gadget's sort order to 'Instant'. I.e. Gold Operators over Request Based. This will entice real-time bookings from your consumers, and will entice your Operators to transition from '24hr' to 'Instant'.
    • Operator Profiles should not display the Operator PHONE | EMAIL | WEBSITE details if they have bookable product. Doing so is proven to be a large hindrance for a destination to generate online bookings. If required, we strongly suggest these details require an action to prompt their display.

    • Ensure the operator pages are clear, informative, and have the Items Gadget located in a prominent position on the page, as with operator imagery (which is a proven feature to selling more). We also advise that you load SEO friendly URLS Eg. www.bookeasy.com/operator-name and avoid having URL's like www.bookeasy.com/page/subpage/pagename.aspx#/accom/1234
    • Set your site's default search nights to 3, 5 or 7 depending on how they render. This produces a 'grid view' that is deemed industry common. Doing so should entice longer stays, as well as generate more bookings due to increased transparency.

    • Be wary of other elements such as 'Site Search' and 'Business Directories' when integrating the booking engine. It is imperative to avoid duplicate Operator Profiles and ensure a seamless user experience.

    • To ensure the beGadgets propagate on your website, ensure that you redirect your website's non-www domain URL to the www domain URL (or vice versa, depending on which domain URL version you have been provisioned a beGadget Authorisation Key for). For example, if beDigital has provisioned a beGadget Authorisation Key for www.yourdomain.com, ensure that you redirect yourdomain.com to www.yourdomain.com. If you don't, then anyone landing on the yourdomain.com version of your website will not see the beGadgets displayed and will be unable to make bookings. This will also assist your website's SEO and search engine indexing.

    Recommended Parameters

    Each beGadget contains various parameters that can be parsed with the javascript gadget. These are included in the actual code of the gadget. An example screenshot of how parameters are implemented with the gadget is found below:

    Example Image

    There are many parameters that can be used and can be viewed from the gadget documentation found here. However, we have included our recommended parameters below.

    Recommended Parameters

    showAll
    showAllAccom | showAllTours | showAllEvents should be applied to both the REGION and ITEM Gadgets.

    This should be applied so in the event that a user visits an operator profile directly, or further inspects an operator that does not have availability for all dates selected, they will not see the message: Sorry, no results match your search criteria. Please change your dates and options and try searching again.

    bookingStatus
    This is nice customisable feature that allows you to modify the default 'Sold' term to something more enticing to promote more bookings. Terms such as Enquire | Request | or even the VIC's Contact Number are encouraged instead of the default.

    Inline parameters
    These are parameters that will enable the display of the operator's descriptions to show inline, rather than a hover, which is far more mobile friendly and strongly encouraged. This would be a default feature, however cannot at present due to some clients interpretation of the gadgets styling.

    Region:
    • showRoomDetails: true
    • showRoomDetailsInline: true
    • showHoverInline: true

    Item:
    • descriptionHovershow: true
    • hoverInline: true

    showRoomDetails
    At the Region Gadget level, you can apply a parameter that allows the user to view the Operator's product on the same page, rather than having to drill down to the Operator Profile and perhaps back again.

    When applied, and should the user select Book Now against the product itself, the user will bypass the Operator Profile altogether and be taken directly to the Booking Gadget, meaning reduced steps to actually make a reservation.

    If they want more information, the user can select the Operator Name and be taken to the Operator Profile as per the default process. To be deemed an optional feature, perhaps worth trialling initially or seeking a business decision.

    Styling the Gadgets

    Styling

    Ensure the beGadgets 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, the implementor, 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. There are also a number of alternatives for those with more complex needs.

    beGadgets are highly customisable by using only CSS styling. 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 beGadgets 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>

    Some samples of different beGadgets styling are below:

    http://www.visitnewcastle.com.au/
    http://www.ministryofvillas.com/
    http://www.margaretriver.com/
    http://www.visitpeel.com.au/
    http://www.alps2ocean.com/
    http://www.ozbook.com.au/
    http://www.parkstay.vic.gov.au/
    http://www.mackayregion.com/

    Building operator pages

    It is imperative that operator pages are created on the destination website. The operator page is the single most important page on the operator website, as this is the page which convinces the consumer to proceed with a booking.

    Some examples of great operator pages can viewed below:

    Tourism Whitsundays
    View Retreats
    Ministry Of Villas

    As you can see, these operator pages make great use of images and content and utilise the beGadgets to proceed with a booking.

    We would also recommend that you ensure that clients are sure of the design of the operator pages before proceeding with the development.

    To pull data from Bookeasy you will require to call the Bookeasy SJP. This has been covered in detail in this documentation.

    Requirements using SJP

    The ultimate goal with SJP integration is that you query Bookeasy, 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

    There are a few steps that need to occur before you build operator pages and start the development to Bookeasy. 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: Get a list of operator IDs for the VC

    http://sjp.impartmedia.com/V1.1/be/getVcOperatorIds?q=XXX

    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 Two: Check for modified dates

    http://sjp.impartmedia.com/V1.1/be/getOperatorModDates?q=XXX&ModifiedAfter=YYYY-MM-DD

    This call will give you a list 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 Bookeasy 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 we have some VC's that only poll once a day without issue.

    Step Three: Obtaining operator data

    http://sjp.impartmedia.com/V1.1/be/getOperatorsInformation?q=244&operators=XXXX,XXXX,XXXX (Cap at 15 per string)

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

    http://sjp.impartmedia.com/V1.1/be/getOperatorsDetailsShort?q=XXX&operators=XXXX,XXXX,XXXX

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

    ATDW Integration

    If the centre wishes to use ATDW operator content on their website, this is possible and there are two ways that this can be achieved.

    Option One: "Preferred"

    Built into the Bookeasy software is the ATDW integration. This allows a Booking Centre to sync operator content from within the Bookeasy system from ATDW. This then stores the content in Bookeasy. This option means that you will only need to organise the storage of data for operators from one central source rather than trying to match ATDW and Bookeasy together.

    This is also easier for the client to understand and the data follows a path of ATDW > Bookeasy > Website Database > Website Frontend

    It is also important to note that if you do use this method, you will be required to insert ATDW webbeacons on the website. This will allow ATDW to report on required stats from their side.

    For any further information on this data, please contact Bookeasy Support.

    Option Two: Direct ATDW Data

    It is possible to code directly to the ATDW API to pull content directly from them. If this is the preferred method, the client will need to provide ATDW with a list of operator IDs and operator names from Bookeasy.

    ATDW will then set the Bookeasy operator ID against their system, allowing you to load the correct Gadget.

    For further information on this method, please speak with ATDW directly.

    Getting the Site Live

    Bookeasy 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.

    Click to view the form

    Help and Support

    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 Bookeasy 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@impartmedia.com or call 07 5668 2543

    Featured Destinations

    Margaret River Busselton

    More

    Parks Victoria

    More

    Tourism Whitsundays

    More

    Tourism Top End - Darwin

    More

    View Retreats

    More

    Bay Of Islands

    More

    Sydney Visitor Centre

    More

    Barossa Visitor Centre

    More

    Visit Canberra

    Read more...

    Destination Launceston

    More

    Get in touch

    To discuss further information regarding the use of beGadgets, please get in touch via the details below.

     

    Call Bookeasy
    Call
     
    (07) 5668 2530
    Email Bookeasy
    Email
     
    support@bookeasy.com
    Visit Bookeasy
    Visit
     
    Suite 30303,
     
    9 Lawson St,
    Southport, QLD 4215

    Our Technologies.

    Gold Coast, AU

    • Meet us.
      Southport Central 
      Tower 3, Level 3, Suite 30304
      9 Lawson Street
      Southport, QLD 4215

      +61 7 5668 2530
    • Write us.
      support@bookeasy.comThis email address is being protected from spambots. You need JavaScript enabled to view it.
    • Follow us.
      Twitter logo white   FB-f-Logo  white 29    In-White-28px-R

    Recent Tweets