Documentație tehnică

Integrarea widgetului

Încărcare automată (Plug & Play)

Implementare de bază fără configurare suplimentară. Widgetul se încarcă imediat cu valorile implicite.

Nu este nevoie de un link CSS separat: scriptul inserează automat foaia de stiluri (aceeași cale de bază ca `.js`). Opțional puteți păstra un `` în `` pentru descărcare în paralel.

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

Inițializare prin API (Recomandat)

Permite definirea întârzierilor și configurărilor vizuale personalizate din 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>

Parametri de inițializare

Initialization parameters reference

Parametru	Tip	Implicit	Descriere
delay	Number	0	Timp în ms pentru încărcare întârziată.
position	String	'right'	Poziția butonului: left sau right.
dark_mode	String / Bool	'0'	1 pentru a porni în modul întunecat (dacă nu există memorie).
lang	String	'auto'	Cod ISO al limbii (es, en, fr...).
autoInit	Boolean	true	Dacă este false, widgetul așteaptă să fie apelat manual.
logo_url	URL	ADDAW logo	Imagine personalizată pentru subsolul widgetului.
logo_link	URL	https://addaw.org/es	Destinația clicului pe logoul personalizat.

Metode de control (API public)

Utilizați aceste comenzi din consolă sau din scripturile dvs. pentru a interacționa cu widgetul după ce este încărcat.

Addaw.initialized — Verifică dacă widgetul este activ.

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

Addaw.destroy() — Elimină complet widgetul de pe site.

Addaw.destroy();

Addaw.init({...}) — Reinițializează cu o nouă configurare.

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

Ierarhia configurației

Widgetul urmează o logică strictă de prioritate pentru aplicarea setărilor:

Control manual avansat

Pentru aplicații care necesită pornire la cerere (de exemplu, după apăsarea unui buton specific):

<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 gestionare a domeniilor

API REST care permite angajaților să gestioneze domeniile asociate contului lor și să personalizeze aspectul și comportamentul widgetului (paletă de culori și parametri echivalenți cu 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}"

Autentificare

Toate cererile (cu excepția login) necesită un token Bearer în antetul 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.

Înregistrarea unui domeniu

Înregistrează un nou domeniu asociat contului dvs. Operația este idempotentă: dacă domeniul există deja, nu este duplicat.

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

Dezactivarea unui domeniu

Dezactivează un domeniu. Nu este șters, este marcat ca inactiv.

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

Obținerea domeniilor mele

Returnează lista domeniilor active asociate contului dvs.

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

Listarea culorilor disponibile

Returnează numele și ID-urile paletelor de culori disponibile pentru personalizarea widgetului.

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

Personalizarea unui domeniu

Stochează setările widgetului pentru un domeniu: paleta de culori și, opțional, aceiași parametri ca Addaw.init (limbă, mod întunecat, poziție, pornire automată, logo-uri, întârziere și focalizare în modale). Prima cerere trebuie să includă id-ul paletei `color`; ulterior poate fi omis pentru a păstra culorile salvate sau se pot actualiza doar unele câmpuri. Pentru așterge o valoare salvată, trimiteți cheia ca `null`.

Parametri în corpul JSON

Pe lângă `dominio` puteți include următoarele câmpuri. Numele corespund API-ului widgetului (`autoInit` și `focusOnContent`; sunt acceptate și `auto_init` și `focus_on_content`).

JSON body parameters for domain customization

Parametru	Tip	Descriere
color	integer	Id. paletă din lista de culori disponibile. Obligatoriu la prima configurare a domeniului; dacă omiteți la actualizări ulterioare, se păstrează culorile stocate.
lang	string | null	Cod ISO 639-1 din două litere (ex. `es`) sau `null` pentru valoarea implicită.
dark_mode	boolean | null	`true` / `false`, `1` / `0` sau `null` (mod întunecat inițial; respectă preferințele deja salvate în browser).
position	string | null	`left`, `right` sau `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` sau `null` (pornire automată la încărcarea scriptului).
logo_url	string | null	URL logo în subsol (http, https, cale absolută sau relativă `./`) sau `null`.
logo_link	string | null	URL destinație la clic pe logo sau `null`.
delay	integer | null	Întreg milisecunde între 0 și 86400000 pentru întârzierea pornirii sau `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` sau `null` (focalizare pe conținutul modalelor interne).

La servirea `addaw-wba11y.min.js` prin CDN, domeniul se ia din antetul Referer. Dacă există opțiuni salvate pentru acel domeniu, se adaugă `window.AddawConfig = { ... };` înaintea scriptului pentru a se aplica înainte de pornirea automată (utilizatorul poate avea în continuare prioritate prin stocarea locală — vezi ierarhia din secțiunea 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;