Documentación técnica

Integración del widget

Carga automática (Plug & Play)

Implementación básica sin configuración adicional. El widget se carga inmediatamente con los valores por defecto.

No es necesario enlazar el CSS por separado: el script inserta automáticamente la hoja de estilos del widget (misma ruta base que el `.js`). Opcionalmente puedes mantener un `` en el `` para descargar CSS y JS en paralelo.

<script defer src="https://api.addaw.org/addaw-wba11y.min.js"></script>

Inicialización vía API (Recomendado)

Permite definir retardos y configuraciones visuales personalizadas desde JavaScript.

<script defer src="https://api.addaw.org/addaw-wba11y.min.js"></script>
<script defer>
Addaw.init({
  delay: 5000,
  position: 'left',
  dark_mode: '1',
  lang: 'es',
  logo_url: 'https://yoursite.com/logo.png',
  logo_link: 'https://yoursite.com'
});
</script>

Parámetros de inicialización

Tabla de parámetros de inicialización del widget

Parámetro	Tipo	Por defecto	Descripción
delay	Number	0	Tiempo en ms para carga diferida.
position	String	'right'	Ubicación del botón: left o right.
dark_mode	String / Bool	'0'	1 para iniciar en modo oscuro (si no hay memoria).
lang	String	'auto'	Código ISO de idioma (es, en, fr...).
autoInit	Boolean	true	Si es false, el widget espera a ser llamado manualmente.
logo_url	URL	ADDAW logo	Imagen personalizada para el footer del widget.
logo_link	URL	https://addaw.org/es	Destino del clic en el logo personalizado.

Métodos de control (API pública)

Utilice estos comandos desde la consola o sus scripts para interactuar con el widget una vez cargado.

Addaw.initialized — Verifica si el widget está activo.

if (Addaw.initialized) {
  console.log('Widget is active');
}

Addaw.destroy() — Elimina el widget completamente del sitio.

Addaw.destroy();

Addaw.init({...}) — Re-inicializa con nueva configuración.

Addaw.init({
  position: 'left',
  dark_mode: '1',
  lang: 'en'
});

Jerarquía de configuración

El widget sigue una lógica estricta de prioridad para aplicar los ajustes:

Control manual avanzado

Para aplicaciones que requieren un inicio bajo demanda (por ejemplo, tras pulsar un botón específico):

<script>
window.AddawConfig = { autoInit: false };
</script>
<script defer src="https://api.addaw.org/addaw-wba11y.min.js"></script>
<script defer>
document.addEventListener('DOMContentLoaded', function() {
  Addaw.init({
    position: 'right',
    lang: 'es'
  });
});
</script>

API de gestión de dominios

API REST para que los empleados gestionen los dominios vinculados a su cuenta y personalicen la apariencia y el comportamiento del widget (paleta de colores y parámetros equivalentes a Addaw.init).

Endpoints disponibles (API empleado)

Tabla de endpoints de la API de empleado

Metodo	Endpoint	Descripcion
POST	/webService/ApiEmpleadoLogin	Autentica y devuelve access_token tipo Bearer.
GET	/webService/ApiEmpleadoPing	Comprueba validez del token y estado operativo.
POST	/webService/ApiEmpleadoDominioAlta	Alta de dominio (idempotente, con control de cuota/plan activo).
POST	/webService/ApiEmpleadoDominioBaja	Baja logica del dominio (marca activo=0).
GET	/webService/ApiEmpleadoMisDominios	Lista dominios activos con su configuracion efectiva.
GET	/webService/ApiEmpleadoColoresDisponibles	Lista paletas de color disponibles.
POST	/webService/ApiEmpleadoPersonalizarDominio	Guarda color y opciones del widget por dominio.

Quickstart backend (flujo recomendado)

1. Autentica con ApiEmpleadoLogin y guarda access_token.
2. Da de alta el dominio con ApiEmpleadoDominioAlta.
3. Consulta paletas con ApiEmpleadoColoresDisponibles.
4. Aplica configuracion con ApiEmpleadoPersonalizarDominio.
5. Valida el resultado con ApiEmpleadoMisDominios.

# Quickstart con curl (requiere jq)
TOKEN=$(curl -s -X POST "https://panel.addaw.org/webService/ApiEmpleadoLogin" \
  -H "Content-Type: application/json" \
  -d '{"correo":"tu_correo@ejemplo.com","pass":"tu_password"}' | jq -r '.access_token')

curl -s "https://panel.addaw.org/webService/ApiEmpleadoMisDominios" \
  -H "Authorization: Bearer ${TOKEN}"

Autenticación

Todas las peticiones (excepto login) requieren un token Bearer en la cabecera Authorization.

$ch = curl_init('https://panel.addaw.org/webService/ApiEmpleadoLogin');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'correo' => 'tu_correo@ejemplo.com',
    'pass'   => 'tu_password',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

$token = $response['access_token'];

Ping autenticado

Endpoint recomendado para verificar token y conectividad antes de operaciones de dominio.

curl -X GET "https://panel.addaw.org/webService/ApiEmpleadoPing" \
  -H "Authorization: Bearer $TOKEN"

Respuesta esperada: ok, datos del empleado y server_time.

Dar de alta un dominio

Registra un nuevo dominio vinculado a tu cuenta. La operación es idempotente: si el dominio ya existe, no se duplica.

$ch = curl_init('https://panel.addaw.org/webService/ApiEmpleadoDominioAlta');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['dominio' => 'www.example.com']));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Dar de baja un dominio

Desactiva un dominio. No se elimina, se marca como inactivo.

$ch = curl_init('https://panel.addaw.org/webService/ApiEmpleadoDominioBaja');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['dominio' => 'www.example.com']));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Obtener mis dominios

Devuelve la lista de dominios activos vinculados a tu cuenta.

$ch = curl_init('https://panel.addaw.org/webService/ApiEmpleadoMisDominios');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Listar colores disponibles

Devuelve los nombres e ids de las paletas de colores disponibles para personalizar el widget.

$ch = curl_init('https://panel.addaw.org/webService/ApiEmpleadoColoresDisponibles');
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

Personalizar un dominio

Guarda la configuración del widget para un dominio: paleta de colores y, de forma opcional, los mismos parámetros que admite Addaw.init (idioma, modo oscuro, posición, inicio automático, logos, retardo y foco en modales). La primera vez debe enviarse el id de paleta `color`; en peticiones posteriores puede omitirse y se conservan los colores ya guardados, o puede actualizarse solo parte de los campos. Para anular un valor almacenado y volver al comportamiento por defecto del widget, envíe la clave con `null`.

Parámetros del cuerpo JSON

Además de `dominio`, puede incluir los siguientes campos. Los nombres coinciden con la API del widget (`autoInit` y `focusOnContent`; también se aceptan `auto_init` y `focus_on_content`).

Parámetros JSON para personalizar el dominio

Parámetro	Tipo	Descripción
color	integer	Id. de paleta en el listado de colores disponibles. Obligatorio la primera vez que se configura el dominio; si se omite en actualizaciones posteriores, se mantienen los colores ya almacenados.
lang	string | null	Código ISO 639-1 de dos letras (p. ej. `es`) o `null` para el valor por defecto del widget.
dark_mode	boolean | null	`true` / `false`, `1` / `0` o `null` (modo oscuro inicial; respeta preferencias ya guardadas en el navegador).
position	string | null	`left`, `right` o `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` o `null` (inicio automático al cargar el script).
logo_url	string | null	URL del logo en el pie (http, https, ruta absoluta o relativa `./`) o `null`.
logo_link	string | null	URL de destino al pulsar el logo o `null`.
delay	integer | null	Entero en milisegundos entre 0 y 86400000 para retrasar el inicio, o `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` o `null` (foco en el contenido de modales internos).

Al servir `addaw-wba11y.min.js` desde el CDN, el dominio se detecta por la cabecera Referer. Si hay opciones guardadas para ese dominio, se antepone `window.AddawConfig = { ... };` al script, de modo que se apliquen antes del arranque automático (el usuario puede seguir teniendo prioridad vía almacenamiento local, según la jerarquía indicada en la sección del widget).

$ch = curl_init('https://panel.addaw.org/webService/ApiEmpleadoPersonalizarDominio');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer ' . $token,
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'dominio' => 'example.com',
    'color'   => 2,
    'lang'    => 'es',
    'position' => 'left',
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

// Ejemplo JavaScript con fetch
await fetch('https://panel.addaw.org/webService/ApiEmpleadoPersonalizarDominio', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dominio: 'example.com',
    color: 2,
    lang: 'es',
    position: 'left',
    autoInit: true,
    dark_mode: false,
    logo_url: 'https://example.com/logo.svg',
    logo_link: 'https://example.com',
    delay: 1200,
    focusOnContent: true
  })
});

Errores comunes y buenas practicas

• Si quieres limpiar un valor almacenado para un dominio, envia esa clave con null.
• Usa siempre HTTPS y valida la expiracion del token en tu backend.
• La alta de dominio es idempotente: si ya existe, no se duplica.
• Al servir el widget por CDN, verifica que el dominio de Referer coincide con el esperado.

Endpoint de estadisticas del widget

Ademas de la API de dominios, el widget envia agregados diarios de uso a:

Este endpoint acepta JSON con events y suma contadores por dominio/dia/accion. Solo procesa claves permitidas (por ejemplo panel_open, tool_*, profile_*, blind_*).

await fetch('https://api.addaw.org/webService/widgetInteractionStats', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    events: {
      panel_open: 1,
      panel_close: 1,
      tool_zoom: 3,
      profile_dyslexia: 1
    }
  })
});

Como obtener estadisticas por dominio

En la API publica actual no existe un endpoint ApiEmpleado* especifico para leer series historicas de estadisticas por dominio con Bearer. La consulta por dominio se resuelve hoy desde el panel interno.

1) Vista de analitica por dominio (panel)

Esta ruta requiere sesion de panel y muestra metricas de cargas e interacciones del dominio.

• desde: fecha inicio en formato YYYY-MM-DD.
• hasta: fecha fin en formato YYYY-MM-DD.
• Si no se envian, el panel usa por defecto los ultimos 30 dias.
• Rango maximo permitido por el backend: 90 dias.

# Ejemplo (navegador con sesion iniciada en panel)
https://panel.addaw.org/Widget/Dominios/example.com?desde=2026-04-01&hasta=2026-04-20

2) Metricas calculadas en esa vista

3) Consulta directa en BBDD (entornos internos)

-- Cargas diarias de un dominio
SELECT stat_date AS dia, SUM(request_count) AS total
FROM widget_domain_loads_daily
WHERE domain_normalized = 'example.com'
  AND stat_date BETWEEN '2026-04-01' AND '2026-04-20'
GROUP BY stat_date
ORDER BY stat_date;

-- Interacciones diarias de un dominio
SELECT stat_date AS dia, SUM(event_count) AS total
FROM widget_interaction_daily
WHERE domain_normalized = 'example.com'
  AND stat_date BETWEEN '2026-04-01' AND '2026-04-20'
GROUP BY stat_date
ORDER BY stat_date;

-- Top acciones por dominio
SELECT action_key, SUM(event_count) AS total
FROM widget_interaction_daily
WHERE domain_normalized = 'example.com'
  AND stat_date BETWEEN '2026-04-01' AND '2026-04-20'
GROUP BY action_key
ORDER BY total DESC
LIMIT 15;