技術ドキュメント

ウィジェットの統合

自動読み込み（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	遅延読み込みのためのms単位の時間。
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>

ドメイン管理API

従業員がアカウントに紐づいたドメインを管理し、ウィジェットの外観と動作をカスタマイズするためのREST API（カラーパレットおよび 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を除く）はAuthorizationヘッダーにBearerトークンが必要です。

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

利用可能な色の一覧

ウィジェットをカスタマイズするために利用可能なカラーパレットの名前とIDを返します。

$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 と同じパラメータ（言語、ダークモード、位置、自動起動、ロゴ、遅延、モーダル内フォーカス）を任意で指定できます。初回リクエストではパレット ID `color` が必須です。以降は省略して保存済みの色を維持したり、一部のフィールドだけ更新できます。保存値を消すにはキーを `null` にします。

JSON ボディのパラメータ

`dominio` に加え、次のフィールドを指定できます。名前はウィジェット API と一致します（`autoInit` と `focusOnContent`；`auto_init` と `focus_on_content` も可）。

JSON body parameters for domain customization

パラメータ	型	説明
color	integer	利用可能な色一覧のパレット ID。初回設定時は必須。以降の更新で省略すると保存済みの色が維持されます。
lang	string | null	ISO 639-1 の2文字コード（例: `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`（内部モーダル内容へのフォーカス）。

CDN から `addaw-wba11y.min.js` を配信する際、ドメインは 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;