Tehnička dokumentacija

Integracija vidžeta

Automatsko učitavanje (Plug & Play)

Osnovna implementacija bez dodatne konfiguracije. Vidžet se učitava odmah sa podrazumevanim vrednostima.

Nije potreban poseban CSS link: skript automatski ubacuje stil (ista osnovna putanja kao za `.js`). Opciono zadržite `` u `` za paralelno preuzimanje.

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

Inicijalizacija putem API-ja (Preporučeno)

Omogućava definisanje kašnjenja i prilagođenih vizuelnih konfiguracija iz JavaScript-a.

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

Initialization parameters reference

Parametar	Tip	Podrazumevano	Opis
delay	Number	0	Vreme u ms za odloženo učitavanje.
position	String	'right'	Pozicija dugmeta: left ili right.
dark_mode	String / Bool	'0'	1 za pokretanje u tamnom režimu (ako nema memorije).
lang	String	'auto'	ISO kod jezika (es, en, fr...).
autoInit	Boolean	true	Ako je false, vidžet čeka da bude pozvan ručno.
logo_url	URL	ADDAW logo	Prilagođena slika za podnožje vidžeta.
logo_link	URL	https://addaw.org/es	Odredište klika na prilagođeni logo.

Metode upravljanja (javni API)

Koristite ove komande iz konzole ili vaših skripti za interakciju sa vidžetom nakon učitavanja.

Addaw.initialized — Proverava da li je vidžet aktivan.

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

Addaw.destroy() — Potpuno uklanja vidžet sa sajta.

Addaw.destroy();

Addaw.init({...}) — Ponovo inicijalizuje sa novom konfiguracijom.

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

Hijerarhija konfiguracije

Vidžet prati strogu logiku prioriteta za primenu podešavanja:

Napredno ručno upravljanje

Za aplikacije koje zahtevaju pokretanje na zahtev (na primer, nakon pritiska određenog dugmeta):

<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 za upravljanje domenima

REST API koji omogućava zaposlenima da upravljaju domenima povezanim sa njihovim nalogom i prilagode izgled i ponašanje vidžeta (paleta boja i parametri ekvivalentni 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}"

Autentifikacija

Svi zahtevi (osim login) zahtevaju Bearer token u Authorization zaglavlju.

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

Registracija domena

Registruje novi domen povezan sa vašim nalogom. Operacija je idempotentna: ako domen već postoji, neće biti dupliran.

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

Deaktivacija domena

Deaktivira domen. Ne briše se, označava se kao neaktivan.

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

Preuzmi moje domene

Vraća listu aktivnih domena povezanih sa vašim nalogom.

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

Lista dostupnih boja

Vraća imena i identifikatore dostupnih paleta boja za prilagođavanje vidžeta.

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

Prilagođavanje domena

Čuva podešavanja vidžeta za domen: paletu boja i po potrebi iste parametre kao Addaw.init (jezik, tamni režim, pozicija, automatsko pokretanje, logotipi, kašnjenje i fokus u modalima). Prvi zahtev mora da sadrži id palete `color`; kasnije može biti izostavljen da bi se sačuvale boje ili ažurirala samo neka polja. Pošaljite ključ kao `null` da obrišete sačuvanu vrednost.

Parametri JSON tela

Pored `dominio` možete uključiti sledeća polja. Imena odgovaraju API-ju vidžeta (`autoInit` i `focusOnContent`; prihvataju se i `auto_init` i `focus_on_content`).

JSON body parameters for domain customization

Parametar	Tip	Opis
color	integer	Id palete sa liste dostupnih boja. Obavezno pri prvom podešavanju domena; ako se kasnije izostavi, ostaju sačuvane boje.
lang	string | null	Dvoslovni ISO 639-1 kod (npr. `es`) ili `null` za podrazumevanu vrednost.
dark_mode	boolean | null	`true` / `false`, `1` / `0` ili `null` (početni tamni režim; poštuje sačuvana podešavanja pregledača).
position	string | null	`left`, `right` ili `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` ili `null` (automatsko pokretanje pri učitavanju skripte).
logo_url	string | null	URL logotipa u podnožju (http, https, apsolutna putanja ili relativna `./`) ili `null`.
logo_link	string | null	Ciljni URL pri kliku na logo ili `null`.
delay	integer | null	Ceo broj milisekundi od 0 do 86400000 za odlaganje pokretanja ili `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` ili `null` (fokus na sadržaj unutrašnjih modala).

Pri serviranju `addaw-wba11y.min.js` preko CDN-a domen se uzima iz Referer zaglavlja. Ako postoje sačuvane opcije za domen, ispred skripte se dodaje `window.AddawConfig = { ... };` da se primene pre automatskog pokretanja (korisnik i dalje može imati prednost putem lokalnog skladišta — pogledajte hijerarhiju u odeljku o vidžetu).

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