Technische documentatie

Widget-integratie

Automatisch laden (Plug & Play)

Basisimplementatie zonder extra configuratie. De widget wordt onmiddellijk geladen met de standaardwaarden.

Geen aparte CSS-link nodig: het script voegt het stylesheet automatisch toe (zelfde basispad als de `.js`). Optioneel kunt u een `` in de `` houden om CSS en JS parallel te laden.

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

Initialisatie via API (Aanbevolen)

Maakt het mogelijk vertragingen en aangepaste visuele configuraties vanuit JavaScript te definiëren.

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

Initialisatieparameters

Initialization parameters reference

Parameter	Type	Standaard	Beschrijving
delay	Number	0	Tijd in ms voor uitgesteld laden.
position	String	'right'	Positie van de knop: left of right.
dark_mode	String / Bool	'0'	1 om in donkere modus te starten (als er geen geheugen is).
lang	String	'auto'	ISO-taalcode (es, en, fr...).
autoInit	Boolean	true	Als false, wacht de widget tot deze handmatig wordt aangeroepen.
logo_url	URL	ADDAW logo	Aangepaste afbeelding voor de voettekst van de widget.
logo_link	URL	https://addaw.org/es	Klikbestemming voor het aangepaste logo.

Besturingsmethoden (openbare API)

Gebruik deze opdrachten vanuit de console of uw scripts om met de widget te communiceren nadat deze is geladen.

Addaw.initialized — Controleert of de widget actief is.

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

Addaw.destroy() — Verwijdert de widget volledig van de site.

Addaw.destroy();

Addaw.init({...}) — Initialiseert opnieuw met nieuwe configuratie.

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

Configuratiehiërarchie

De widget volgt een strikte prioriteitslogica om instellingen toe te passen:

Geavanceerde handmatige besturing

Voor toepassingen die een start op aanvraag vereisen (bijvoorbeeld na het indrukken van een specifieke knop):

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

Domeinbeheer-API

REST-API waarmee medewerkers de aan hun account gekoppelde domeinen kunnen beheren en het uiterlijk en gedrag van de widget kunnen aanpassen (kleurenpalet en parameters gelijkwaardig aan 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}"

Authenticatie

Alle verzoeken (behalve login) vereisen een Bearer-token in de Authorization-header.

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

Een domein registreren

Registreert een nieuw domein dat aan uw account is gekoppeld. De bewerking is idempotent: als het domein al bestaat, wordt het niet gedupliceerd.

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

Een domein deactiveren

Deactiveert een domein. Het wordt niet verwijderd, maar als inactief gemarkeerd.

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

Mijn domeinen ophalen

Geeft de lijst van actieve domeinen terug die aan uw account zijn gekoppeld.

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

Beschikbare kleuren weergeven

Geeft de namen en ID's van beschikbare kleurenpaletten terug om de widget aan te passen.

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

Een domein aanpassen

Slaat widgetinstellingen op voor een domein: kleurenpalet en optioneel dezelfde parameters als Addaw.init (taal, donkere modus, positie, automatisch starten, logo's, vertraging en focus in modals). De eerste keer moet het palet-id `color` worden meegegeven; later kan dit worden weggelaten om opgeslagen kleuren te behouden, of kunt u alleen sommige velden bijwerken. Stuur een sleutel als `null` om een opgeslagen waarde te wissen en de widgetstandaarden te gebruiken.

JSON-bodyparameters

Naast `dominio` kunt u de volgende velden opnemen. De namen komen overeen met de widget-API (`autoInit` en `focusOnContent`; `auto_init` en `focus_on_content` worden ook geaccepteerd).

JSON body parameters for domain customization

Parameter	Type	Beschrijving
color	integer	Palet-id uit de lijst met beschikbare kleuren. Verplicht bij de eerste configuratie van het domein; als het later wordt weggelaten, blijven de opgeslagen kleuren behouden.
lang	string | null	Tweeletterige ISO 639-1-code (bijv. `es`) of `null` voor de widgetstandaard.
dark_mode	boolean | null	`true` / `false`, `1` / `0` of `null` (initiële donkere modus; respecteert eerder opgeslagen voorkeuren in de browser).
position	string | null	`left`, `right` of `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` of `null` (automatisch starten bij het laden van het script).
logo_url	string | null	URL van het voettekstlogo (http, https, absoluut pad of relatief `./`) of `null`.
logo_link	string | null	Doel-URL bij klik op het logo of `null`.
delay	integer | null	Geheel getal milliseconden tussen 0 en 86400000 om de start te vertragen, of `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` of `null` (focus op inhoud van interne modals).

Bij het uitserveren van `addaw-wba11y.min.js` via het CDN wordt het domein afgeleid van de Referer-header. Als er opties voor dat domein zijn opgeslagen, wordt `window.AddawConfig = { ... };` vóór het script geplaatst zodat ze vóór automatische start gelden (de gebruiker kan nog steeds voorrang hebben via lokale opslag, zie de hiërarchie in het widgetgedeelte).

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