Documentation technique

Intégration du widget

Chargement automatique (Plug & Play)

Implémentation de base sans configuration supplémentaire. Le widget se charge immédiatement avec les valeurs par défaut.

Pas besoin de lien CSS séparé : le script injecte automatiquement la feuille de styles (même chemin de base que le `.js`). Vous pouvez garder un `` dans le `` pour télécharger le CSS et le JS en parallèle.

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

Initialisation via API (Recommandé)

Permet de définir des délais et des configurations visuelles personnalisées depuis 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>

Paramètres d'initialisation

Initialization parameters reference

Paramètre	Type	Par défaut	Description
delay	Number	0	Temps en ms pour le chargement différé.
position	String	'right'	Position du bouton : left ou right.
dark_mode	String / Bool	'0'	1 pour démarrer en mode sombre (s'il n'y a pas de mémoire).
lang	String	'auto'	Code ISO de langue (es, en, fr...).
autoInit	Boolean	true	Si false, le widget attend d'être appelé manuellement.
logo_url	URL	ADDAW logo	Image personnalisée pour le pied de page du widget.
logo_link	URL	https://addaw.org/es	Destination du clic sur le logo personnalisé.

Méthodes de contrôle (API publique)

Utilisez ces commandes depuis la console ou vos scripts pour interagir avec le widget une fois chargé.

Addaw.initialized — Vérifie si le widget est actif.

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

Addaw.destroy() — Supprime complètement le widget du site.

Addaw.destroy();

Addaw.init({...}) — Réinitialise avec une nouvelle configuration.

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

Hiérarchie de configuration

Le widget suit une logique de priorité stricte pour appliquer les réglages :

Contrôle manuel avancé

Pour les applications nécessitant un démarrage à la demande (par exemple, après avoir cliqué sur un bouton spécifique) :

<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 de gestion de domaines

API REST permettant aux employés de gérer les domaines liés à leur compte et de personnaliser l'apparence et le comportement du widget (palette de couleurs et paramètres équivalents à 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}"

Authentification

Toutes les requêtes (sauf login) nécessitent un token Bearer dans l'en-tête 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.

Enregistrer un domaine

Enregistre un nouveau domaine lié à votre compte. L'opération est idempotente : si le domaine existe déjà, il n'est pas dupliqué.

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

Désactiver un domaine

Désactive un domaine. Il n'est pas supprimé, il est marqué comme inactif.

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

Obtenir mes domaines

Retourne la liste des domaines actifs liés à votre compte.

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

Lister les couleurs disponibles

Retourne les noms et identifiants des palettes de couleurs disponibles pour personnaliser le widget.

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

Personnaliser un domaine

Enregistre la configuration du widget pour un domaine : palette de couleurs et, en option, les mêmes paramètres qu’Addaw.init (langue, mode sombre, position, démarrage automatique, logos, délai et focus des modales). La première requête doit inclure l’identifiant de palette `color` ; ensuite il peut être omis pour conserver les couleurs, ou seuls certains champs peuvent être mis à jour. Pour réinitialiser une valeur et revenir au comportement par défaut du widget, envoyez la clé à `null`.

Paramètres du corps JSON

En plus de `dominio`, vous pouvez inclure les champs suivants. Les noms correspondent à l’API du widget (`autoInit` et `focusOnContent` ; `auto_init` et `focus_on_content` sont également acceptés).

JSON body parameters for domain customization

Paramètre	Type	Description
color	integer	Identifiant de palette dans la liste des couleurs disponibles. Obligatoire la première fois ; s’il est omis ensuite, les couleurs déjà enregistrées sont conservées.
lang	string | null	Code ISO 639-1 sur deux lettres (ex. `es`) ou `null` pour la valeur par défaut du widget.
dark_mode	boolean | null	`true` / `false`, `1` / `0` ou `null` (mode sombre initial ; respecte les préférences déjà stockées dans le navigateur).
position	string | null	`left`, `right` ou `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` ou `null` (démarrage automatique au chargement du script).
logo_url	string | null	URL du logo en pied de page (http, https, chemin absolu ou relatif `./`) ou `null`.
logo_link	string | null	URL de destination du clic sur le logo ou `null`.
delay	integer | null	Entier en millisecondes entre 0 et 86400000 pour retarder le démarrage, ou `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` ou `null` (focus sur le contenu des modales internes).

Lors de la diffusion de `addaw-wba11y.min.js` via le CDN, le domaine est déduit de l’en-tête Referer. Si des options sont enregistrées pour ce domaine, `window.AddawConfig = { ... };` est ajouté avant le script afin qu’elles s’appliquent avant le démarrage automatique (l’utilisateur peut toujours passer en premier via le stockage local, selon la hiérarchie décrite dans la section widget).

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