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

Интеграция виджета

Автоматическая загрузка (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;