Tekninen dokumentaatio

Widgetin integrointi

Automaattinen lataus (Plug & Play)

Perusimplementointi ilman lisäkonfiguraatiota. Widget latautuu välittömästi oletusarvoilla.

Erillistä CSS-linkkiä ei tarvita: skripti lisää tyylitiedoston automaattisesti (sama peruspolku kuin `.js`-tiedostolla). Voit halutessasi pitää ``-elementin ``-osassa ladataksesi CSS:n ja JS:n rinnakkain.

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

Alustus API:n kautta (Suositeltu)

Mahdollistaa viiveiden ja mukautettujen visuaalisten asetusten määrittelyn JavaScriptistä.

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

Alustusparametrit

Initialization parameters reference

Parametri	Tyyppi	Oletus	Kuvaus
delay	Number	0	Aika millisekunteina viivästettyä latausta varten.
position	String	'right'	Painikkeen sijainti: left tai right.
dark_mode	String / Bool	'0'	1 käynnistääksesi tummassa tilassa (jos ei muistia).
lang	String	'auto'	ISO-kielikoodi (es, en, fr...).
autoInit	Boolean	true	Jos false, widget odottaa manuaalista kutsua.
logo_url	URL	ADDAW logo	Mukautettu kuva widgetin alatunnisteeseen.
logo_link	URL	https://addaw.org/es	Mukautetun logon klikkauksen kohde.

Ohjausmenetelmät (julkinen API)

Käytä näitä komentoja konsolista tai skripteistäsi ollaksesi vuorovaikutuksessa widgetin kanssa sen latauduttua.

Addaw.initialized — Tarkistaa, onko widget aktiivinen.

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

Addaw.destroy() — Poistaa widgetin kokonaan sivustolta.

Addaw.destroy();

Addaw.init({...}) — Alustaa uudelleen uudella määrityksellä.

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

Konfiguraatiohierarkia

Widget noudattaa tiukkaa prioriteettilogiikkaa asetusten soveltamisessa:

Edistynyt manuaalinen ohjaus

Sovelluksille, jotka vaativat käynnistyksen tarpeen mukaan (esimerkiksi tietyn painikkeen painamisen jälkeen):

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

Verkkotunnusten hallinnan API

REST-API, joka mahdollistaa työntekijöille tiliin liitettyjen verkkotunnusten hallinnan ja widgetin ulkoasun sekä toiminnan mukauttamisen (väripaletti ja Addaw.init-vastaiset parametrit).

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

Todennus

Kaikki pyynnöt (paitsi login) vaativat Bearer-tokenin Authorization-otsakkeessa.

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

Rekisteröi verkkotunnus

Rekisteröi uuden verkkotunnuksen tiliisi liitettynä. Toiminto on idempotentti: jos verkkotunnus on jo olemassa, sitä ei kopioida.

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

Poista verkkotunnus käytöstä

Poistaa verkkotunnuksen käytöstä. Sitä ei poisteta, se merkitään epäaktiiviseksi.

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

Hae verkkotunnukseni

Palauttaa luettelon tiliisi liitetyistä aktiivisista verkkotunnuksista.

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

Listaa käytettävissä olevat värit

Palauttaa käytettävissä olevien väripalettien nimet ja tunnisteet widgetin mukauttamiseen.

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

Mukauta verkkotunnus

Tallentaa widget-asetukset verkkotunnukselle: väripaletin ja valinnaisesti samat parametrit kuin Addaw.init (kieli, tumma tila, sijainti, automaattinen käynnistys, logot, viive ja modaalien kohdistus). Ensimmäisessä pyynnössä on annettava paletin tunniste `color`; myöhemmin se voidaan jättää pois tallennettujen värien säilyttämiseksi tai vain osa kentistä päivitetään. Tyhjennä tallennettu arvo lähettämällä avain arvona `null`.

JSON-runkoparametrit

`dominio`-kentän lisäksi voit lisätä seuraavat kentät. Nimet vastaavat widget-API:a (`autoInit` ja `focusOnContent`; myös `auto_init` ja `focus_on_content` hyväksytään).

JSON body parameters for domain customization

Parametri	Tyyppi	Kuvaus
color	integer	Palettitunniste saatavilla olevien värien luettelosta. Pakollinen ensimmäisellä määrityksellä; jos myöhemmin jätetään pois, säilytetään tallennetut värit.
lang	string | null	Kaksikirjaiminen ISO 639-1 -koodi (esim. `es`) tai `null` oletusarvoon.
dark_mode	boolean | null	`true` / `false`, `1` / `0` tai `null` (alkuva tumma tila; kunnioittaa tallennettuja selainasetuksia).
position	string | null	`left`, `right` tai `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` tai `null` (automaattinen käynnistys skriptin latautuessa).
logo_url	string | null	Alatunnisteen logon URL (http, https, absoluuttinen polku tai suhteellinen `./`) tai `null`.
logo_link	string | null	Kohde-URL logon napsautuksessa tai `null`.
delay	integer | null	Kokonaisluku millisekunteina 0–86400000 käynnin viivyttämiseksi tai `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` tai `null` (kohdistus sisäisten modaalien sisältöön).

Kun `addaw-wba11y.min.js` tarjoillaan CDN:stä, verkkotunnus luetaan Referer-otsakkeesta. Jos verkkotunnukselle on tallennettu asetuksia, skriptin eteen lisätään `window.AddawConfig = { ... };`, jotta ne tulevat voimaan ennen automaattista käynnistystä (käyttäjä voi yhä ohittaa paikallisen tallennuksen kautta — katso hierarkia widget-osiossa).

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