Műszaki dokumentáció

Widget integráció

Automatikus betöltés (Plug & Play)

Alapvető implementáció további konfiguráció nélkül. A widget azonnal betöltődik az alapértelmezett értékekkel.

Nem kell külön CSS hivatkozás: a szkript automatikusan beszúrja a stíluslapot (ugyanaz az alapútvonal, mint a `.js`-nél). Opcionálisan megtarthat egy `` elemet a ``-ben a párhuzamos letöltéshez.

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

Inicializálás API-n keresztül (Ajánlott)

Lehetővé teszi késleltetések és egyéni vizuális konfigurációk meghatározását JavaScript-ből.

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

Inicializálási paraméterek

Initialization parameters reference

Paraméter	Típus	Alapértelmezett	Leírás
delay	Number	0	Idő ms-ban a késleltetett betöltéshez.
position	String	'right'	Gomb helyzete: left vagy right.
dark_mode	String / Bool	'0'	1 a sötét módban való indításhoz (ha nincs memória).
lang	String	'auto'	ISO nyelvkód (es, en, fr...).
autoInit	Boolean	true	Ha false, a widget kézi hívásra vár.
logo_url	URL	ADDAW logo	Egyéni kép a widget láblécéhez.
logo_link	URL	https://addaw.org/es	Az egyéni logó kattintási célja.

Vezérlési módszerek (nyilvános API)

Használja ezeket a parancsokat a konzolból vagy szkriptjeiből a widgettel való interakcióhoz a betöltés után.

Addaw.initialized — Ellenőrzi, hogy a widget aktív-e.

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

Addaw.destroy() — Teljesen eltávolítja a widgetet az oldalról.

Addaw.destroy();

Addaw.init({...}) — Újrainicializálja új konfigurációval.

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

Konfigurációs hierarchia

A widget szigorú prioritási logikát követ a beállítások alkalmazásához:

Fejlett kézi vezérlés

Igény szerinti indítást igénylő alkalmazásokhoz (például egy adott gomb megnyomása után):

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

Domainkezelési API

REST API, amely lehetővé teszi az alkalmazottak számára a fiókjukhoz kapcsolt domainek kezelését és a widget megjelenésének és viselkedésének testreszabását (színpaletta és az Addaw.init-hez hasonló paraméterek).

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

Hitelesítés

Minden kérés (a login kivételével) Bearer tokent igényel az Authorization fejlécben.

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

Domain regisztrálása

Regisztrál egy új domaint a fiókjához kapcsolva. A művelet idempotens: ha a domain már létezik, nem duplikálódik.

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

Domain deaktiválása

Deaktiválja a domaint. Nem törlődik, inaktívként jelölődik meg.

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

Saját domainek lekérése

A fiókjához kapcsolt aktív domainek listáját adja vissza.

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

Elérhető színek listázása

A widget testreszabásához elérhető színpaletták neveit és azonosítóit adja vissza.

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

Domain testreszabása

Widget-beállításokat tárol egy domainhez: színpalettát és opcionálisan ugyanazokat a paramétereket, mint az Addaw.init (nyelv, sötét mód, pozíció, automatikus indítás, logók, késleltetés és modális fókusz). Az első kérésben kötelező a `color` palettaazonosító; később elhagyható a mentett színek megőrzéséhez, vagy csak egyes mezők frissíthetők. Mentett érték törléséhez küldje a kulcsot `null` értékkel.

JSON törzs paraméterei

A `dominio` mellett az alábbi mezők adhatók meg. A nevek megegyeznek a widget API-val (`autoInit` és `focusOnContent`; `auto_init` és `focus_on_content` is elfogadott).

JSON body parameters for domain customization

Paraméter	Típus	Leírás
color	integer	Palettaazonosító az elérhető színek listáján. Kötelező első konfiguráláskor; később elhagyva a mentett színek megmaradnak.
lang	string | null	Kétbetűs ISO 639-1 kód (pl. `es`) vagy `null` az alapértelmezéshez.
dark_mode	boolean | null	`true` / `false`, `1` / `0` vagy `null` (kezdeti sötét mód; tiszteletben tartja a böngészőben mentett beállításokat).
position	string | null	`left`, `right` vagy `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` vagy `null` (automatikus indítás a szkript betöltésekor).
logo_url	string | null	Lábléc logó URL-je (http, https, abszolút útvonal vagy relatív `./`) vagy `null`.
logo_link	string | null	Cél URL a logóra kattintva vagy `null`.
delay	integer | null	Egész milliszekundum 0–86400000 között a késleltetéshez vagy `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` vagy `null` (fókusz belső modálok tartalmán).

Az `addaw-wba11y.min.js` CDN-ről történő kiszolgálásakor a domain a Referer fejlécből kerül kiolvasásra. Ha vannak mentett beállítások a domainhez, a szkript elé `window.AddawConfig = { ... };` kerül, hogy az automatikus indítás előtt érvényesüljenek (a felhasználó továbbra is elsőbbséget kaphat helyi tárolással — lásd a widget szakasz hierarchiáját).

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