Technische Dokumentation

Widget-Integration

Automatisches Laden (Plug & Play)

Grundlegende Implementierung ohne zusätzliche Konfiguration. Das Widget wird sofort mit den Standardwerten geladen.

Ein separates CSS ist nicht nötig: Das Skript fügt das Stylesheet automatisch ein (gleicher Basis-Pfad wie die `.js`). Optional können Sie im `` ein `` behalten, um JS und CSS parallel zu laden.

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

Initialisierung über API (Empfohlen)

Ermöglicht die Definition von Verzögerungen und benutzerdefinierten visuellen Konfigurationen aus 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>

Initialisierungsparameter

Initialization parameters reference

Parameter	Typ	Standard	Beschreibung
delay	Number	0	Zeit in ms für verzögertes Laden.
position	String	'right'	Position der Schaltfläche: left oder right.
dark_mode	String / Bool	'0'	1 um im Dunkelmodus zu starten (falls kein Speicher vorhanden).
lang	String	'auto'	ISO-Sprachcode (es, en, fr...).
autoInit	Boolean	true	Wenn false, wartet das Widget auf einen manuellen Aufruf.
logo_url	URL	ADDAW logo	Benutzerdefiniertes Bild für die Fußzeile des Widgets.
logo_link	URL	https://addaw.org/es	Klickziel für das benutzerdefinierte Logo.

Steuerungsmethoden (öffentliche API)

Verwenden Sie diese Befehle in der Konsole oder in Ihren Skripten, um mit dem Widget nach dem Laden zu interagieren.

Addaw.initialized — Prüft, ob das Widget aktiv ist.

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

Addaw.destroy() — Entfernt das Widget vollständig von der Website.

Addaw.destroy();

Addaw.init({...}) — Reinitialisiert mit neuer Konfiguration.

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

Konfigurationshierarchie

Das Widget folgt einer strengen Prioritätslogik zur Anwendung der Einstellungen:

Erweiterte manuelle Steuerung

Für Anwendungen, die einen bedarfsgesteuerten Start erfordern (z. B. nach dem Drücken einer bestimmten Schaltfläche):

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

Domainverwaltungs-API

REST-API, mit der Mitarbeiter die mit ihrem Konto verknüpften Domains verwalten und das Erscheinungsbild sowie das Verhalten des Widgets anpassen können (Farbpalette und Parameter wie bei 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}"

Authentifizierung

Alle Anfragen (außer Login) erfordern ein Bearer-Token im Authorization-Header.

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

Eine Domain registrieren

Registriert eine neue Domain, die mit Ihrem Konto verknüpft ist. Der Vorgang ist idempotent: Existiert die Domain bereits, wird sie nicht dupliziert.

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

Eine Domain deaktivieren

Deaktiviert eine Domain. Sie wird nicht gelöscht, sondern als inaktiv markiert.

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

Meine Domains abrufen

Gibt die Liste der aktiven Domains zurück, die mit Ihrem Konto verknüpft sind.

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

Verfügbare Farben auflisten

Gibt die Namen und IDs der verfügbaren Farbpaletten zur Anpassung des Widgets zurück.

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

Eine Domain anpassen

Speichert die Widget-Konfiguration für eine Domain: Farbpalette und optional dieselben Parameter wie Addaw.init (Sprache, Dunkelmodus, Position, Auto-Start, Logos, Verzögerung und Fokus in Modals). Beim ersten Aufruf muss die Paletten-ID `color` angegeben werden; später kann sie weggelassen werden, um gespeicherte Farben zu behalten, oder nur einzelne Felder werden aktualisiert. Um einen gespeicherten Wert zu löschen und die Widget-Standards zu nutzen, senden Sie den Schlüssel als `null`.

JSON-Body-Parameter

Zusätzlich zu `dominio` können Sie folgende Felder angeben. Die Namen entsprechen der Widget-API (`autoInit` und `focusOnContent`; `auto_init` und `focus_on_content` werden ebenfalls akzeptiert).

JSON body parameters for domain customization

Parameter	Typ	Beschreibung
color	integer	Paletten-ID aus der Liste verfügbarer Farben. Beim ersten Einrichten der Domain erforderlich; wird sie später weggelassen, bleiben die gespeicherten Farben erhalten.
lang	string | null	Zweistelliger ISO-639-1-Code (z. B. `es`) oder `null` für die Widget-Standardeinstellung.
dark_mode	boolean | null	`true` / `false`, `1` / `0` oder `null` (anfänglicher Dunkelmodus; berücksichtigt bereits gespeicherte Browser-Einstellungen).
position	string | null	`left`, `right` oder `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` oder `null` (Auto-Start beim Laden des Skripts).
logo_url	string | null	URL des Fußzeilen-Logos (http, https, absoluter Pfad oder relativ `./`) oder `null`.
logo_link	string | null	Ziel-URL beim Klick auf das Logo oder `null`.
delay	integer | null	Ganzzahl Millisekunden zwischen 0 und 86400000 zum Verzögern des Starts, oder `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` oder `null` (Fokus auf den Inhalt interner Modals).

Beim Ausliefern von `addaw-wba11y.min.js` über das CDN wird die Domain aus dem Referer-Header ermittelt. Sind Optionen für diese Domain gespeichert, wird `window.AddawConfig = { ... };` dem Skript vorangestellt, damit sie vor dem Auto-Start gelten (der Nutzer kann weiterhin Vorrang über lokalen Speicher haben, siehe Hierarchie im Widget-Abschnitt).

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