Implementation Guide (v2)
      Back to home
      1. Knowledge Base
      2. Booking Widget
      3. Implementation Guide (v2)

      Configuring the Booking Widget Using URL Arguments (v2)

      The Booking Widget (v2) can be preconfigured and opened upon loading a webpage. This functionality can be useful to prompt the widget for a specific store, a set or subset of services or a specific event.


      To do so, a list of arguments must be passed along with the URL at which the Booking Widget will be loaded. 

      Script

      Before proceeding further, make sure the below script is included on your webpage and loaded synchronously. The script’s URL depends on your hosting region, “www.booxi.com” for North America and “www.booxi.eu” for Europe.

       

      North America

      <head>
          <script src="https://www.booxi.com/api/booknow.js" sync=""></script>
      </head>

       

      Europe

      <head>
          <script src="https://www.booxi.com/api/booknow.js" sync=""></script>
      </head>

       

      How to Format URL Arguments

      A list of arguments should be constructed as a query string starting with the character ? and each argument separated with the appropriate separator &. 

       

      The below examples showcase how query strings are formatted.

      <!--example with a single user-defined argument "book" used to open the 
      booking widget as soon as the page is loaded -->

      www.yoursite.com/landingpage?book=now
      <!--example with a second user-defined argument "flow" assigned with the value "locations". 
      This argument will be used to open the booking widget with the parameter 
      bookingFlow:'locations' -->


      www.yoursite.com/landingpage?book=now&flow=locations

       

      Here’s a list of parameters the booking widget can be opened with. URL arguments can be used to assign values to these parameters

      Widget Parameters

      Name Description
      bookingFlow

      Determine the first step in the booking process. When setting the booking flow to “locations”, clients will be asked to select a store location before proceeding further with their booking.

      Possible values are:

      • locations
      locationTags Filter stores by location using user-defined tags.
      serviceTags Filter services using user-defined tags.
      serviceCategoryId Preselect a service category when opening the booking widget.
      serviceId Preselect a specific service the widget will be opened with. The ID can be found in the back office under a service’s summary page.
      staffId Automatically set staff ID when a service is selected. When used, a serviceId must be provided. The ID can be found in the back office under a staff’s summary page.

       

      Opening the Widget With a List of Arguments

      To open the widget with a set of arguments, the below steps must be followed:

      • Extract the arguments passed along with the URL.
      • Format arguments into a list of parameters recognizable by the widget.
      • Configure the widget with your API key.
      • Open the booking widget with your list of parameters.

       

      Extracting Arguments from URL

      Within the <body> of your webpage use <script> tags to embed  the following code. Arguments will be extracted from the query string and stored in an array.

       

      <body>
      <script>   

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');
         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

       

      Format Arguments Into a List of Parameters

      Then, parse each of the arguments and construct a list of parameters that will be passed to the booking widget. The parsing will vary depending on how you named your arguments and what parameters you want to pass.

       

        // Build a list of parameters from the arguments
         var param = {};
         Object.assign(param,
            (urlArgs[flow] == 'locations') ? { bookingFlow:'locations' } : null,
            (urlArgs['stores'] != '') ? { locationTags:urlArgs['stores'] } : null
         );

       

      Building the Configuration, Opening the Widget

      Next, build the booking widget’s configuration by assigning your merchant API key. You may assign optional properties such as the button’s text and the display language at this time. Then, open the booking widget by calling the method booxiController.open() using the parameters from the URL arguments.

       

         var bnHandler = null;
         window.bxApiInit = function () {

            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE',
            buttonText: 'Book',
            language: 'eng'
         });

         // Opening the booking widget with parameters from the URL arguments
         booxiController.open({null, param});

      </script>
      </body>

       

      The complete code segment should be as showcased below:

      <body>
      <script>

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');
         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

         // Build a list of parameters from the arguments
         var param = {};
         Object.assign(param,
            (urlArgs['flow'] == 'locations') ? { bookingFlow:'locations' } : null,
            (urlArgs['stores'] != '') ? { locationTags : urlArgs['stores'] } : null
         );

         var bnHandler = null;
         window.bxApiInit = function () {

            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE',
            buttonText: 'Book',
            language: 'eng'

         });

         // Opening the booking widget with parameters from the URL arguments
         booxiController.open({null, param});

      </script>
      </body>

       

      Use Cases

      One Store Location

      To open the booking widget for a specific merchant or store location, use your API key as shown below.

       

      Code

      <body>
      <script>

         var bnHandler = null;
         window.bxApiInit = function () {

            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE'

         });

         // Opening the booking widget
         booxiController.book();

      </script>
      </body>

       

      All Store Locations

      To open the booking widget for all merchants or stores, use your API key and set the parameter "bookingFlow" to "locations". 

       

      Code

      <body>
      <script>

         var bnHandler = null;
         window.bxApiInit = function () {

            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE',
            bookingFlow: 'locations'
         });

         // Opening the booking widget
         booxiController.book();

      </script>
      </body>

       

      Opening the Booking Widget Automatically 

       

      The following example showcases how you can control if the booking widget should be opened automatically using a simple user-defined argument.

       

      Example of URL

      wwww.yoursite.com/landingpage?book=now

       

      Code

      <body>
      <script>

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');

         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

         var bnHandler = null;
         window.bxApiInit = function () {

            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE'
         });

         // Open automatically if the argument book=now is passed
         if(urlArgs['book'] == 'now') {
            // Opening the booking widget with parameters from the URL arguments
            booxiController.book();
         }

      </script>
      </body>

       

      Choice of Stores Assigned with a Specific Tag (locationTags)

       

      The example below shows how to open the booking widget with a list of store locations assigned with the location tag “downtown”.

       

      Example of URL

      www.yoursite.com/landingpage?flow=locations&stores=downtown

       

      Code

      <body>
      <script>

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');
         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

         // Parse for booking flow and location tags
         var param = {};
         Object.assign(param,
            (urlArgs['flow'] == 'locations') ? { bookingFlow:'locations' } : null,
            (urlArgs['stores'] != '') ? { locationTags : urlArgs['stores'] } : null
         );

         var bnHandler = null;
         window.bxApiInit = function () {
            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE'
         });

         // Opening the booking widget with parameters from the URL arguments
         booxiController.open({null, param});

      </script>
      </body>

       

      Preselect a Service and a Staff Member (serviceId & staffId)

       

      This example shows how to open the booking widget with a specific service and a selected staff. Take note that when preselecting a staff, a serviceId MUST be provided otherwise, the booking widget will open with its default settings.

       

      Example of URL

      www.yoursite.com/landingpage?service=12345&staff=123456

       

      Code

      <body>
      <script>

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');
         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

         // Parse for serviceId and staffId
         var param = {};
         Object.assign(param,
            (urlArgs['service'] != '') ? { serviceId:urlArgs['service'] } : null,
            (urlArgs[staff] != '') ? { staffId:urlArgs['staff'] } : null
         );

         var bnHandler = null;
         window.bxApiInit = function () {
            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE'
         });

         // Opening the booking widget with parameters from the URL arguments
         booxiController.open({null, param});

      </script>
      </body>

       

      Services Assigned with a Specific Tag (serviceTags)

       

      This example shows how to open the booking widget and list only services assigned with the tag “vip”.

       

      Example of URL

      www.yoursite.com/landingpage?type=vip

       

      Code

      <body>
      <script>

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');
         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

         // Parse for service tags
         var param = {};
         Object.assign(param,
            (urlArgs['type'] != '') ? { serviceTags:urlArgs['type'] } : null
         );

         var bnHandler = null;
         window.bxApiInit = function () {

            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE'
         });

         // Opening the booking widget with parameters from the URL arguments
         booxiController.open({null, param});

      </script>
      </body>

       

      Specific Service Category (serviceCategoryId)

       

      This example shows how to open the booking widget with a preselected service category.

       

      Example of URL

      www.yoursite.com/landingpage?category=14082

       

      Code

      <body>
      <script>

         // Extracting arguments from the URL
         var urlArgs=[];
         var s=location.toString().split('?');
         s=s[1].split('&');

         for(i=0;i<s.length;i++) {
           u=s[i].split('=');
           urlArgs[u[0]]=u[1];
         }

         // Parse for a service category
         var param = {};
         Object.assign(param,
            (urlArgs['category'] != '') ? { serviceCategoryId:urlArgs['category'] } : null
         );

         var bnHandler = null;
         window.bxApiInit = function () {
            // Configure your API key to initialize the booking widget
            bnHandler = booxiController.configure({
            apiKey: 'YOUR_API_KEY_HERE'
         });

         // Opening the booking widget with parameters from the URL arguments
         booxiController.open({null, param});

      </script>
      </body>