Dokumentacja techniczna

Integracja widgetu

Automatyczne ładowanie (Plug & Play)

Podstawowa implementacja bez dodatkowej konfiguracji. Widget ładuje się natychmiast z wartościami domyślnymi.

Nie trzeba osobno linkować CSS: skrypt automatycznie wstawia arkusz stylów (ta sama ścieżka bazowa co `.js`). Opcjonalnie możesz zostawić `` w ``, aby pobierać CSS i JS równolegle.

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

Inicjalizacja przez API (Zalecane)

Umożliwia definiowanie opóźnień i niestandardowych konfiguracji wizualnych z poziomu 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>

Parametry inicjalizacji

Initialization parameters reference

Parametr	Typ	Domyślnie	Opis
delay	Number	0	Czas w ms dla opóźnionego ładowania.
position	String	'right'	Pozycja przycisku: left lub right.
dark_mode	String / Bool	'0'	1, aby uruchomić w trybie ciemnym (jeśli brak pamięci).
lang	String	'auto'	Kod ISO języka (es, en, fr...).
autoInit	Boolean	true	Jeśli false, widget czeka na ręczne wywołanie.
logo_url	URL	ADDAW logo	Niestandardowy obraz dla stopki widgetu.
logo_link	URL	https://addaw.org/es	Cel kliknięcia niestandardowego logo.

Metody sterowania (publiczne API)

Użyj tych poleceń z konsoli lub swoich skryptów, aby wchodzić w interakcję z widgetem po jego załadowaniu.

Addaw.initialized — Sprawdza, czy widżet jest aktywny.

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

Addaw.destroy() — Całkowicie usuwa widżet ze strony.

Addaw.destroy();

Addaw.init({...}) — Ponownie inicjuje z nową konfiguracją.

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

Hierarchia konfiguracji

Widget stosuje ścisłą logikę priorytetów przy stosowaniu ustawień:

Zaawansowane sterowanie ręczne

Dla aplikacji wymagających uruchomienia na żądanie (na przykład po naciśnięciu określonego przycisku):

<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 zarządzania domenami

API REST umożliwiające pracownikom zarządzanie domenami powiązanymi z ich kontem oraz dostosowywanie wyglądu i zachowania widgetu (paleta kolorów i parametry równoważne 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}"

Uwierzytelnianie

Wszystkie żądania (z wyjątkiem login) wymagają tokenu Bearer w nagłówku 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.

Zarejestrowanie domeny

Rejestruje nową domenę powiązaną z Twoim kontem. Operacja jest idempotentna: jeśli domena już istnieje, nie jest duplikowana.

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

Dezaktywacja domeny

Dezaktywuje domenę. Nie jest usuwana, lecz oznaczana jako nieaktywna.

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

Pobieranie moich domen

Zwraca listę aktywnych domen powiązanych z Twoim kontem.

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

Lista dostępnych kolorów

Zwraca nazwy i identyfikatory dostępnych palet kolorów do personalizacji widgetu.

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

Personalizacja domeny

Zapisuje konfigurację widgetu dla domeny: paletę kolorów oraz opcjonalnie te same parametry co Addaw.init (język, tryb ciemny, pozycja, autostart, logotypy, opóźnienie i fokus modali). Przy pierwszym żądaniu należy podać identyfikator palety `color`; później można go pominąć, aby zachować zapisane kolory, lub zaktualizować tylko wybrane pola. Aby usunąć zapisaną wartość i wrócić do domyślnych ustawień widgetu, wyślij klucz jako `null`.

Parametry treści JSON

Oprócz `dominio` możesz dołączyć poniższe pola. Nazwy odpowiadają API widgetu (`autoInit` i `focusOnContent`; akceptowane są też `auto_init` i `focus_on_content`).

JSON body parameters for domain customization

Parametr	Typ	Opis
color	integer	Identyfikator palety z listy dostępnych kolorów. Wymagany przy pierwszej konfiguracji domeny; jeśli później zostanie pominięty, zachowane zostaną zapisane kolory.
lang	string | null	Dwuliterowy kod ISO 639-1 (np. `es`) lub `null` dla wartości domyślnej widgetu.
dark_mode	boolean | null	`true` / `false`, `1` / `0` lub `null` (początkowy tryb ciemny; uwzględnia wcześniej zapisane preferencje w przeglądarce).
position	string | null	`left`, `right` lub `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` lub `null` (autostart przy ładowaniu skryptu).
logo_url	string | null	Adres URL logotypu w stopce (http, https, ścieżka bezwzględna lub względna `./`) lub `null`.
logo_link	string | null	URL docelowy po kliknięciu logotypu lub `null`.
delay	integer | null	Liczba całkowita milisekund od 0 do 86400000 opóźniająca start lub `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` lub `null` (fokus na treści wewnętrznych modali).

Przy serwowaniu `addaw-wba11y.min.js` z CDN domena jest pobierana z nagłówka Referer. Jeśli dla domeny zapisano opcje, przed skryptem dodawane jest `window.AddawConfig = { ... };`, aby zastosować je przed autostartem (użytkownik może nadal mieć pierwszeństwo przez pamięć lokalną — zgodnie z hierarchią w sekcji widgetu).

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