Documentazione tecnica

Integrazione del widget

Caricamento automatico (Plug & Play)

Implementazione base senza configurazione aggiuntiva. Il widget si carica immediatamente con i valori predefiniti.

Non serve un CSS separato: lo script inserisce automaticamente il foglio di stili (stesso percorso base del `.js`). Opzionalmente puoi mantenere un `` nel `` per scaricare CSS e JS in parallelo.

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

Inizializzazione via API (Consigliato)

Consente di definire ritardi e configurazioni visive personalizzate da 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 di inizializzazione

Initialization parameters reference

Parametro	Tipo	Predefinito	Descrizione
delay	Number	0	Tempo in ms per il caricamento differito.
position	String	'right'	Posizione del pulsante: left o right.
dark_mode	String / Bool	'0'	1 per avviare in modalità scura (se non c'è memoria).
lang	String	'auto'	Codice ISO della lingua (es, en, fr...).
autoInit	Boolean	true	Se false, il widget attende di essere chiamato manualmente.
logo_url	URL	ADDAW logo	Immagine personalizzata per il footer del widget.
logo_link	URL	https://addaw.org/es	Destinazione del clic sul logo personalizzato.

Metodi di controllo (API pubblica)

Utilizza questi comandi dalla console o dai tuoi script per interagire con il widget una volta caricato.

Addaw.initialized — Verifica se il widget è attivo.

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

Addaw.destroy() — Rimuove completamente il widget dal sito.

Addaw.destroy();

Addaw.init({...}) — Re-inizializza con una nuova configurazione.

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

Gerarchia di configurazione

Il widget segue una logica di priorità rigorosa per applicare le impostazioni:

Controllo manuale avanzato

Per le applicazioni che richiedono un avvio su richiesta (ad esempio, dopo aver premuto un pulsante specifico):

<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 di gestione dei domini

API REST per consentire ai dipendenti di gestire i domini collegati al proprio account e personalizzare l'aspetto e il comportamento del widget (palette di colori e parametri equivalenti a 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}"

Autenticazione

Tutte le richieste (tranne login) richiedono un token Bearer nell'intestazione 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.

Registrare un dominio

Registra un nuovo dominio collegato al tuo account. L'operazione è idempotente: se il dominio esiste già, non viene duplicato.

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

Disattivare un dominio

Disattiva un dominio. Non viene eliminato, viene contrassegnato come inattivo.

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

Ottenere i miei domini

Restituisce l'elenco dei domini attivi collegati al tuo account.

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

Elencare i colori disponibili

Restituisce i nomi e gli ID delle palette di colori disponibili per personalizzare il 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);

Personalizzare un dominio

Salva la configurazione del widget per un dominio: palette di colori e, facoltativamente, gli stessi parametri supportati da Addaw.init (lingua, modalità scura, posizione, avvio automatico, loghi, ritardo e focus delle modali). La prima richiesta deve includere l’id palette `color`; in seguito può essere omesso per mantenere i colori salvati, oppure aggiornare solo alcuni campi. Per azzerare un valore memorizzato e usare i default del widget, inviare la chiave come `null`.

Parametri del corpo JSON

Oltre a `dominio` è possibile includere i campi seguenti. I nomi corrispondono all’API del widget (`autoInit` e `focusOnContent`; sono accettati anche `auto_init` e `focus_on_content`).

JSON body parameters for domain customization

Parametro	Tipo	Descrizione
color	integer	Id della palette nell’elenco colori disponibili. Obbligatorio la prima volta che si configura il dominio; se omesso negli aggiornamenti successivi, si mantengono i colori già salvati.
lang	string | null	Codice ISO 639-1 a due lettere (es. `es`) o `null` per il valore predefinito del widget.
dark_mode	boolean | null	`true` / `false`, `1` / `0` o `null` (modalità scura iniziale; rispetta le preferenze già salvate nel browser).
position	string | null	`left`, `right` o `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` o `null` (avvio automatico al caricamento dello script).
logo_url	string | null	URL del logo nel piè di pagina (http, https, percorso assoluto o relativo `./`) o `null`.
logo_link	string | null	URL di destinazione al clic sul logo o `null`.
delay	integer | null	Intero in millisecondi tra 0 e 86400000 per ritardare l’avvio, o `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` o `null` (focus sul contenuto delle modali interne).

Servendo `addaw-wba11y.min.js` dal CDN, il dominio è ricavato dall’intestazione Referer. Se esistono opzioni salvate per quel dominio, viene anteposto `window.AddawConfig = { ... };` allo script in modo che si applichino prima dell’avvio automatico (l’utente può avere ancora priorità tramite l’archiviazione locale, come nella gerarchia della sezione 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;