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

Інтеграція віджета

Автоматичне завантаження (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	Час у мс для відкладеного завантаження.
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 (мова, темний режим, позиція, автозапуск, логотипи, затримка та фокус модальних вікон). У першому запиті потрібно вказати ідентифікатор палітри `color`; пізніше його можна не передавати, щоб зберегти кольори, або оновити лише окремі поля. Щоб скинути збережене значення й використати стандартні налаштування віджета, надішліть ключ як `null`.

Параметри тіла JSON

Окрім `dominio` можна передати такі поля. Назви збігаються з API віджета (`autoInit` і `focusOnContent`; також приймаються `auto_init` і `focus_on_content`).

JSON body parameters for domain customization

Параметр	Тип	Опис
color	integer	Ідентифікатор палітри зі списку доступних кольорів. Обов’язковий під час першого налаштування домену; якщо пропустити в наступних запитах, збережені кольори не змінюються.
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;