For AI agents: the complete documentation index is available at https://nhanbe.id.vn/llms.txt, the full documentation bundle is available at https://nhanbe.id.vn/llms-full.txt, and this page is available as Markdown at https://nhanbe.id.vn/building-for-the-web/equalweb-intro.md.
Nhan AEM Notes

Hướng dẫn kỹ thuật tích hợp EqualWeb widget: cấu hình window.interdeal, thiết lập CSP, tối ưu hiệu năng và đánh giá kỹ thuật dạng overlay.

EqualWeb

EqualWeb là gì

EqualWeb là giải pháp Accessibility Widget (Client-side Overlay) hỗ trợ người dùng cuối tùy biến giao diện và bổ sung các thuộc tính hỗ trợ tiếp cận (a11y) theo chuẩn WCAG 2.1/2.2 AA, ADA Title III và Section 508.

Giao diện EqualWeb Accessibility Widget

Đối với developer, đây là giải pháp tích hợp nhanh qua script nhúng bên thứ ba mà không cần can thiệp sâu vào codebase hiện tại.

Độ phức tạp: 1/10

Cơ chế hoạt động

EqualWeb hoạt động hoàn toàn ở phía client (browser runtime):

  1. Loader Script: Một file JS nhỏ (~5KB) được tải bất đồng bộ (async/defer) để khởi tạo namespace window.interdeal.
  2. DOM Injection: Script tải bundle chính từ EqualWeb CDN, sau đó inject floating icon và modal điều khiển vào document.body.
  3. DOM Mutation & CSS Overrides: Khi người dùng bật tính năng (độ tương phản, cỡ chữ, phông chữ Dyslexic, dừng animation), script sẽ:
    • Chèn các class và thẻ <style> inline để override CSS hiện tại.
    • Bổ sung động các thuộc tính aria-label, role, tabindex vào các element thiếu sót thông qua cơ chế quét DOM tự động.

Cài đặt và tích hợp

1. Nhúng trực tiếp vào HTML

Đặt snippet sau trước thẻ đóng </body> hoặc trong <head> của trang:

index.html
<script type="text/javascript">
  window.interdeal = {
    sitekey: "YOUR_SITE_KEY",
    Position: "Left",
    Menulang: "EN",
    domains: {
      js: "https://cdn.equalweb.com/",
      acc: "https://access.equalweb.com/"
    }
  };

  (function(doc, head, body) {
    var coreCall = doc.createElement('script');
    coreCall.src = 'https://cdn.equalweb.com/core/4.5.2/accessibility.js';
    coreCall.defer = true;
    coreCall.setAttribute('data-core', 'equalweb');
    (doc.querySelector(head) || doc.querySelector(body)).appendChild(coreCall);
  })(document, 'head', 'body');
</script>

2. Tích hợp trong SPA (React / Next.js)

Với các framework SPA, cần đảm bảo script chỉ được nạp một lần duy nhất tại root layout:

app/layout.tsx (Next.js App Router)
import Script from 'next/script';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script id="equalweb-config" strategy="afterInteractive">
          {`
            window.interdeal = {
              sitekey: "${process.env.NEXT_PUBLIC_EQUALWEB_KEY}",
              Position: "Right",
              Menulang: "EN",
              domains: {
                js: "https://cdn.equalweb.com/",
                acc: "https://access.equalweb.com/"
              }
            };
          `}
        </Script>
        <Script
          src="https://cdn.equalweb.com/core/4.5.2/accessibility.js"
          strategy="lazyOnload"
          data-core="equalweb"
        />
      </body>
    </html>
  );
}

Bảng tham số cấu hình (window.interdeal)

Thuộc tínhKiểu dữ liệuMặc địnhMô tả
sitekeystring(Bắt buộc)Key định danh tài khoản được cấp từ EqualWeb Portal.
Positionstring"Left"Vị trí neo nút widget trên viewport: "Left" hoặc "Right".
Menulangstring"EN"Mã ngôn ngữ hiển thị của menu widget: "VI", "EN", "ES", "FR",...
btn_horizontalnumber10Khoảng cách từ icon đến mép màn hình ngang (pixel).
btn_verticalnumber10Khoảng cách từ icon đến mép màn hình dọc (pixel).
btn_sizestring"medium"Kích thước icon: "small", "medium", "large".
btn_shapestring"circle"Hình dạng nút: "circle", "square".
btn_colorstring"#0066cc"Mã màu HEX cho icon mở widget.
domains.jsstring"https://cdn.equalweb.com/"CDN host tải script thực thi.
domains.accstring"https://access.equalweb.com/"API endpoint ghi nhận log và kiểm tra license.

Cấu hình Content Security Policy (CSP)

Nếu web server hoặc CDN có header CSP chặt chẽ, cần whitelist các domain của EqualWeb:

Nginx / Cloudflare / Apache CSP Header
Content-Security-Policy:
  script-src 'self' https://cdn.equalweb.com;
  connect-src 'self' https://access.equalweb.com https://cdn.equalweb.com;
  style-src 'self' 'unsafe-inline' https://cdn.equalweb.com;
  font-src 'self' https://cdn.equalweb.com data:;
  img-src 'self' https://cdn.equalweb.com data:;
  frame-src 'self' https://access.equalweb.com;
[Lưu ý CSP]

EqualWeb inject inline styles vào DOM khi người dùng kích hoạt các tùy chọn màu sắc hoặc độ tương phản. Do đó, style-src bắt buộc cần 'unsafe-inline' trừ khi dùng nonce hỗ trợ runtime injection.

Tác động hiệu năng (Performance & CWV)

Khi tích hợp EqualWeb, developer cần lưu ý các chỉ số Web Vitals sau:

  1. Largest Contentful Paint (LCP):
    • Sử dụng thuộc tính defer hoặc strategy="lazyOnload" để script không chặn tải tài nguyên chính của trang.
  2. Total Blocking Time (TBT) / INP:
    • Bundle của widget thực thi sau khi DOM ready. Trên các trang có DOM tree lớn (>1500 nodes), việc quét và gắn ARIA thuộc tính có thể chiếm thread chính trong khoảng 50–150ms.
  3. Layout Shift (CLS):
    • Cố định icon bằng position: fixed với tọa độ cố định (btn_horizontal, btn_vertical) để không đẩy các element khác trong layout.
    • Chú ý tránh trùng tọa độ với các widget thứ ba khác (Zendesk chat, Intercom, back-to-top button).

Đánh giá kỹ thuật: Overlay vs Native Remediation

Tiêu chíEqualWeb OverlaySửa trực tiếp từ source code (Native)
Thời gian triển khaiVài phút (chèn script snippet).Hàng tuần hoặc hàng tháng tuỳ quy mô dự án.
Công cụ cho end-userCó sẵn (Dyslexia font, contrast toggle, ruler, cursor resize).Phải tự xây dựng UI hoặc dựa vào OS/Browser accessibility.
Xử lý Semantic HTMLKhông sửa được mã nguồn gốc; chỉ inject tạm thời vào DOM runtime.Sửa triệt để từ mã nguồn (<button> thay vì <div onClick>).
Hỗ trợ Screen ReaderTương đối; một số screen reader độc lập (NVDA, JAWS) bỏ qua overlay.Tối ưu 100% cho mọi thiết bị trợ năng tiêu chuẩn.
Phụ thuộc bên thứ baPhụ thuộc CDN và uptime của EqualWeb.Độc lập, không có rủi ro bên thứ ba.

Tóm tắt

  • Dùng EqualWeb khi cần đáp ứng gấp yêu cầu tuân thủ giao diện người dùng và cung cấp bộ công cụ trợ năng nhanh chóng.
  • Luôn tải script với defer/lazyOnload và khai báo đầy đủ CSP directives để tránh lỗi bảo mật.
  • Overlay không thay thế được việc viết Semantic HTML chuẩn, quản lý keyboard focus hợp lý và cung cấp thẻ alt đúng ngữ cảnh trong source code.