Dokumentazio teknikoa

Widgetaren integrazioa

Karga automatikoa (Plug & Play)

Oinarrizko inplementazioa konfigurazio gehigarririk gabe. Widgeta berehala kargatzen da balio lehenetsiekin.

Ez da CSSa bereizirik lotu behar: scriptak estilo-orria automatikoki txertatzen du (`.js`-rekin oinarrizko bide bera). Aukeran, mantendu `` ``-ean CSSa eta JSa paraleloan deskargatzeko.

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

API bidezko hasieratzea (Gomendatua)

Atzerapenak eta konfigurazio bisual pertsonalizatuak definitzeko aukera ematen du JavaScript-etik.

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

Hasieratze-parametroak

Initialization parameters reference

Parametroa	Mota	Lehenetsia	Deskribapena
delay	Number	0	Karga atzeratua ms-tan.
position	String	'right'	Botoiaren kokapena: left edo right.
dark_mode	String / Bool	'0'	1 modu ilunean hasteko (memoriarik ez bada).
lang	String	'auto'	Hizkuntza ISO kodea (es, en, fr...).
autoInit	Boolean	true	False bada, widgetak eskuz deitzeko itxaroten du.
logo_url	URL	ADDAW logo	Widgetaren footer-erako irudi pertsonalizatua.
logo_link	URL	https://addaw.org/es	Logo pertsonalizatuan klik egiteko helmuga.

Kontrol-metodoak (API publikoa)

Erabili komando hauek kontsolan edo zure script-etan widgetarekin elkarrekiteko behin kargatuta.

Addaw.initialized — Widgeta aktibo dagoen egiaztatzen du.

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

Addaw.destroy() — Widgeta guneaz guztiz ezabatzen du.

Addaw.destroy();

Addaw.init({...}) — Konfigurazio berriarekin berriz hasieratzen du.

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

Konfigurazio-hierarkia

Widgetak lehentasun-logika zorrotza jarraitzen du ezarpenak aplikatzeko:

Kontrol manual aurreratua

Eskaeraren araberako hasiera behar duten aplikazioetarako (adibidez, botoi zehatz bat sakatu ondoren):

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

Domeinuen kudeaketa APIa

REST APIa langileek beren kontuko domeinuak kudeatzeko eta widgetaren itxura eta portaera pertsonalizatzeko (kolore-paleta eta Addaw.init-ekin baliokideak diren parametroak).

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

Autentikazioa

Eskaera guztiek (login izan ezik) Bearer token bat behar dute Authorization goiburuan.

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

Domeinu bat erregistratu

Domeinu berri bat erregistratzen du zure kontuari lotuta. Eragiketa idenpotentea da: domeinua dagoeneko existitzen bada, ez da bikoizten.

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

Domeinu bat desaktibatu

Domeinu bat desaktibatzen du. Ez da ezabatzen, inaktibo gisa markatzen da.

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

Nire domeinuak lortu

Zure kontuari lotutako domeinu aktiboen zerrenda itzultzen du.

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

Kolore erabilgarriak zerrendatu

Widgeta pertsonalizatzeko eskuragarri dauden kolore-paleten izenak eta id-ak itzultzen ditu.

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

Domeinu bat pertsonalizatu

Widgetaren konfigurazioa gordetzen du domeinu baterako: kolore-paleta eta, aukeran, Addaw.init-ek onartzen dituen parametro berak (hizkuntza, modu iluna, kokapena, abio automatikoa, logoak, atzerapena eta modaletan fokua). Lehenengo aldian `color` paletaren id-a bidali behar da; ondorengo eskaeretan utz daiteke eta gordetako koloreak mantentzen dira, edo eremu batzuk soilik egunera daitezke. Gordetako balio bat baliogabetzeko eta widgetaren lehenetsitara itzultzeko, gakoa `null` gisa bidali.

JSON gorputzaren parametroak

`dominio`-az gain, eremu hauek gehitu ditzakezu. Izenek widgetaren APIrekin bat datoz (`autoInit` eta `focusOnContent`; `auto_init` eta `focus_on_content` ere onartzen dira).

JSON body parameters for domain customization

Parametroa	Mota	Deskribapena
color	integer	Kolore eskuragarrien zerrendako paletaren id-a. Domeinua lehen aldiz konfiguratzean derrigorrezkoa; eguneratze beranduagoetan utziz gero, gordetako koloreak mantentzen dira.
lang	string | null	ISO 639-1 bi letrako kodea (adib. `es`) edo `null` widgetaren lehenetsia erabiltzeko.
dark_mode	boolean | null	`true` / `false`, `1` / `0` edo `null` (hasierako modu iluna; nabigatzailean gordetako hobespenak errespetatzen ditu).
position	string | null	`left`, `right` edo `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` edo `null` (script-a kargatzean abio automatikoa).
logo_url	string | null	Oineko logoaren URLa (http, https, bide absolutua edo `./` erlatiboa) edo `null`.
logo_link	string | null	Logoa klikatzean helburuko URLa edo `null`.
delay	integer | null	Hasiera atzeratzeko 0 eta 86400000 arteko milisegundo osoa edo `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` edo `null` (barne modaletako edukian fokua).

CDN-tik `addaw-wba11y.min.js` zerbitzatzean, domeinua Referer goiburuaren bidez antzematen da. Domeinu horretarako aukerak gordeta badaude, `window.AddawConfig = { ... };` aurretik gehitzen zaio script-ari abio automatikoa baino lehen aplikatzeko (erabiltzaileak lehentasuna izan dezake tokiko biltegian, widgetaren ataleko hierarkiaren arabera).

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