Τεχνική τεκμηρίωση

Ενσωμάτωση widget

Αυτόματη φόρτωση (Plug & Play)

Βασική υλοποίηση χωρίς πρόσθετη ρύθμιση. Το widget φορτώνεται αμέσως με τις προεπιλεγμένες τιμές.

Δεν χρειάζεται ξεχωριστό CSS: το script εισάγει αυτόματα το stylesheet (ίδια βασική διαδρομή με το `.js`). Προαιρετικά κρατήστε `` στο `` για παράλληλη λήψη.

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

Αρχικοποίηση μέσω API (Συνιστάται)

Επιτρέπει τον ορισμό καθυστερήσεων και προσαρμοσμένων οπτικών ρυθμίσεων από 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>

Παράμετροι αρχικοποίησης

Initialization parameters reference

Παράμετρος	Τύπος	Προεπιλογή	Περιγραφή
delay	Number	0	Χρόνος σε ms για καθυστερημένη φόρτωση.
position	String	'right'	Θέση κουμπιού: left ή right.
dark_mode	String / Bool	'0'	1 για εκκίνηση σε σκοτεινή λειτουργία (αν δεν υπάρχει μνήμη).
lang	String	'auto'	Κωδικός γλώσσας ISO (es, en, fr...).
autoInit	Boolean	true	Αν είναι false, το widget αναμένει χειροκίνητη κλήση.
logo_url	URL	ADDAW logo	Προσαρμοσμένη εικόνα για το υποσέλιδο του widget.
logo_link	URL	https://addaw.org/es	Προορισμός κλικ στο προσαρμοσμένο λογότυπο.

Μέθοδοι ελέγχου (δημόσιο API)

Χρησιμοποιήστε αυτές τις εντολές από την κονσόλα ή τα scripts σας για αλληλεπίδραση με το widget μετά τη φόρτωσή του.

Addaw.initialized — Ελέγχει αν το widget είναι ενεργό.

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

Addaw.destroy() — Αφαιρεί πλήρως το widget από τον ιστότοπο.

Addaw.destroy();

Addaw.init({...}) — Επαναρχικοποιεί με νέα διαμόρφωση.

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

Ιεραρχία ρυθμίσεων

Το widget ακολουθεί αυστηρή λογική προτεραιότητας για την εφαρμογή ρυθμίσεων:

Προηγμένος χειροκίνητος έλεγχος

Για εφαρμογές που απαιτούν εκκίνηση κατ' απαίτηση (π.χ. μετά το πάτημα ενός συγκεκριμένου κουμπιού):

<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 διαχείρισης τομέων

REST API για τη διαχείριση τομέων συνδεδεμένων με τον λογαριασμό των υπαλλήλων και την προσαρμογή της εμφάνισης και της συμπεριφοράς του widget (χρωματική παλέτα και παράμετροι ισοδύναμες με το 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}"

Αυθεντικοποίηση

Όλα τα αιτήματα (εκτός login) απαιτούν ένα Bearer token στην κεφαλίδα 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.

Εγγραφή τομέα

Καταχωρεί έναν νέο τομέα συνδεδεμένο με τον λογαριασμό σας. Η λειτουργία είναι ανεξάρτητη: αν ο τομέας υπάρχει ήδη, δεν αντιγράφεται.

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

Απενεργοποίηση τομέα

Απενεργοποιεί έναν τομέα. Δεν διαγράφεται, επισημαίνεται ως ανενεργός.

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

Λήψη των τομέων μου

Επιστρέφει τη λίστα ενεργών τομέων συνδεδεμένων με τον λογαριασμό σας.

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

Λίστα διαθέσιμων χρωμάτων

Επιστρέφει τα ονόματα και τα αναγνωριστικά των διαθέσιμων χρωματικών παλετών για την προσαρμογή του widget.

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

Προσαρμογή τομέα

Αποθηκεύει τις ρυθμίσεις widget για έναν τομέα: χρωματική παλέτα και προαιρετικά τις ίδιες παραμέτρους με το Addaw.init (γλώσσα, σκοτεινή λειτουργία, θέση, αυτόματη εκκίνηση, λογότυπα, καθυστέρηση και εστίαση σε modals). Το πρώτο αίτημα πρέπει να περιλαμβάνει το id παλέτας `color`· αργότερα μπορεί να παραλειφθεί για διατήρηση των αποθηκευμένων χρωμάτων ή ενημέρωση μόνο ορισμένων πεδίων. Στείλτε το κλειδί ως `null` για εκκαθάριση αποθηκευμένης τιμής.

Παράμετροι σώματος JSON

Εκτός από `dominio` μπορείτε να συμπεριλάβετε τα ακόλουθα πεδία. Τα ονόματα αντιστοιχούν στο API του widget (`autoInit` και `focusOnContent`· γίνονται δεκτά και `auto_init` και `focus_on_content`).

JSON body parameters for domain customization

Παράμετρος	Τύπος	Περιγραφή
color	integer	Αναγνωριστικό παλέτας από τη λίστα διαθέσιμων χρωμάτων. Υποχρεωτικό την πρώτη ρύθμιση· αν παραλειφθεί αργότερα, διατηρούνται τα αποθηκευμένα χρώματα.
lang	string | null	Δίγραμμος κωδικός ISO 639-1 (π.χ. `es`) ή `null` για την προεπιλογή.
dark_mode	boolean | null	`true` / `false`, `1` / `0` ή `null` (αρχική σκοτεινή λειτουργία· σέβεται αποθηκευμένες προτιμήσεις περιηγητή).
position	string | null	`left`, `right` ή `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` ή `null` (αυτόματη εκκίνηση κατά τη φόρτωση του script).
logo_url	string | null	URL λογότυπου υποσέλιδου (http, https, απόλυτη διαδρομή ή σχετική `./`) ή `null`.
logo_link	string | null	URL προορισμού κατά το κλικ στο λογότυπο ή `null`.
delay	integer | null	Ακέραιος χιλιοστά δευτερολέπτου 0–86400000 για καθυστέρηση εκκίνησης ή `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` ή `null` (εστίαση στο περιεχόμενο εσωτερικών modals).

Κατά την παράδοση του `addaw-wba11y.min.js` μέσω CDN, ο τομέας προκύπτει από την κεφαλίδα Referer. Αν υπάρχουν αποθηκευμένες επιλογές για τον τομέα, προστίθεται `window.AddawConfig = { ... };` πριν το script ώστε να εφαρμοστούν πριν την αυτόματη εκκίνηση (ο χρήστης μπορεί ακόμη να έχει προτεραιότητα μέσω τοπικής αποθήκευσης — δείτε την ιεραρχία στην ενότητα 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;