Widget Customizable Web Check-in - Guía para Desarrollador
Introducción y Conceptos
A lo largo de este instructivo, los usuarios podrán crear sus propios widgets para embeber en las páginas web y de este acceder vía parámetros a las funcionalidades de Web CheckIn .
Este documento es una guía para el desarrollador web que explica como obtener y conectar el Widget desarrollado con el motor de reservas.
Esta guía no se adentra en como crear el widget, sino, los campos y contenido que debe contar para poder realizar las búsquedas a desplegarse luego en el motor web de KIU.
- Que es un widget?
- Es un formulario en HTML que debe contener estilos .CSS y que permite embeberse dentro de un iframe a la página web del cliente y otros sitios.
- Ofrece KIU un widget?
- Si. KIU provee de un widget estándar cuando el producto IBE es creado, pero, posiblemente este no contempla todos los aspectos que requiere el cliente por lo tanto, este último puede desarrollar su propio widget y conectarse con Web CheckIn.
- El widget desarrollado debe contemplar la configuración general de Web CheckIn?
- Si. El Widget debe contemplar y obtener el contenido en base a la configuración de la Web CheckIn con el objetivo de realizar las búsquedas de acuerdo a los requerimientos comerciales del cliente. Esta información reside en Backoffice y debe estar completamente configurado al momento de desarrollar e implementar el widget. En esta guía se explica como conectarse y como obtener el contenido a desplegar de acuerdo a la configuración mencionada.
Importante
Para poder hacer un POST al servicio de búsqueda de vuelos, primero es necesario que en Web CheckIn se agregue el host desde donde se va a realizar la búsqueda a los sitios permitidos, para esto es necesario que la aerolínea envíe a webservices@kiusys.com el host donde va a estar servido el widget y a cual ambiente de Web CheckIn va a apuntar.
Importante
Para que un carrier pueda utilizar el widget customizable, es necesario agregar en el settings del carrier la siguiente información:
- CSRF_TRUSTED_ORIGINS
- ALLOWED_HOSTS
Ambos con el DNS/HOST del carrier.
Obtener Contenido para Construir el Widget
Cuando el desarrollador crea el formulario en HTML para generar el widget, hay ciertos campos mandatorios que deben existir para poder enviar la información mínima necesaria a Web CheckIn y de esta manera obtener resultados.
Con el objetivo de obtener este contenido el desarrollador debe agregar el siguiente Script dentro de la etiqueta <head> en el formulario.
<script type="text/javascript">
var url = "http://wc2-dev-xx.kiusys.net/api/get_widget_form/?callback";
$.ajax({
url: url+"/api/get_widget_form/",
success: function(response){ formatResponse(response);},
dataType: "jsonp"
});
function formatResponse(response){
//Example of how to consume the data
$("#csrfmiddlewaretoken").val(response.csrf_token);
$("#pnr_label").html(response.form_inputs.pnr.label);
$("#pnr").attr("required", response.form_inputs.pnr.required);
$("#pnr").attr("max_length", response.form_inputs.pnr.max_length);
$("#pnr").attr("title", response.form_inputs.pnr.tooltip);
$("#pnr").attr("placeholder", response.form_inputs.pnr.label);
$("#last_name_label").html(response.form_inputs.last_name.label);
$("#last_name").attr("required", response.form_inputs.last_name.required);
$("#last_name").attr("max_length", response.form_inputs.last_name.max_length);
$("#last_name").attr("title", response.form_inputs.last_name.tooltip);
$("#last_name").attr("placeholder", response.form_inputs.last_name.label);
$("#conditions_url").attr("href", url+response.conditions.file_link);
$("#conditions_message").html(response.conditions.message);
form_actions_html = "";
$.each(response.form_actions, function( index, value ) {
form_actions_html+=('<div class="col-md-6 col-xs-12 text-center searcher-buttons-form-group"> <button type="submit" name="'+ value.id +'" value="1" class="btn button-search">'+ value.label +'</button></div>');
});
$(".button-lists").html(
form_actions_html
)
}
</script>
Ejemplo para armar un formulario:
<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.3.1/jquery.min.js"></script>
<form action="" method="POST" >
<input type="hidden" name="csrfmiddlewaretoken" id="csrfmiddlewaretoken" value="">
<div class="panel-body">
<div class="searcher-input">
<label class="etiqueta" for="url" id="url_label">Introduce una url para comenzar</label><br>
<input type="text" name="url" id="url" value="" placeholder="http://wc2-uat-xx.kiusys.net" >
</div>
<div class="searcher-input">
Datos:<br>
<label class="etiqueta" for="id_pnr" id="pnr_label"></label>
<input type="text" name="pnr" id="pnr" value="" >
</div>
<div class="searcher-input">
<label class="etiqueta" for="id_last_name" id="last_name_label"></label>
<input type="text" name="last_name" id="last_name" value="" >
</div>
<div class="col-md-12 row button-lists"></div>
<div class="row">
<div class="col-md-12 col-lg-12 col-xs-12 col-sm-12 conditions-text">
<b><a class="termsConditions" href="" id="conditions_url" target="popup"
onclick="window.open(this,'condiciones','width=800,height=600'); return false;">
<span id="conditions_message"> </span>
</a></b>
</div>
</div>
</div>
</form>
<script type="text/javascript">
var url = "";
$ ( document ).ready(function(){
$("input").on("change blur keydown", function(){
if ($(this).attr("id") == "url") {
url = $(this).val();
$("form").attr("action", url+"/");
get_template_data();
} else {
$(this).val($(this).val().toUpperCase())
}
})
function get_template_data() {
$.ajax({
url: url+"/api/get_widget_form/",
success: function(response){ formatResponse(response);},
dataType: "jsonp"
});
}
function formatResponse(response){
$("#csrfmiddlewaretoken").val(response.csrf_token);
$("#pnr_label").html(response.form_inputs.pnr.label);
$("#pnr").attr("required", response.form_inputs.pnr.required);
$("#pnr").attr("max_length", response.form_inputs.pnr.max_length);
$("#pnr").attr("title", response.form_inputs.pnr.tooltip);
$("#pnr").attr("placeholder", response.form_inputs.pnr.label);
$("#last_name_label").html(response.form_inputs.last_name.label);
$("#last_name").attr("required", response.form_inputs.last_name.required);
$("#last_name").attr("max_length", response.form_inputs.last_name.max_length);
$("#last_name").attr("title", response.form_inputs.last_name.tooltip);
$("#last_name").attr("placeholder", response.form_inputs.last_name.label);
$("#conditions_url").attr("href", url+response.conditions.file_link);
$("#conditions_message").html(response.conditions.message);
form_actions_html = "";
$.each(response.form_actions, function( index, value ) {
form_actions_html+=('<div class="col-md-6 col-xs-12 text-center searcher-buttons-form-group"> <button type="submit" name="'+ value.id +'" value="1" class="btn button-search">'+ value.label +'</button></div>');
});
$(".button-lists").html(
form_actions_html
)
}
});
</script>
URL: Se debe declarar el dominio de Web CheckIn (Este dato es proveído por KIU al momento de crear la instancia del producto para el cliente) agregando los parámetros /api/get_widget_form/ (Ej:http://wc2-dev-xx.kiusys.net/api/get_widget_form/?callback).
Esta URL va a devolver la siguiente respuesta en formato JSON:
{
"form_inputs":{
"last_name":{
"required":true,
"max_length":"100",
"tooltip":"TOOL ES",
"label":"Apellido"
},
"pnr":{
"required":true,
"max_length":"6",
"tooltip":"TOOL ES",
"label":"Codigo de reserva"
}
},
"csrf_token":"vgTgLRd6L1XKeeJdWdMSPDOhyUURzF02XJUl0CarwNc3ABHAQeWdMkmgi93QMVOI",
"conditions":{
"message":"",
"file_link":"/media/XX/general/conditions.pdf"
},
"form_actions":{
"void_checkin":{
"id":"void-check-in-button",
"label":"Anular Web Check-In"
},
"start_checkin":{
"id":"check-in-button",
"label":"Comenzar Web Check-In"
}
}
}
Diccionario de Respuesta
Nombre | Descripción | Valores / Formato |
|---|---|---|
form_inputs | Contiene un objeto con las configuraciones para el last_name y el pnr. | Objeto |
last_name | Es el objeto apellido que tiene la información necesaria para armar el campo en el formulario. | Objeto |
required | last_name, indica si el campo es requerido o no. | true / false |
max_length | last_name, indica la longitud máxima del campo. | Numérico |
tooltip | last_name, es el mensaje de ayuda en el tooltip. | Alfabético |
label | last_name, es el nombre del campo que se mostrará en el formulario. | Alfabético |
pnr | Es el objeto pnr que tiene la información necesaria para armar el campo en el formulario. | Alfanumérico 6 caracteres |
required | pnr, indica si el campo es requerido o no. | true / false |
max_length | pnr, indica la longitud máxima del campo. | Numérico |
tooltip | pnr, es el mensaje de ayuda en el tooltip. | Número |
label | pnr, es el nombre del campo que se mostrará en el formulario. | Alfabético |
csrf_token | Es el HASH de validación de DJANGO para la validación del SUBMIT del formulario. | HASH |
conditions | Es el objeto condiciones que tiene la información necesaria para armar el campo en el formulario. | Objeto |
message | El mensaje que va a mostrarse de acuerdo a los términos y condiciones. | Alfanumérico |
file_link | Es el link de descarga que se va a indicar para los términos y condiciones. | Link |
form_actions | Es el objeto que contiene las acciones de Anulación e Inicio sobre el formulario. | Objeto |
void_checkin | Es el objeto void_checkin que tiene la información necesaria para armar el campo en el formulario. | Objeto |
id | void_checkin, Id para armar el botón de Anulación. | key |
label | void_checkin, es el nombre del campo que se mostrará en el formulario. | Alfabético |
start_checkin | Es el objeto start_checkin que tiene la información necesaria para armar el campo en el formulario. | Objeto |
id | start_checkin, Id para armar el botón de Inicio. | key |
label | start_checkin, es el nombre del campo que se mostrará en el formulario. | Alfabético |
Búsqueda de Vuelos
Una vez que el formulario ya se encuentra desarrollado y cuenta con el contenido anteriormente descrito, el desarrollador debe enviar estos parámetros a Web CheckIn, para lo cual, debe agregar dentro de la etiqueta <form> :
- action: La URL de destino debe ser el dominio de Web CheckIn.
- method: El método debe ser POST.
Ejemplo:
<action="https://wc2-dev-xx.kiusys.net/" method="POST">
Incluidos estos atributos cuando el usuario envía el formulario, Web Checkin va a tomar los parámetros:
- last name
- pnr
Realiza una serie de validaciones de datos y procesa el pedido. En este momento, los resultados obtenidos se van a desplegar dentro de la página de Web CheckIn en el ambiente de Web CheckIn.
Validaciones Recomendadas
Mas allá que la aplicación Web CheckIn tiene sus propias validaciones en el backend, debemos realizar ciertas recomendaciones a los desarrolladores sobre algunas validaciones a realizar del lado del cliente (Front-end) con el objetivo de evitar errores de búsqueda inconsistentes y generar un proceso mas eficiente.
- last name:
Validar si el campo está como requerido.
Validar que sea de máximo 100 caracteres.
Validar que el ingreso sea en mayúscula. - pnr:
Validar si el campo está como requerido.
Validar que sea de 6 caracteres.
Validar que el ingreso sea en mayúscula.