Teknisk dokumentation

Widget-integration

Automatisk indlæsning (Plug & Play)

Grundlæggende implementering uden yderligere konfiguration. Widgetten indlæses straks med standardværdier.

Du behøver ikke et separat CSS-link: scriptet indsætter automatisk stylesheet (samme basissti som `.js`). Du kan valgfrit beholde et `` i `` for parallel download.

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

Initialisering via API (Anbefalet)

Gør det muligt at definere forsinkelser og tilpassede visuelle konfigurationer fra 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>

Initialiseringsparametre

Initialization parameters reference

Parameter	Type	Standard	Beskrivelse
delay	Number	0	Tid i ms for forsinket indlæsning.
position	String	'right'	Knapplacering: left eller right.
dark_mode	String / Bool	'0'	1 for at starte i mørk tilstand (hvis ingen hukommelse).
lang	String	'auto'	ISO-sprogkode (es, en, fr...).
autoInit	Boolean	true	Hvis false, venter widgetten på at blive kaldt manuelt.
logo_url	URL	ADDAW logo	Tilpasset billede til widgettens sidefod.
logo_link	URL	https://addaw.org/es	Klikmål for det tilpassede logo.

Kontrolmetoder (offentlig API)

Brug disse kommandoer fra konsollen eller dine scripts til at interagere med widgetten, efter den er indlæst.

Addaw.initialized — Kontrollerer, om widgetten er aktiv.

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

Addaw.destroy() — Fjerner widgetten fuldstændigt fra sitet.

Addaw.destroy();

Addaw.init({...}) — Geninitialiserer med ny konfiguration.

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

Konfigurationshierarki

Widgetten følger en streng prioritetslogik for at anvende indstillinger:

Avanceret manuel styring

Til applikationer, der kræver start efter behov (f.eks. efter at have trykket på en bestemt knap):

<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>

Domæneadministrations-API

REST-API, der giver medarbejdere mulighed for at administrere domæner tilknyttet deres konto og tilpasse widgettens udseende og adfærd (farvepalet og parametre svarende til 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}"

Autentificering

Alle anmodninger (undtagen login) kræver et Bearer-token i Authorization-headeren.

$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.

Registrer et domæne

Registrerer et nyt domæne tilknyttet din konto. Operationen er idempotent: hvis domænet allerede eksisterer, duplikeres det ikke.

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

Deaktiver et domæne

Deaktiverer et domæne. Det slettes ikke, det markeres som inaktivt.

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

Hent mine domæner

Returnerer listen over aktive domæner tilknyttet din konto.

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

Vis tilgængelige farver

Returnerer navne og ID'er på tilgængelige farvepaletter til tilpasning af widgetten.

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

Tilpas et domæne

Gemmer widget-indstillinger for et domæne: farvepalet og valgfrit de samme parametre som Addaw.init (sprog, mørk tilstand, position, automatisk start, logoer, forsinkelse og fokus i modaler). Første anmodning skal indeholde palet-id `color`; senere kan det udelades for at beholde gemte farver, eller kun opdatere valgte felter. Send nøglen som `null` for at nulstille en gemt værdi.

JSON-body-parametre

Ud over `dominio` kan du inkludere følgende felter. Navnene matcher widget-API'et (`autoInit` og `focusOnContent`; `auto_init` og `focus_on_content` accepteres også).

JSON body parameters for domain customization

Parameter	Type	Beskrivelse
color	integer	Palet-id fra listen over tilgængelige farver. Påkrævet første gang domænet konfigureres; udelades det senere, bevares de gemte farver.
lang	string | null	To-bogstavs ISO 639-1-kode (fx `es`) eller `null` for standard.
dark_mode	boolean | null	`true` / `false`, `1` / `0` eller `null` (indledende mørk tilstand; respekterer gemte browserpræferencer).
position	string | null	`left`, `right` eller `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` eller `null` (automatisk start ved indlæsning af scriptet).
logo_url	string | null	URL til footer-logo (http, https, absolut sti eller relativ `./`) eller `null`.
logo_link	string | null	Destinations-URL ved klik på logo eller `null`.
delay	integer | null	Heltal millisekunder mellem 0 og 86400000 for at forsinke start, eller `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` eller `null` (fokus på indhold i interne modaler).

Når `addaw-wba11y.min.js` leveres via CDN, hentes domænet fra Referer-headeren. Hvis der er gemte indstillinger for domænet, foranstilles `window.AddawConfig = { ... };` scriptet, så de gælder før automatisk start (brugeren kan stadig have forrang via lokal lagring — se hierarkiet i widget-afsnittet).

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