Primeros pasos
En esta sección se te explicará los pasos a seguir para que puedas crear desde cero tu propia plataforma 100% personalizada. Esta API javascript, se creó con la intención de que cualquier cliente de nuestra plataforma pueda generar sus propias soluciones de forma ágil y rápida. Estas mismas herramientas que les compartimos son las que utilizamos nosotros en nuestros desarrollos y por lo mismo las queremos compartir con ustedes para que puedan lograr, personalizaciones propias y lograr exclusividad en su producto.
- Crear mi plataforma
- Instala y ejecuta gpsApi
- Ejemplo de plataforma
- Recibe notificaciones, alertas o eventos
- Crear listados
- Crear Formularios
- Cargar contenido externo
- Manejo de mapa y marcadores
Crear mi plataforma
Acceso a "Mis Plataformas"
1: Para crear su propia plataforma, debe ingresar a la plataforma "Partners" y en la opción superior debe dar clic en "Opciones" y entrar en la sección "personalización de plataformas"
Una vez dentro de "personalización de plataformas", debe dar clic a la opción "Mis Plataformas", para mostrar un listado de las plataformas que se han creado.
Entre las acciones que se tienen disponibles en el listado de plataformas son:
Acceder : Con esa opción podrá acceder a la plataforma creada.
Editar: Con esta opción se podrán editar los parámetros iniciales de la plataforma.
Eliminar: Con opción podrá eliminar de forma lógica una plataforma.
2: Debe dar clic sobre el botón "crear" para mostrar el formulario con el cual se registrara una nueva plataforma.
Los campos del formulario son:
Nombre Plataforma: Es el nombre con el que se identificara a la nueva plataforma.
URL Destino: URL hacia donde apuntará la plataforma.
Clase del Icono : Para esta opción, se debe escribir la clase del icono que se mostrara referente a su plataforma, acceda a la librería de iconos y css con la siguiente URL http://library.service24gps.com/
Subir icono: Esta opción es para subir un icono personalizado, ppuede ser PNG, JPG o ZVG
Instala y ejecuta gpsApi
A continuación les explicamos 2 formas de utilizar el GpsApiV2.
1. Ingresar y autenticar al usuario de forma directa luego de haber creado una plataforma personalizada.
Su creaste anteriormente la plataforma desde la plataforma de partners y se le asignó el permiso al cliente que utilizará la misma, podrás autenticar utilizando el link del menú de múltiples plataformas.
Al acceder a este icono de la plataforma que crearon anteriormente el sistema abrirá la URL destino que definieron y a la misma le agregará un TOKEN, el cual se encuentra en la URL y este mismo sirve para autenticar al usuario en su plataforma personalizada.
En este caso usted solo debe incluir estas lineas de código en la URL de destino y de forma automática nuestra librería realizará la autenticación del usuario y por medio de javascript usted podrá acceder a todos los elementos o permisos que tenga el usuario.
AQUI EL CODIGO DE EJEMPLO DE JSAPI |
Te recomendamos que para crear tu primer plataforma utilices el ejemplo que aparece en el siguiente capitulo de este libro llamado "Ejemplo de plataforma" ya que ahí encontrará un ejemplo completo de como crear tu plataforma con solo copiar y pegar el código.
2. Utilizar el API de forma manual.
En el caso que quieras utilizar el API de forma manual, deberán en su plataforma o desarrollo propio, crear un formulario de autenticación o dejar esta información de forma fija en el código.
Cuanto utilizamos el API manualmente, esta misma requiere algunos datos para poder autenticar:
Usuario y contraseña: estos son los datos que utiliza el usuario diariamente para ingresar a la plataforma.
API key: esta llave, es generada desde la plataforma OnPartners, en el caso que usted no tenga acceso a la misma, puede solicitar al administrador de la plataforma que le genere el APIKEY para su cliente.
Un a vez teniendo estos datos de autenticación, podemos utilizar el siguiente ejemplo para realizar el ingreso y autenticación
al api por medio de javascript.
<h4>Code example for use <strong>gpsApiv2</strong></h4>
<script src="https://qa.service24gps.com/commons/js/axios.min.js"></script>
<script src="https://qa.service24gps.com/commons/js/gpsApiv2.js"></script>
<script>
setTimeout(function() {
_gpsApiv2.setRegenerateToken = true;
gpsApiv2.connect('USERNAME', 'PASSWORD', gpsApiv2.apikey)
.then(code => {
if (code == 200) {
console.log('OK, token=', _gpsApiv2.token);
} else {
console.info(`Error #${ code }`);
}
})
.catch(console.error);
}, 1000);
</script>
Ejemplo de plataforma
En esta sección del libro, les mostraremos un ejemplo para poder crear una plataforma personalizada en el cual ahorrarán varios pasos en el proceso y podrán comenzar a trabajar las necesidades de sus clientes.
1. Ejemplo de plataforma sin mapa.
Para crear tu primer plataforma solo debes copiar y pegar este código HTML y JS dentro de tu servidor donde se encuentra la URL destino que configuraste al crear la plataforma y solo haciendo esto, nuestro código se encargará de autenticar al usuario por medio del token y ademas ya tendrás algunos elementos en Javascript listo para utilizar.
<!DOCTYPE html>
<html lang="es">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://gpsresources.sfo3.cdn.digitaloceanspaces.com/js/jquery-1.11.3.min.js"></script>
<script src="https://qa.service24gps.com/commons/js/axios.min.js"></script>
<script src="https://qa.service24gps.com/commons/js/commons_new.js?22"></script>
<title>my platform</title>
</head>
<body class="customPlatform">
<!--Header nuevo-->
<header class="header-custom fix-t" id="header-platform"></header>
<!---->
<section class="wrap-base wc40-60">
<div class="wb-aside">
<div id="listado_generico" class="dt-new-style"></div>
</div>
<div class="wb-content">
<div id="div-map"></div>
</div>
</section>
<script type="text/javascript">
menu_elements = [
{ name: "Activos", icon: "i-vehicle", function: "_gpsApiv2.getAssets"},
{ name: "Conductores", icon: "i-driver", function: "showDrivers" },
{ name: "Lugares", icon: "i-place", function: "showPlaces" },
{ name: "Google", "href":"http://www.google.com"}
];
platform_logo = "https://library.service24gps.com/img/library_icon.svg";
_createComponents.createMenu(menu_elements,platform_logo);
/* Para cargar elementos dentro del systemElements
si no requiere alguno, solo elimina la linea
*/
$(document).ready(function() {
setTimeout(() => {
_gpsApiv2.getAssets()
_gpsApiv2.getPlaces()
_gpsApiv2.getDrivers()
}, 3000);
});
function showDrivers() {
_createComponents.loading();
const data = _gpsApiv2.getSystemElements({ element: 'drivers' });
const columns = {
'nombre' : 'Nombre',
'apellido' : 'Apellido',
'licencia' : 'Licencia',
'nombrevehiculo': 'Vehiculo'
};
let action_buttons = [];
action_buttons.push({
class: "bt xs ico agregar",
icon : 'i-plus',
attr : {
id : 'new_element',
title : "Crear"._t(),
onclick: "_createComponents.showForm('driver');"
}
});
let extra_buttons = []
extra_buttons.push(
{
name: 'Editar'._t(),
icon: 'i-edit',
function: 'editDriver',
class: 'bt xs edit ico',
campos: [ 'id' ],
title: 'Editar'
},
{
name: 'Eliminar'._t(),
icon: 'i-delete',
function: 'deleteDriver',
class: 'bt xs eliminar ico',
campos: [ 'id' ],
title: 'Eliminar'._t()
}
);
if (data !== null && Object.entries(data).length > 0) {
_createComponents.createList({ data, columns, action_buttons, extra_buttons });
} else {
_gpsApiv2.getDrivers({})
.then(data => _createComponents.createList({ data, columns, action_buttons, extra_buttons }))
.catch(console.error);
}
}
function showPlaces() {
_createComponents.loading();
const map_exists = typeof google !== 'undefined';
const data = _gpsApiv2.getSystemElements({ element: 'places' });
const columns = {
'nombre' : 'Nombre',
'grupo' : 'Grupo',
'direccion': 'Direccion'
};
const extra_buttons = [{
name: 'Centrar'._t(),
icon: 'i-place',
function: 'centerPlace',
class: 'bt xs edit ico',
campos: [ 'idLugar' ],
title: 'Centrar'._t()
}];
if (data !== null && Object.entries(data).length > 0) {
_createComponents.createList({ data, columns, action_buttons: [], extra_buttons });
if (map_exists) {
principal.addPlaceMarkers({ data, divId: 'div-map' });
}
} else {
_gpsApiv2.getPlaces({})
.then(data => {
_createComponents.createList({ data, columns, action_buttons: [], extra_buttons });
if (map_exists) {
principal.addPlaceMarkers({ data, divId: 'div-map' });
}
})
.catch(console.error);
}
}
function centerPlace(id) {
const place = _gpsApiv2.getSystemElements({ element: 'places', key: id });
if (place === null) {
return false;
}
const { marker = null } = place;
if (marker !== null) {
principal.centerMap({ marker });
}
}
</script>
</body>
</html>
Un vez autenticado en tu plataforma, puedes acceder a información del usuario que ingresó por medio de javascript ya que debes contar con el siguiente Objeto de datos el cual, esta listo para que lo consumas.
//its defined a global object SYSTEMELEMENTS
console.log(systemElements);
//result {assets: {…}, places: {…}, drivers: {…}}
//This onject have elements as "assets, places, drivers" and shi have all elements atributtes
assets:
uid_element: {Address: '', Alto_icono: 50, Ancho_icono: 50, DatosJson: {…}, Equipo: 'uid_element', …}
uid_element: {Address: '', Alto_icono: 50, Ancho_icono: 50, DatosJson: {…}, Equipo: 'uid_element', …}
uid_element: {Address: '', Alto_icono: 50, Ancho_icono: 50, DatosJson: {…}, Equipo: 'uid_element', …}
drivers:
uid: {id: 'uid', numero: '', alias: '', nombre: 'name', apellido: 'lastname', …}
uid: {id: 'uis', numero: '', alias: '', nombre: 'name', apellido: 'lastname', …}
places:
place_uid: {idLugar: 'place_uid', nombre: 'place_name', direccion: '', latitud: '18.98', longitud: '-98.08', …}
place_uid: {idLugar: 'place_uid', nombre: 'place_name', direccion: '', latitud: '19.34', longitud: '-97.78', …}
Como se ve en el ejemplo anterior, en el objeto de systemElements, tendrás a la mano los elementos de la plataforma que el usuario tiene permisos para poder utilizarlos en tu desarrollo.
Así se verá la plataforma utilizando el código que se definió anteriormente en el ejemplo.
La plataforma puede o no contener un mapa, dependiendo de cómo lo definieron en la creación de la misma.
En el ejemplo anterior, definimos la creación de módulo o menús, dentro de la barra de navegación. Es importante que sepas que tu puedes crear todos los módulos o menús que necesites, siguiendo los ejemplos de herramientas que siguen a continuación en este mismos libro.
2. Ejemplo de plataforma con mapa.
A la hora de crear una plataforma con mapa, tenemos la opción de agregar el TOKEN del API de google dentro de la plataforma que creamos desde el menú de la plataforma OnPartners.
Un vez ingresada esta llave en tu plataforma personalizada, puedes utilizar el siguiente código de ejemplo para que inicies con tu plataforma la cual contendrá un mapa de google.
Recibe notificaciones, alertas o eventos
Una vez iniciada tu plataforma personalizada, nuestra librería se conecta de forma automática a un tópico de MQTT y la finalidad principal de este es que de forma automática el usuario que ingresó a la plataforma comience a recibir los mensajes de alertas o eventos que corresponden a los activos que el tenga asignados.
Los mensajes de eventos o alertas, los debes poder visualizar como en el siguiente imagen.
Estas notificaciones, aparecen por defecto en la parte inferior derecha de la pantalla de la plataforma.
En el caso que tu requieras generar desde un proceso propio notificaciones para tus usuarios, ya sea en tu plataforma o en cualquiera de nuestras plataformas, lo puedes hacer utilizando el siguiente ejemplo de código.
codigo para poder enviar un mensaje por MQTT A un usuario o a un cliente.
Documentación aún no disponible.
Con el ejemplo anterior, podrás encolar mensajes los cuales, serán recibidos por un usuario o por todos los usuarios de un cliente.
Crear listados
Dentro de las herramientas que incluye el GpsApiV2, tenemos una clase de javascript que es utilizada para maquetar elementos dentro de tu plataforma.
Dentro de estos elementos, tenemos la opción que desde un objeto javascript de datos podamos crear un listado tipo datatable como los que actualmente se utilizan dentro de nuestra plataforma.
Detalle de la función _createComponents.createList()
la clase que utilizaremos para crear elementos dentro de la plataforma es llamada "_createComponents" les dejamos un ejemplo de cómo utilizar la misma con la función "createList" que nos ofrece crear un listado de datos desde un objeto javascript.
//Create datateble list from javascritp data object
//example of data object
let list_data = [
{ id: '01', name: 'name1', lastname: 'lastname1', age: '11', phone: '99887766' },
{ id: '02', name: 'name2', lastname: 'lastname2', age: '11', phone: '99887766' },
{ id: '03', name: 'name3', lastname: 'lastname3', age: '11', phone: '99887766' },
{ id: '04', name: 'name4', lastname: 'lastname4', age: '11', phone: '99887766' },
];
//table options
var list_options = {
target_id : 'listado_generico',
data : list_data,
columns : { 'name': 'name', 'id': 'id', 'age': 'age', 'lastname': 'lastname'},
action_buttons : [],
extra_buttons : [],
table_height : null,
}
//execute createList function
_createComponents.createList( list_options );
Este ejemplo que se muestra en el código anterior, genera un listado como el que se ve en la siguiente imagen.
tu puedes utilizar esta función para crear todo tipo de listados dentro de tu plataforma personalizada.
Crear Formularios
Dentro de las herramientas disponibles de nuestra clase javascript tenemos una para poder crear formularios desde un objeto javascript.
Con esta función de la clase podrás crear formularios con un estándar tanto estético como funcional y con ello ahorrar bastante tiempo en los desarrollos.
A continuación mostramos un ejemplo de cómo utilizar este método o función.
//this object declare all forms fields, container, actions and title
var fields = {
"fields": [
{
id: 'idgrupo',
name: 'idgrupo',
visible: true,
type: 'combobox',
required: false,
fieldClass: '',
},
{
id: 'observaciones',
name: 'observaciones',
visible: true,
type: 'textarea',
required: false,
fieldClass: '',
},
{
id: 'numero',
name: 'Número',
visible: true,
type: 'text',
required: false,
fieldClass: '',
valueDefault: '00000001'
},
{
id: 'nombre',
name: 'Nombre',
visible: true,
type: 'text',
required: true,
fieldClass: ''
},
{
id: 'apellido',
name: 'Apellido',
visible: true,
type: 'text',
required: true,
fieldClass: ''
},
{
id: 'cancelForm',
name: 'cancelForm',
visible: true,
type: 'boton',
text: "Cancelar",
icon: "i-clear",
clases: "sm white",
functionClick: "$('#showFormsGeneric').modal('toggle')",
showLabel: false
},
{
id: 'saveDriver',
name: 'saveDriver',
visible: true,
type: 'boton',
text: "Guardar",
icon: "i-save",
clases: "sm save",
functionClick: "_createComponents.saveFormData(this, 'createDriver')",
showLabel: false
}
],
"conteiner": "showFormsGeneric",
"title": "Crear conductor"
}
//fhis function, create form into DOM
_createComponents.showCustomForm(fields)
Dentro de las opciones que se definen en el formulario, podrás definir a que función javascript se llamará para que esta guarde los datos del mismo en tu base de datos o donde la requieras.
Cargar contenido externo
Aquí se muestra un ejemplo de cómo podemos cargar un contenido externo dentro de nuestra plataforma. Este contenido puede ser de otra base de datos y de otro sistema.
Próximamente
Manejo de mapa y marcadores
Próximamente