196 lines
9.6 KiB
Markdown
Executable File
196 lines
9.6 KiB
Markdown
Executable File
[[post_data {
|
|
"author" : "KyMAN",
|
|
"since" : 20220320,
|
|
"version" : 20220320
|
|
}]]
|
|
# Funcionamiento
|
|
|
|
El funcionamiento del KStats está dividido en dos partes: cliente y servidor. Para empezar por la
|
|
parte más común, nos vamos a ir por la parte del lado cliente. Pero antes de empezar, es importante
|
|
mencionar que el entorno cliente es un entorno ECMAScript el cual ha de ser ejecutado para que
|
|
funcione sobre el lado servidor, y el lado servidor ha de estar activo.
|
|
|
|
## Cliente
|
|
|
|
El lado cliente se basa dos partes diferenciadas: en la creación del Token; y la instalación cliente
|
|
del mismo.
|
|
|
|
> [[! important IMPORTANTE]]: El KStats funciona de dos formas diferentes cara el cliente:
|
|
registrando un histórico completo mediante ECMA/JS; y registrando accesos mediante petición URL.
|
|
|
|
### Creación del Token
|
|
|
|
Empezando por la creación del Token, nos encontramos en la base de datos, en caso de no tener acceso
|
|
por favor, pónganse en contacto con el administrador del sitio, y hay que ejecutar un procedimiento
|
|
almacenado llamado "token_create" el cual tiene los siguientes parámetros:
|
|
|
|
- **$public (_entrada_)**: Parámetro de entrada que indica si el Token es público o no. Al estar
|
|
sobre el lado cliente éste ha de ser siempre "true".
|
|
- **$pattern (_entrada_)**: Parámetro de entrada que permite restringir los registros de URLs a un
|
|
patrón regular, el cual puede tener más de un radical, como por ejemplo el caso de la Web de KyMAN.
|
|
- **$remarks (_entrada_)**: Parámetro de entrada de texto libre con límite en 2048 caracteres que
|
|
sirve para describir el Token, finalidad, etc. Así como establecer notas, observaciones o cualquier
|
|
otro elemento textual que pertenezca al mismo.
|
|
- **$error (_salida_)**: Parámetro de salida que mostrará un código de error en formato numérico
|
|
entero donde cada bit representa lo siguiente según posición:
|
|
0. Excepción SQL.
|
|
1. El valor '$public' es nulo.
|
|
2. El valor '$pattern' es nulo.
|
|
3. El valor '$pattern' está vacío.
|
|
4. El valor '$remarks' es nulo.
|
|
5. El valor '$remarks' está vacío.
|
|
- **$id (_salida_)**: Parámetro de salida que retorna el ID del nuevo Token creado.
|
|
- **$token (_salida_)**: Parámetro de salida que retorna el nuevo Token creado.
|
|
|
|
Ejemplos:
|
|
|
|
```sql
|
|
|
|
-- Para crear el Token de KSTats.
|
|
call token_create(true, '^https?\\:\\/{2}kstats\\.k3y\\.pw\\/?', 'Token for KStats project.', @error, @id, @token);
|
|
select @error, @id, @token;
|
|
|
|
-- Para crear el Token de KyMAN y MiguelBST.
|
|
call token_create(true, '^https?\\:\\/{2}(kyman|m(iguel)?bst)\\.k3y\\.pw\\/?', 'Token for KyMAN|MBST project.', @error, @id, @token);
|
|
select @error, @id, @token;
|
|
|
|
```
|
|
|
|
### Adjuntar KStats para ECMA/JS
|
|
|
|
Una vez tenemos los Tokens creados, podemos ir al entorno cliente propiamente dicho donde hemos de
|
|
agregar en cada página Web donde queramos registrar los Stats el siguiente fragment HTML y ECMA.
|
|
|
|
```html
|
|
|
|
<script data-type="text/javascript" data-language="ECMAScript 2015" src="https://kstats.k3y.pw/ecma/KStats.ecma.js" data-crossorigin="anonymous" charset="utf-8"></script>
|
|
|
|
<script>
|
|
|
|
kstats = new KStats({url : "https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/json/set"});
|
|
|
|
</script>
|
|
|
|
```
|
|
|
|
La primera etiqueta adjunta a nuestra página Web el Script que gestiona el Script ECMA que nos hace
|
|
falta para poder ejecutar el KStats; mientras que el segundo crea el objeto KStats con la URL
|
|
concreta que identifica tu sitio Web dentro del KStats con su Token concreto. Es importante saber la
|
|
estructura de la URL de petición.
|
|
|
|
Los parámetros de entrada que se le pueden dar a ese diccionario donde metemos la URL son los
|
|
siguientes:
|
|
|
|
- **autostart**: Valor que determina si el objeto se inicia de forma automática (true) o se hace de
|
|
forma manual (false). Por defecto es true.
|
|
- **nulls**: Valor Booleano que determina si se admiten retornos nulos o no. Por defecto es false.
|
|
- **default_value**: Valor por defecto a retornar en caso de no tener opciones de valor. Por defecto
|
|
es null.
|
|
- **ajax_timeout**: Tiempo límite de ejecución de una petición asícrona AJAX (XMLHttpRequest) en
|
|
miliseguncos. Por defecto son 2000 milisegundos.
|
|
- **settings_overwrite**: Valor Booleano que determina si se sobreescriben los valores de la
|
|
configuración a la hora de añadirlos (true), en base a sus llaves, o no (false). Por defecto es false.
|
|
- **kstats_url**: URL por defecto a la cual atacar. Por defecto es
|
|
"https://kstats.k3y.pw/api/uCDY3brWxEJrJywm2sFcKo1d8oaUdmxTTrv3VGuhpyRDpPYXyKeHWeknh/{session}/ecma/set".
|
|
- **frames_per_second** o **fps**: Fotogramas por segundo o tasa de refrescos por segundo cara los
|
|
hilos. Por defecto son 1 fotograma por segundo.
|
|
- **milliseconds_per_connection**: Tiempo de espera entre una conexión y otra para actualizar el
|
|
estado actual del usuario en milisegundos. Por defecto son 2000.
|
|
- **session_cookie_name**: Nombre de llave de la Cookie que almacena la sesión del servidor de forma
|
|
cruzada. Por defecto es "kstats_session_id".
|
|
- **session_timeout**: Tiempo límite de inactividad de la sesión en milisegundos. Por defecto es de
|
|
60000. *Este valor no tiene efecto inicialmente*.
|
|
- **data_key**: Nombre de llave de variable por donde se enviarán los datos al servidor. Por defecto
|
|
es "kstats_data". **Tiene que ser el mismo que la del servidor.**
|
|
|
|
### Registro por petición URL
|
|
|
|
Este método permite hacer registro a partir de una llamada, tanto manual como automática, al
|
|
servidor. A continuación se presentarán ejemplos de llamadas automáticas:
|
|
|
|
```html
|
|
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
|
|
<!-- Llamada desde un ECMA -->
|
|
<script data-type="text/javascript" data-language="ECMAScript 2015" src="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/ecma/set" data-crossorigin="anonymous" charset="utf-8"></script>
|
|
|
|
<!-- Llamada desde un JS -->
|
|
<script data-type="text/javascript" data-language="JavaScript 1.8.5" src="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/js/set" data-crossorigin="anonymous" charset="utf-8"></script>
|
|
|
|
<!-- Llamada desde un CSS -->
|
|
<link type="text/css" data-language="CSS3" rel="stylesheet" href="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/css/set" data-crossorigin="anonymous" charset="utf-8" />
|
|
|
|
</head>
|
|
<body>
|
|
|
|
<!-- Llamada desde una imagen -->
|
|
<img src="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/img/set" alt="KStats" title="KStats" />
|
|
<img src="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/image/set" alt="KStats" title="KStats" />
|
|
|
|
</body>
|
|
</html>
|
|
```
|
|
|
|
Y a continuación como se haría de forma manual desde HTML.
|
|
|
|
```html
|
|
|
|
<!-- Llamada mediante Link -->
|
|
<a href="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/text/set" target="_blank" title="KStats">KStats</a>
|
|
|
|
<!-- Llamada mediante formulario -->
|
|
<form method="get" action="https://kstats.k3y.pw/api/SbfXgp4r3fAtuthpzXdZw2JTLKZqZFYzLhWTkQiQr4kYWsrcZvvsbKrHt/{session}/text/set"></form>
|
|
|
|
```
|
|
|
|
### Estructura de la URL
|
|
|
|
La estructura de la URL se compone de varias variables las cuales las encapsulamos a continuación entre llaves:
|
|
|
|
```txt
|
|
https://{domain}/api/{token}/{session}/{response}/{action}/{id}
|
|
```
|
|
|
|
Cada una de estas variables indica lo siguiente:
|
|
|
|
- **domain**: Parámetro obligatorio que indica el dominio donde se encuentra el sitio Web del
|
|
servidor KStats al que estamos atacando.
|
|
- **token**: Parámetro obligatorio que indica el Token a usar contra el servidor KStats.
|
|
- **session**: Parámetro obligatorio pero automático donde sólo hemos de indicar la variable, el
|
|
cual contendrá el ID de la sesión actual a partir de una Cookie local evitando que éstas se crucen
|
|
entre distintos dominios.
|
|
- **response**: Modo de respuesta tras la acción de registrar la petición. Estos modos son los
|
|
siguientes:
|
|
- **[[ignore js]]**: Retorna el Script KStats en formato JavaScript 1.8.5.
|
|
- **[[ignore ecma]]**: Retorna el Script KStats en formato ECMA 2015.
|
|
- **img** o **image**: Retorna una simple imagen de 1x1 de forma simbólica para no dar error
|
|
contra una etiqueta HTML IMG.
|
|
- **[[ignore css]]**: Retorna un contenido CSS para poder usar la etiqueta HTML LINK.
|
|
- **[[ignore json]]**: Retorna el resultado del proceso en formato JSON.
|
|
- **test**: Hace un retornos sobre un entorno de pruebas.
|
|
- **action**: Método o acción a ejecutar en el servidor. Dichos métodos son los siguientes:
|
|
- **set**: Establece un nuevo registro de conexión o actualiza uno ya existente.
|
|
- **id**: ID de registro actual o existente que se usará para determinar el tiempo de conexión en
|
|
esa página Web concreta. *No analizar tiempo de inactividad*.
|
|
|
|
> [[! note NOTA]]: En caso de no tener ninguno de estos tipos de valor en la variable 'response',
|
|
éste retornará siempre un texto plano vacío.
|
|
|
|
> [[! importante]]: El servidor ha de tener firma SSL para poder realizar la operación asíncrona
|
|
segura por defecto.
|
|
|
|
[[html_data {
|
|
"title" : "KStats - Funcionamiento",
|
|
"url" : "https://kstats.k3y.pw/es/",
|
|
"author" : "KyMAN",
|
|
"since" : 20220320,
|
|
"version" : 20220320,
|
|
"key_words" : "kstats,stats,statistics,kyman,wmd,wmarkdown,documentación,funcionamiento",
|
|
"description" : "Funcionamiento del proyecto KStats.",
|
|
"project" : "KStats",
|
|
"logo" : "https://kstats.k3y.pw/images/KStats.png",
|
|
"language" : "es"
|
|
}]]
|