Documentació tècnica

Integració del widget

Càrrega automàtica (Plug & Play)

Implementació bàsica sense configuració addicional. El widget es carrega immediatament amb els valors per defecte.

No cal enllaçar el CSS a part: el script insereix automàticament el full d'estils (mateixa ruta base que el `.js`). Opcionalment podeu mantenir un `` al `` per descarregar CSS i JS en paral·lel.

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

Inicialització via API (Recomanat)

Permet definir retards i configuracions visuals personalitzades des de 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àmetres d'inicialització

Initialization parameters reference

Paràmetre	Tipus	Per defecte	Descripció
delay	Number	0	Temps en ms per a càrrega diferida.
position	String	'right'	Ubicació del botó: left o right.
dark_mode	String / Bool	'0'	1 per iniciar en mode fosc (si no hi ha memòria).
lang	String	'auto'	Codi ISO d'idioma (es, en, fr...).
autoInit	Boolean	true	Si és false, el widget espera a ser cridat manualment.
logo_url	URL	ADDAW logo	Imatge personalitzada per al footer del widget.
logo_link	URL	https://addaw.org/es	Destinació del clic al logo personalitzat.

Mètodes de control (API pública)

Utilitzeu aquestes ordres des de la consola o els vostres scripts per interactuar amb el widget un cop carregat.

Addaw.initialized — Verifica si el widget està actiu.

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

Addaw.destroy() — Elimina el widget completament del lloc.

Addaw.destroy();

Addaw.init({...}) — Re-inicialitza amb nova configuració.

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

Jerarquia de configuració

El widget segueix una lògica estricta de prioritat per aplicar els ajustos:

Control manual avançat

Per a aplicacions que requereixen un inici sota demanda (per exemple, després de prémer un botó específic):

<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ó de dominis

API REST perquè els empleats gestionin els dominis vinculats al seu compte i personalitzin l'aparença i el comportament del widget (paleta de colors i paràmetres equivalents a Addaw.init).

Endpoints disponibles (API empleado)

Employee API endpoints

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ó

Totes les peticions (excepte login) requereixen un token Bearer a la capçalera 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.

Donar d'alta un domini

Registra un nou domini vinculat al teu compte. L'operació és idempotent: si el domini ja existeix, no es 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);

Donar de baixa un domini

Desactiva un domini. No s'elimina, es marca com a inactiu.

$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);

Obtenir els meus dominis

Retorna la llista de dominis actius vinculats al teu compte.

$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);

Llistar colors disponibles

Retorna els noms i ids de les paletes de colors disponibles per personalitzar 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);

Personalitzar un domini

Desa la configuració del widget per a un domini: paleta de colors i, opcionalment, els mateixos paràmetres que admet Addaw.init (idioma, mode fosc, posició, inici automàtic, logos, retard i focus en modals). La primera vegada cal enviar l’id de paleta `color`; en sol·licituds posteriors es pot ometre i es conserven els colors desats, o actualitzar només alguns camps. Per anul·lar un valor emmagatzemat i tornar al comportament per defecte del widget, envieu la clau amb `null`.

Paràmetres del cos JSON

A més de `dominio`, podeu incloure els camps següents. Els noms coincideixen amb l’API del widget (`autoInit` i `focusOnContent`; també s’accepten `auto_init` i `focus_on_content`).

JSON body parameters for domain customization

Paràmetre	Tipus	Descripció
color	integer	Id. de paleta al llistat de colors disponibles. Obligatori la primera vegada que es configura el domini; si s’omet en actualitzacions posteriors, es mantenen els colors ja emmagatzemats.
lang	string | null	Codi ISO 639-1 de dues lletres (p. ex. `es`) o `null` per al valor per defecte del widget.
dark_mode	boolean | null	`true` / `false`, `1` / `0` o `null` (mode fosc inicial; respecta preferències ja desades al navegador).
position	string | null	`left`, `right` o `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` o `null` (inici automàtic en carregar l’script).
logo_url	string | null	URL del logo al peu (http, https, ruta absoluta o relativa `./`) o `null`.
logo_link	string | null	URL de destinació en fer clic al logo o `null`.
delay	integer | null	Enter en mil·lisegons entre 0 i 86400000 per retardar l’inici, o `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` o `null` (focus en el contingut de modals interns).

En servir `addaw-wba11y.min.js` des del CDN, el domini es detecta per la capçalera Referer. Si hi ha opcions desades per a aquest domini, es prepèn `window.AddawConfig = { ... };` a l’script perquè s’apliquin abans de l’arrencada automàtica (l’usuari pot seguir tenint prioritat mitjançant l’emmagatzematge local, segons la jerarquia de la secció 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;