Teknik dokümantasyon

Araç entegrasyonu

Otomatik yükleme (Plug & Play)

Ek yapılandırma gerektirmeyen temel uygulama. Araç varsayılan değerlerle anında yüklenir.

Ayrı bir CSS bağlantısı gerekmez; betik stil sayfasını otomatik ekler (`.js` ile aynı temel yol). İsteğe bağlı olarak `` içinde `` bırakarak CSS ve JS dosyalarını paralel indirebilirsiniz.

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

API ile başlatma (Önerilen)

JavaScript üzerinden gecikmeleri ve özel görsel yapılandırmaları tanımlamaya olanak tanır.

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

Başlatma parametreleri

Initialization parameters reference

Parametre	Tür	Varsayılan	Açıklama
delay	Number	0	Gecikmeli yükleme için ms cinsinden süre.
position	String	'right'	Düğme konumu: left veya right.
dark_mode	String / Bool	'0'	Karanlık modda başlamak için 1 (bellek yoksa).
lang	String	'auto'	ISO dil kodu (es, en, fr...).
autoInit	Boolean	true	false ise araç manuel olarak çağrılmayı bekler.
logo_url	URL	ADDAW logo	Araç alt bilgisi için özel görsel.
logo_link	URL	https://addaw.org/es	Özel logoya tıklama hedefi.

Kontrol yöntemleri (genel API)

Araç yüklendikten sonra onunla etkileşimde bulunmak için bu komutları konsoldan veya betiklerinizden kullanın.

Addaw.initialized — Widget'ın etkin olup olmadığını kontrol eder.

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

Addaw.destroy() — Widget'ı siteden tamamen kaldırır.

Addaw.destroy();

Addaw.init({...}) — Yeni yapılandırma ile yeniden başlatır.

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

Yapılandırma hiyerarşisi

Araç, ayarları uygulamak için katı bir öncelik mantığı izler:

Gelişmiş manuel kontrol

İstek üzerine başlatma gerektiren uygulamalar için (örneğin, belirli bir düğmeye bastıktan sonra):

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

Alan adı yönetimi API'si

Çalışanların hesaplarına bağlı alan adlarını yönetmelerini ve araç görünümünü ve davranışını özelleştirmelerini sağlayan REST API (renk paleti ve Addaw.init ile eşdeğer parametreler).

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}"

Kimlik doğrulama

Tüm istekler (login hariç) Authorization başlığında Bearer token gerektirir.

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

Bir alan adı kaydetme

Hesabınıza bağlı yeni bir alan adı kaydeder. İşlem idempotenttir: alan adı zaten varsa çoğaltılmaz.

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

Bir alan adını devre dışı bırakma

Bir alan adını devre dışı bırakır. Silinmez, etkin değil olarak işaretlenir.

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

Alan adlarımı getir

Hesabınıza bağlı etkin alan adlarının listesini döndürür.

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

Mevcut renkleri listele

Aracı özelleştirmek için mevcut renk paletlerinin adlarını ve kimliklerini döndürür.

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

Bir alan adını özelleştir

Bir alan adı için widget ayarlarını kaydeder: renk paleti ve isteğe bağlı olarak Addaw.init ile aynı parametreler (dil, karanlık mod, konum, otomatik başlatma, logolar, gecikme ve modallarda odak). İlk istekte `color` palet kimliği gerekir; sonraki isteklerde atlanabilir ve kayıtlı renkler korunur veya yalnızca bazı alanlar güncellenir. Kayıtlı bir değeri sıfırlamak için anahtarı `null` olarak gönderin.

JSON gövde parametreleri

`dominio` dışında aşağıdaki alanları ekleyebilirsiniz. Adlar widget API’si ile eşleşir (`autoInit` ve `focusOnContent`; `auto_init` ve `focus_on_content` de kabul edilir).

JSON body parameters for domain customization

Parametre	Tür	Açıklama
color	integer	Mevcut renkler listesindeki palet kimliği. Alan adı ilk kez yapılandırılırken zorunludur; sonraki güncellemelerde atlanırsa kayıtlı renkler korunur.
lang	string | null	İki harfli ISO 639-1 kodu (ör. `es`) veya varsayılan için `null`.
dark_mode	boolean | null	`true` / `false`, `1` / `0` veya `null` (başlangıç karanlık modu; tarayıcıda kayıtlı tercihlere saygı duyar).
position	string | null	`left`, `right` veya `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` veya `null` (betik yüklenirken otomatik başlatma).
logo_url	string | null	Alt bilgi logosu URL’si (http, https, mutlak yol veya `./` göreli) veya `null`.
logo_link	string | null	Logoya tıklanınca gidilecek URL veya `null`.
delay	integer | null	Başlangıcı geciktirmek için 0–86400000 arası milisaniye tamsayı veya `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` veya `null` (iç modallardaki içeriğe odak).

CDN üzerinden `addaw-wba11y.min.js` sunulurken alan adı Referer başlığından alınır. Bu alan adı için seçenekler kayıtlıysa, otomatik başlamadan önce uygulanması için `window.AddawConfig = { ... };` betiğin başına eklenir (kullanıcı yerel depolama ile öncelikli olabilir; widget bölümündeki hiyerarşiye bakın).

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