Widget Custom E-commerce - Developer Guide

Owned by Angelo Suarez
Last updated: Feb 14, 2021 by Luciana Lospinnato
28 min read

Introduction and Concepts

Throughout this tutorial, users will be able to create their own widgets to embed in web pages and from there access via parameters to the functionalities of E-COMMERCE searchflight.

This document is a guide for the web developer, which explains how to obtain and connect the Widget developed with the booking engine.

This guide goes into how to create the widget, detailing the services and fields that you must have in order to build the tool and manage to perform the searches to be later displayed in E-COMMERCE flightresults.

What is a widget? 

It is a small application that is included on the client's website, with the aim of expanding the functionality offered by E-COMMERCE searchflight.

Does KIU offer a widget?

Yes. KIU provides a widget usable in an embedded way through an iframe when the E-COMMERCE product is created, but, possibly it does not cover all the aspects that the client requires therefore, it can develop its own widget and connect with E-COMMERCE , with the help of our API REST services, which provide all the data necessary to put together a personalized form and guarantee compatibility with the rest of the reservation flow.

The developed widget must consider the general configuration of E-COMMERCE?

Yes. The Widget must contemplate and obtain the content based on the configuration provided by kiu, in order to carry out searches according to the commercial requirements of the client. This information resides in Backoffice and must be fully configured when developing and implementing the widget. This guide explains how to connect and get the content to be displayed according to the mentioned configuration.

Get Content to Build the Widget

When the developer creates the HTML form to generate the widget, there are certain mandatory fields that must exist in order to send the minimum necessary information to the E-COMMERCE flightresults or corresponding screen according to the flow, and in this way obtain results.

Url to use iframe

This is to be used in case you prefer to use the widget that Kiu offers, within an iframe on the client's website.

https://ecommerce-xx-stage.kiusys.net/searchflight/widget/

Using this option, you only need to add this url to an iframe, like the following example:
<iframe src="https://ecommerce-xx-stage.kiusys.net/searchflight/widget/"</iframe>

General url to implement custom widget

The url to use in order to consume the necessary services to implement and use the custom widget, for example, carrier XX and stage environment:

https://ecommerce-xx-stage.kiusys.net/

Services to use

Get sessions

It is the first service to use, its function is to obtain a session key and the configuration of the flow that the application must follow. It is important that it is implemented first, since with the key session is that we can issue request to ... / configs.

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/sessions/

Implementation:

let headers = { 'Content-Type': 'application/json', 'accept': 'application/json', 'carrier': 'xx', 'sec-fetch-site': 'same-origin', 'sec-fetch-mode': 'cors', 'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/', 'authority': 'ecommerce-xx-stage.kiusys.net' } fetch('https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/sessions/', { method: 'GET', headers: headers } ).then(res => res.json()) .catch(error => console.error('Error:', error)) .then( response => customHandleResponseFunction(response) )

Response:

{ "kiu_internals":{ "duration":0.19812583923339844, "id_tracking":"backendsearchflight.29bad7c320a2_6a0a84986ffd41cc8fb90dee945baf21" }, "response":{ "flow":[ { "id":1, "spaflow_id":1, "url":"/searchflight/", "zorder":0 }, { "id":2, "spaflow_id":1, "url":"/flightresults/", "zorder":1 }, { "id":5, "spaflow_id":1, "url":"/travellerdetails/", "zorder":2 }, { "id":8, "spaflow_id":1, "url":"/extraservices/", "zorder":3 }, { "id":6, "spaflow_id":1, "url":"/purchase/", "zorder":4 }, { "id":7, "spaflow_id":1, "url":"/endflow/", "zorder":5 } ], "session_key":"fake-test-key.rPnZwFJPXkQ" } }

Response dictionary:

Field

Sub field

Descripction

Format/values

Field

Sub field

Descripction

Format/values

flow

 

List of screens within the e-commerce flow that the user must go through

Array → Object

 

spaflow_id

record id inside spa flow manager

Int

 

url

Path of the screen corresponding to the flow

String, Ej. '/flightresults/'

 

zorder

Indicates the order of the screen. It helps us know where we should go, depending on where we are positioned

Int

Get configs

It is the main service, provider of all the configuration of the carrier.

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/configs/


Implementation:

let headers = { 'Content-Type': 'application/json', 'accept': 'application/json', 'carrier': 'xx', 'sec-fetch-site': 'same-origin', 'sec-fetch-mode': 'cors', 'referer': 'https://ecommerce-xx-stage.kiusys.net/searchflight/', 'authority': 'ecommerce-xx-stage.kiusys.net', 'authorization': 'Token session_key obtained from get_sessions' } fetch('https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/configs/', { method: 'GET', headers: headers } ).then(res => res.json()) .catch(error => console.error('Error:', error)) .then( response => customHandleResponseFunction(response) )

Response:

Response dictionary:

Get Dates

Returns the list of dates with flight availability from the current day to the subsequent 330 days. This service must be used having implemented the inputs of origin and destination. So once the value for the two fields specified above is selected, you can execute the http request.

Parameters:

origin: The code of the airport of origin. Example: 'AEP'.

destination: The code of the airport of destination.. Example: 'BUE'.

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/dates/?origin=${origin}&destination=${destination}


Implementation:

Response:

Response dictionary

In this answer we obtain all the dates with availability from the current day to 330 days later.
ow: Represents the dates available for flights one_way
rt: Represents the dates available for flights round_trip.
The idea of this information is to have what it takes to start any "datepicker" component, indicating which dates you should enable. In the event that the component used does not have this attribute and on the contrary admit dates to disable, this list can be used, comparing it against 330 days, so that we would obtain the days without availability that we would need, (depending on the component used).

Post action

Este servicio es responsable de enviar los datos para la búsqueda de disponibilidad, una vez que el usuario haya completado todos los campos mínimos requeridos. La solicitud debe hacerse a través de POST AJAX y al obtener la respuesta, simplemente redirija a la siguiente url de acuerdo con el flujo obtenido, utilizando el servicio get_sessions.

Parámetros:

country_setting: Country setting selected by usrr.
session_key: session_key from get_sessions.
journey_type: Journey type selected by user.
origin: Origin code selected by user.
destination: Destination code selected by user.
departure_date: Departure date selected by user.
return_date: Return date selected by user (In case round as journey type).
adults: Adult passenger quantity selected by user.
minors: Minor passenger quantity selected by user.
infants: Infant passenger quantity selected by user.
cabin: Cabin selected by user.
promo: Promo code inserted by user.

Url:

https://ecommerce-xx-stage.kiusys.net/searchflight/api/v1/action/


Implementación:

Respuesta:

Based on this answer, the developer has enough information to display within the different fields of the widget:

  • Departure and arrival airports

  • Allowed rutes

  • Passenger types supported

  • Passenger max quantity allowed for search

  • Journey type supported (One way and round trip)

  • Currencies supported by country

  • Temporary messages and privacy politics

  • Promo codes

  • Cabin list

  • Translations

Also based on this information you can generate filters and validators on the client side.

Implementation of the form

El objetivo de esta sección es aprovechar el contenido obtenido en los servicios disponibles para armar el formulario de búsqueda, llevar a cabo las validaciones pertinentes y finalmente poder enviar información a los resultados de vuelo de E-COMMERCE.
What will be shown below is based on a simple development, using bootstrap, javascript and jquery.

HTML

Header:

Form:

Script Javascript:

Demo project to start

IMPORTANT NOTE

This is meant to be used an implementation guideline for developers; it is not meant to be used within the development.

This HTML should not be used as it is. It is not adapted to work on all browsers, devices, or their versions.

This widget needs to be adjusted and a certification process is required before going live where all parties must be involved (airline, website developer, Kiu)

In the following .zip file, you can get a startup version to implement a widget from scratch, in addition, it also has the widget that E-COMMERCE provides to be embedded directly into an iframe without further effort:

Required validations

Beyond that the E-COMMERCE application has its own validations in the backend, we must make certain recommendations to the developers about some validations to be performed on the client side (Front-end) in order to avoid inconsistent search errors and generate a process more efficient.

Origin - Destination:

The Get_config response returns the list of search-enabled routes configured in the backoffice. Based on this information, the developer can filter and validate the related options and thus optimize the search results. This filter is done for example in the javascript function filterRoute(), This must be used in an onkeyup event

Dates:

The supported date format is YYYY-MM-DD (example: 2020-04-06). The developer can display the form in different formats according to the zone he is in, but he should consider doing the transformation to respect the supported format and thus avoid E-COMMERCE returning format error.

Departure date:

The departure date should be considered from the current date to the future and not beyond 330 days in the future. The industry standard application supports availability searches up to 330 days into the current date. We specify this in the Get_dates section, and we use it in the manageDates () javascript function.

Return date:

The return date must be validated against the departure date. This cannot be earlier than the date set for departure and must not exceed 330 days in the future.

Adult passengers:

We recommend that the default value be 1. Do not accept 0, to avoid requests via the unaccompanied minors web sales channel that involves an internal process for authorization by the airline. Similarly, these settings are included in the Get_configs response, passenger_types field.

Infant passengers

By industry logic, an adult must previously exist before adding an infant. If there is more than one infant passenger, the same number of adults must exist since only one infant passenger can be associated and only one can be associated with one adult passenger.

Sending data to E-COMMERCE:
The Post action service is used for sending search data by AJAX, it should not be used in a form submit event, since it does not support re-addresses. The correct use of this service is: once the response with status 200 has been obtained, we must redirect to the next screen E-COMMERCE, This information is provided by the Get sessions service, used first in the integration flow , whose information must be saved in the client (Front End).

To do the redirection, based on the flow, we can make use of the handlePostResponse () function, or directly, taking into account the general url, the session data previously obtained and the Post Action response, use something like the following :