التوثيق التقني

تكامل الأداة

التحميل التلقائي (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>

واجهة برمجة تطبيقات إدارة النطاقات

واجهة برمجة تطبيقات REST تتيح للموظفين إدارة النطاقات المرتبطة بحساباتهم وتخصيص مظهر الأداة وسلوكها (لوحة ألوان ومعلمات مماثلة لـ 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` يمكنك تضمين الحقول التالية. تطابق الأسماء واجهة الأداة (`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;