Technická dokumentace

Integrace widgetu

Automatické načítání (Plug & Play)

Základní implementace bez další konfigurace. Widget se načte okamžitě s výchozími hodnotami.

Není potřeba samostatný odkaz na CSS: skript styly vloží automaticky (stejná základní cesta jako `.js`). Volitelně můžete v `` nechat `` pro paralelní stahování.

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

Inicializace přes API (Doporučeno)

Umožňuje definovat zpoždění a vlastní vizuální konfigurace z JavaScriptu.

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

Parametry inicializace

Initialization parameters reference

Parametr	Typ	Výchozí	Popis
delay	Number	0	Čas v ms pro zpožděné načítání.
position	String	'right'	Pozice tlačítka: left nebo right.
dark_mode	String / Bool	'0'	1 pro spuštění v tmavém režimu (pokud není paměť).
lang	String	'auto'	ISO kód jazyka (es, en, fr...).
autoInit	Boolean	true	Pokud false, widget čeká na ruční zavolání.
logo_url	URL	ADDAW logo	Vlastní obrázek pro zápatí widgetu.
logo_link	URL	https://addaw.org/es	Cíl kliknutí na vlastní logo.

Metody ovládání (veřejné API)

Použijte tyto příkazy z konzole nebo svých skriptů pro interakci s widgetem po jeho načtení.

Addaw.initialized — Ověřuje, zda je widget aktivní.

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

Addaw.destroy() — Widget zcela odstraní ze stránky.

Addaw.destroy();

Addaw.init({...}) — Znovu inicializuje s novou konfigurací.

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

Hierarchie konfigurace

Widget dodržuje přísnou logiku priorit pro aplikaci nastavení:

Pokročilé ruční ovládání

Pro aplikace vyžadující spuštění na vyžádání (například po stisknutí konkrétního tlačítka):

<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 pro správu domén

REST API umožňující zaměstnancům spravovat domény propojené s jejich účtem a přizpůsobit vzhled i chování widgetu (barevná paleta a parametry ekvivalentní 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}"

Autentizace

Všechny požadavky (kromě login) vyžadují Bearer token v hlavičce 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.

Registrace domény

Zaregistruje novou doménu propojenou s vaším účtem. Operace je idempotentní: pokud doména již existuje, neduplikuje se.

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

Deaktivace domény

Deaktivuje doménu. Nesmaže se, označí se jako neaktivní.

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

Získat mé domény

Vrací seznam aktivních domén propojených s vaším účtem.

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

Seznam dostupných barev

Vrací názvy a identifikátory dostupných barevných palet pro přizpůsobení widgetu.

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

Přizpůsobení domény

Ukládá konfiguraci widgetu pro doménu: barevnou paletu a volitelně stejné parametry jako Addaw.init (jazyk, tmavý režim, pozice, automatické spuštění, loga, zpoždění a zaměření modálů). Při prvním požadavku je nutné uvést ID palety `color`; později lze vynechat a zachovat uložené barvy, nebo aktualizovat jen některá pole. Chcete-li uloženou hodnotu zrušit, pošlete klíč jako `null`.

Parametry těla JSON

Kromě `dominio` můžete přidat následující pole. Názvy odpovídají API widgetu (`autoInit` a `focusOnContent`; přijímány jsou i `auto_init` a `focus_on_content`).

JSON body parameters for domain customization

Parametr	Typ	Popis
color	integer	ID palety ze seznamu dostupných barev. Povinné při prvním nastavení domény; při pozdějších aktualizacích vynecháte-li ho, zůstanou uložené barvy.
lang	string | null	Dvoupísmenný kód ISO 639-1 (např. `es`) nebo `null` pro výchozí hodnotu widgetu.
dark_mode	boolean | null	`true` / `false`, `1` / `0` nebo `null` (počáteční tmavý režim; respektuje uložené předvolby prohlížeče).
position	string | null	`left`, `right` nebo `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` nebo `null` (automatické spuštění při načtení skriptu).
logo_url	string | null	URL loga v zápatí (http, https, absolutní cesta nebo relativní `./`) nebo `null`.
logo_link	string | null	Cílová URL po kliknutí na logo nebo `null`.
delay	integer | null	Celé číslo milisekund 0–86400000 pro zpoždění startu nebo `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` nebo `null` (zaměření obsahu vnitřních modálů).

Při servírování `addaw-wba11y.min.js` z CDN se doména bere z hlavičky Referer. Jsou-li pro doménu uloženy volby, před skript se vloží `window.AddawConfig = { ... };`, aby se platily před automatickým spuštěním (uživatel může mít přednost přes lokální úložiště — viz hierarchie v sekci widgetu).

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