Teknisk dokumentasjon

Widget-integrasjon

Automatisk lasting (Plug & Play)

Grunnleggende implementering uten ekstra konfigurasjon. Widgeten lastes umiddelbart med standardverdier.

Du trenger ikke egen CSS-lenke: skriptet setter inn stilarket automatisk (samme basissti som `.js`). Valgfritt kan du beholde en `` i `` for parallell nedlasting.

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

Initialisering via API (Anbefalt)

Gjør det mulig å definere forsinkelser og tilpassede visuelle konfigurasjoner fra 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>

Initialiseringsparametere

Initialization parameters reference

Parameter	Type	Standard	Beskrivelse
delay	Number	0	Tid i ms for forsinket lasting.
position	String	'right'	Knappposisjon: left eller right.
dark_mode	String / Bool	'0'	1 for å starte i mørk modus (hvis ingen hukommelse).
lang	String	'auto'	ISO-språkkode (es, en, fr...).
autoInit	Boolean	true	Hvis false, venter widgeten på å bli kalt manuelt.
logo_url	URL	ADDAW logo	Tilpasset bilde for widgetens bunntekst.
logo_link	URL	https://addaw.org/es	Klikkemål for den tilpassede logoen.

Kontrollmetoder (offentlig API)

Bruk disse kommandoene fra konsollen eller skriptene dine for å samhandle med widgeten etter at den er lastet.

Addaw.initialized — Sjekker om widgeten er aktiv.

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

Addaw.destroy() — Fjerner widgeten fullstendig fra nettstedet.

Addaw.destroy();

Addaw.init({...}) — Initialiserer på nytt med ny konfigurasjon.

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

Konfigurasjonshierarki

Widgeten følger en streng prioritetslogikk for å anvende innstillinger:

Avansert manuell kontroll

For applikasjoner som krever oppstart etter behov (for eksempel etter å ha trykket på en bestemt knapp):

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

Domeneadministrasjons-API

REST-API som gjør det mulig for ansatte å administrere domener knyttet til kontoen sin og tilpasse widgetens utseende og oppførsel (fargepalett og parametre tilsvarende 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}"

Autentisering

Alle forespørsler (unntatt login) krever et Bearer-token i Authorization-headeren.

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

Registrer et domene

Registrerer et nytt domene knyttet til kontoen din. Operasjonen er idempotent: hvis domenet allerede eksisterer, dupliseres det ikke.

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

Deaktiver et domene

Deaktiverer et domene. Det slettes ikke, det markeres som inaktivt.

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

Hent mine domener

Returnerer listen over aktive domener knyttet til kontoen din.

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

List tilgjengelige farger

Returnerer navn og ID-er for tilgjengelige fargepaletter for å tilpasse widgeten.

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

Tilpass et domene

Lagrer widget-innstillinger for et domene: fargepalet og valgfritt de samme parameterne som Addaw.init (språk, mørk modus, posisjon, automatisk start, logoer, forsinkelse og fokus i modaler). Første forespørsel må inneholde palett-id `color`; senere kan det utelates for å beholde lagrede farger, eller bare noen felter oppdateres. Send nøkkelen som `null` for å nullstille en lagret verdi.

JSON-body-parametere

I tillegg til `dominio` kan du inkludere følgende felt. Navnene samsvarer med widget-API-et (`autoInit` og `focusOnContent`; `auto_init` og `focus_on_content` aksepteres også).

JSON body parameters for domain customization

Parameter	Type	Beskrivelse
color	integer	Palett-id fra listen over tilgjengelige farger. Påkrevd første gang domenet konfigureres; utelates det senere, beholdes lagrede farger.
lang	string | null	To-bokstavers ISO 639-1-kode (f.eks. `es`) eller `null` for standard.
dark_mode	boolean | null	`true` / `false`, `1` / `0` eller `null` (innledende mørk modus; respekterer lagrede nettleserpreferanser).
position	string | null	`left`, `right` eller `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` eller `null` (automatisk start ved lasting av skriptet).
logo_url	string | null	URL til bunntekstlogo (http, https, absolutt sti eller relativ `./`) eller `null`.
logo_link	string | null	Mål-URL ved klikk på logo eller `null`.
delay	integer | null	Heltall millisekunder mellom 0 og 86400000 for å utsette start, eller `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` eller `null` (fokus på innhold i interne modaler).

Når `addaw-wba11y.min.js` leveres via CDN, hentes domenet fra Referer-headeren. Hvis det finnes lagrede alternativer for domenet, settes `window.AddawConfig = { ... };` foran skriptet slik at de gjelder før automatisk start (brukeren kan fortsatt ha forrang via lokal lagring — se hierarkiet i widget-delen).

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