Documentación técnica

Integración do widget

Carga automática (Plug & Play)

Implementación básica sen configuración adicional. O widget cárgase inmediatamente cos valores por defecto.

Non é necesario ligar o CSS por separado: o script insire automaticamente a folla de estilos (mesma ruta base que o `.js`). Opcionalmente podes manter un `` no `` para descargar CSS e JS en paralelo.

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

Inicialización vía API (Recomendado)

Permite definir atrasos e configuracións visuais 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

Initialization parameters reference

Parámetro	Tipo	Por defecto	Descrición
delay	Number	0	Tempo en ms para carga diferida.
position	String	'right'	Ubicación do botón: left ou right.
dark_mode	String / Bool	'0'	1 para iniciar en modo escuro (se non hai memoria).
lang	String	'auto'	Código ISO de idioma (es, en, fr...).
autoInit	Boolean	true	Se é false, o widget espera a ser chamado manualmente.
logo_url	URL	ADDAW logo	Imaxe personalizada para o footer do widget.
logo_link	URL	https://addaw.org/es	Destino do clic no logo personalizado.

Métodos de control (API pública)

Utilice estes comandos desde a consola ou os seus scripts para interactuar co widget unha vez cargado.

Addaw.initialized — Verifica se o widget está activo.

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

Addaw.destroy() — Elimina o widget completamente do sitio.

Addaw.destroy();

Addaw.init({...}) — Re-inicializa cunha nova configuración.

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

Xerarquía de configuración

O widget segue unha lóxica estrita de prioridade para aplicar os axustes:

Control manual avanzado

Para aplicacións que requiren un inicio baixo demanda (por exemplo, tras premer 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 xestión de dominios

API REST para que os empregados xestionen os dominios vinculados á súa conta e personalicen a aparencia e o comportamento do widget (paleta de cores e parámetros equivalentes 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ón

Todas as peticións (excepto login) requiren un token Bearer na cabeceira 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

Rexistra un novo dominio vinculado á túa conta. A operación é idempotente: se o dominio xa existe, non 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 baixa un dominio

Desactiva un dominio. Non se elimina, márcese 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);

Obter os meus dominios

Devolve a lista de dominios activos vinculados á túa conta.

$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 cores dispoñibles

Devolve os nomes e ids das paletas de cores dispoñibles para personalizar o 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

Garda a configuración do widget para un dominio: paleta de cores e, opcionalmente, os mesmos parámetros que admite Addaw.init (idioma, modo escuro, posición, inicio automático, logos, atraso e foco en modais). A primeira vez debe enviarse o id de paleta `color`; nas peticións posteriores pode omitirse e consérvanse as cores xa gardadas, ou actualizar só parte dos campos. Para anular un valor almacenado e volver ao comportamento por defecto do widget, envíe a clave con `null`.

Parámetros do corpo JSON

Ademais de `dominio`, pode incluír os seguintes campos. Os nomes coinciden coa API do widget (`autoInit` e `focusOnContent`; tamén se aceptan `auto_init` e `focus_on_content`).

JSON body parameters for domain customization

Parámetro	Tipo	Descrición
color	integer	Id. de paleta na listaxe de cores dispoñibles. Obrigatorio a primeira vez que se configura o dominio; se se omite en actualizacións posteriores, mantéñense as cores xa almacenadas.
lang	string | null	Código ISO 639-1 de dúas letras (p. ex. `es`) ou `null` para o valor por defecto do widget.
dark_mode	boolean | null	`true` / `false`, `1` / `0` ou `null` (modo escuro inicial; respecta preferencias xa gardadas no navegador).
position	string | null	`left`, `right` ou `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` ou `null` (inicio automático ao cargar o script).
logo_url	string | null	URL do logo no rodapé (http, https, ruta absoluta ou relativa `./`) ou `null`.
logo_link	string | null	URL de destino ao premer o logo ou `null`.
delay	integer | null	Enteiro en milisegundos entre 0 e 86400000 para atrasar o inicio, ou `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` ou `null` (foco no contido de modais internos).

Ao servir `addaw-wba11y.min.js` dende o CDN, o dominio detéctase pola cabeceira Referer. Se hai opcións gardadas para ese dominio, prepónese `window.AddawConfig = { ... };` ao script para que se apliquen antes do arranque automático (o usuario pode seguir tendo prioridade vía almacenamento local, segundo a xerarquía da sección do 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;