技术文档

小组件集成

自动加载（Plug & Play）

无需额外配置的基本实现。小组件将使用默认值立即加载。

无需单独引入 CSS：脚本会自动插入样式表（与 `.js` 相同的基础路径）。也可选择在 `` 中保留 `` 以并行下载 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除外）需要在Authorization头中包含Bearer令牌。

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

列出可用颜色

返回可用于自定义小组件的颜色调色板名称和ID。

$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`（内部模态内容焦点）。

通过 CDN 提供 `addaw-wba11y.min.js` 时，域名取自 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;