Documentação técnica

Integração do widget

Carregamento automático (Plug & Play)

Implementação básica sem configuração adicional. O widget é carregado imediatamente com os valores predefinidos.

Não é necessário ligar o CSS separadamente: o script insere automaticamente a folha de estilos (mesmo caminho base que o `.js`). Opcionalmente pode manter um `` no `` para descarregar CSS e JS em paralelo.

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

Inicialização via API (Recomendado)

Permite definir atrasos e configurações visuais personalizadas a partir de 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>

Parâmetros de inicialização

Initialization parameters reference

Parâmetro	Tipo	Predefinido	Descrição
delay	Number	0	Tempo em ms para carregamento diferido.
position	String	'right'	Posição do botão: left ou right.
dark_mode	String / Bool	'0'	1 para iniciar em modo escuro (se não houver memória).
lang	String	'auto'	Código ISO do idioma (es, en, fr...).
autoInit	Boolean	true	Se for false, o widget aguarda ser chamado manualmente.
logo_url	URL	ADDAW logo	Imagem personalizada para o rodapé do widget.
logo_link	URL	https://addaw.org/es	Destino do clique no logótipo personalizado.

Métodos de controlo (API pública)

Utilize estes comandos na consola ou nos seus scripts para interagir com o widget depois de carregado.

Addaw.initialized — Verifica se o widget está ativo.

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

Addaw.destroy() — Remove completamente o widget do site.

Addaw.destroy();

Addaw.init({...}) — Reinicializa com nova configuração.

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

Hierarquia de configuração

O widget segue uma lógica de prioridade estrita para aplicar as definições:

Controlo manual avançado

Para aplicações que requerem um arranque sob demanda (por exemplo, após premir um botão específico):

<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 gestão de domínios

API REST para que os colaboradores gerem os domínios vinculados à sua conta e personalizem a aparência e o comportamento do widget (paleta de cores e parâmetros equivalentes ao 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}"

Autenticação

Todos os pedidos (exceto login) requerem um token Bearer no cabeçalho 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.

Registar um domínio

Regista um novo domínio vinculado à sua conta. A operação é idempotente: se o domínio já existir, não é duplicado.

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

Desativar um domínio

Desativa um domínio. Não é eliminado, é marcado como inativo.

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

Obter os meus domínios

Devolve a lista de domínios ativos vinculados à sua conta.

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

Listar cores disponíveis

Devolve os nomes e IDs das paletas de cores disponíveis para personalizar o 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);

Personalizar um domínio

Guarda a configuração do widget para um domínio: paleta de cores e, opcionalmente, os mesmos parâmetros que o Addaw.init (idioma, modo escuro, posição, arranque automático, logótipos, atraso e foco em modais). Na primeira vez deve enviar o id de paleta `color`; nos pedidos seguintes pode omitir-se e mantêm-se as cores guardadas, ou atualizar apenas alguns campos. Para anular um valor guardado e voltar ao comportamento predefinido do widget, envie a chave como `null`.

Parâmetros do corpo JSON

Além de `dominio`, pode incluir os seguintes campos. Os nomes coincidem com a API do widget (`autoInit` e `focusOnContent`; também são aceites `auto_init` e `focus_on_content`).

JSON body parameters for domain customization

Parâmetro	Tipo	Descrição
color	integer	Id. da paleta na lista de cores disponíveis. Obrigatório na primeira configuração do domínio; se omitido em atualizações posteriores, mantêm-se as cores já armazenadas.
lang	string | null	Código ISO 639-1 de duas letras (ex.: `es`) ou `null` para o valor predefinido do widget.
dark_mode	boolean | null	`true` / `false`, `1` / `0` ou `null` (modo escuro inicial; respeita preferências já guardadas no navegador).
position	string | null	`left`, `right` ou `null`.
autoInit / auto_init	boolean | null	`true` / `false`, `1` / `0` ou `null` (arranque automático ao carregar o script).
logo_url	string | null	URL do logótipo no rodapé (http, https, caminho absoluto ou relativo `./`) ou `null`.
logo_link	string | null	URL de destino ao clicar no logótipo ou `null`.
delay	integer | null	Inteiro em milissegundos entre 0 e 86400000 para atrasar o início, ou `null`.
focusOnContent / focus_on_content	boolean | null	`true` / `false`, `1` / `0` ou `null` (foco no conteúdo de modais internos).

Ao servir `addaw-wba11y.min.js` a partir do CDN, o domínio é obtido pelo cabeçalho Referer. Se existirem opções guardadas para esse domínio, é anteposto `window.AddawConfig = { ... };` ao script para que se apliquem antes do arranque automático (o utilizador pode ainda ter prioridade via armazenamento local, conforme a hierarquia na secção do 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;