Техническа документация

Интегриране на уиджета

Автоматично зареждане (Plug & Play)

Основна реализация без допълнителна конфигурация. Уиджетът се зарежда незабавно с настройки по подразбиране.

Не е нужен отделен CSS линк: скриптът автоматично вмъква стиловете (същата базова пътека като `.js`). По желание оставете `` в `` за паралелно изтегляне.

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

Инициализация чрез API (Препоръчително)

Позволява дефиниране на забавяния и персонализирани визуални конфигурации от 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>

Параметри за инициализация

Initialization parameters reference

Параметър	Тип	По подразбиране	Описание
delay	Number	0	Време в ms за отложено зареждане.
position	String	'right'	Позиция на бутона: left или right.
dark_mode	String / Bool	'0'	1 за стартиране в тъмен режим (ако няма памет).
lang	String	'auto'	ISO код на език (es, en, fr...).
autoInit	Boolean	true	Ако е false, уиджетът изчаква ръчно извикване.
logo_url	URL	ADDAW logo	Персонализирано изображение за долния колонтитул на уиджета.
logo_link	URL	https://addaw.org/es	Дестинация при клик върху персонализираното лого.

Методи за управление (публичен API)

Използвайте тези команди от конзолата или вашите скриптове за взаимодействие с уиджета след зареждането му.

Addaw.initialized — Проверява дали уиджетът е активен.

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

Addaw.destroy() — Премахва напълно уиджета от сайта.

Addaw.destroy();

Addaw.init({...}) — Повторно инициализира с нова конфигурация.

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

Йерархия на конфигурацията

Уиджетът следва строга логика на приоритети за прилагане на настройките:

Разширено ръчно управление

За приложения, изискващи стартиране при поискване (например след натискане на конкретен бутон):

<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 за управление на домейни

REST API за управление на домейни, свързани с акаунта на служителя, и персонализиране на външния вид и поведението на уиджета (цветова палитра и параметри, еквивалентни на 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}"

Удостоверяване

Всички заявки (с изключение на login) изискват Bearer токен в заглавието 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.

Регистриране на домейн

Регистрира нов домейн, свързан с вашия акаунт. Операцията е идемпотентна: ако домейнът вече съществува, не се дублира.

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

Деактивиране на домейн

Деактивира домейн. Не се изтрива, а се маркира като неактивен.

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

Получаване на моите домейни

Връща списък с активните домейни, свързани с вашия акаунт.

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

Списък на наличните цветове

Връща имената и идентификаторите на наличните цветови палитри за персонализиране на уиджета.

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

Персонализиране на домейн

Запазва настройките на уиджета за домейн: цветова палитра и по избор същите параметри като Addaw.init (език, тъмен режим, позиция, автоматично стартиране, лога, забавяне и фокус в модали). Първото заявяване трябва да включва id на палитра `color`; по-късно може да се пропусне, за да се запазят цветовете, или да се актуализират само полета. За изчистване на записана стойност изпратете ключа като `null`.

Параметри на JSON тялото

Освен `dominio` можете да включите следните полета. Имената съответстват на API на уиджета (`autoInit` и `focusOnContent`; приемат се и `auto_init` и `focus_on_content`).

JSON body parameters for domain customization

Параметър	Тип	Описание
color	integer	Id на палитра от списъка с налични цветове. Задължително при първоначална настройка; при пропуск при следващи актуализации се запазват записаните цветове.
lang	string | null	Двубуквен ISO 639-1 код (напр. `es`) или `null` за стойност по подразбиране.
dark_mode	boolean | null	`true` / `false`, `1` / `0` или `null` (начален тъмен режим; уважава вече записани настройки браузъра).
position	string | null	`left`, `right` или `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` или `null` (автоматично стартиране при зареждане на скрипта).
logo_url	string | null	URL на лого в долния колонтитул (http, https, абсолютен път или относителен `./`) или `null`.
logo_link	string | null	Целеви URL при клик върху логото или `null`.
delay	integer | null	Цяло число милисекунди от 0 до 86400000 за забавяне на старт или `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` или `null` (фокус върху съдържанието на вътрешни модали).

При доставяне на `addaw-wba11y.min.js` чрез CDN домейнът се взима от заглавка Referer. Ако има записани опции за домейна, пред скрипта се добавя `window.AddawConfig = { ... };`, за да се приложат преди автоматичното стартиране (потребителят може да има предимство чрез локално съхранение — вижте йерархията в раздела за уиджета).

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