Cơ sở tri thức chính thức Nvirya AdGuard

Phiên bản hiện tại: v11.7.0 | Giấy phép: MIT | Mô hình thực thi: Userscript (@run-at document-start)

Nvirya AdGuard (hiển thị trên thanh tiêu đề bảng điều khiển là Nvirya AdGuard X) là một userscript mã nguồn mở giúp lọc các phần tử quảng cáo đã biết, chặn cửa sổ bật lên (pop-up) và chuyển hướng tự động liên trang, vô hiệu hóa các lớp phủ bẫy nhấp chuột vô hình, đồng thời cung cấp bộ công cụ dọn dẹp trang trực quan ngay trên trình duyệt di động và máy tính.

Tài liệu này giải thích cách thức hoạt động của script, những gì script có thể và không thể thực hiện trong giới hạn bảo mật của trình duyệt, cách xử lý các sự cố tương thích phổ biến và cách gửi báo cáo lỗi hiệu quả.

Đối tượng sử dụng#

Nvirya AdGuard được thiết kế cho:

• Người dùng trình duyệt di động trên iOS/iPadOS (như Safari kết hợp với trình quản lý userscript Stay) và các trình duyệt Android hỗ trợ tiện ích mở rộng hoặc trình quản lý script tích hợp (như XBrowser, hoặc Firefox/Chromium với Tampermonkey, Violentmonkey).
• Người dùng trình duyệt máy tính muốn lọc quảng cáo ở cấp độ trang, xác nhận trước khi mở liên kết ngoài và ẩn phần tử tùy chọn thông qua trình quản lý userscript tiêu chuẩn.
• Người dùng thường xuyên truy cập các trang tin tức, xem video hoặc tải tệp nơi các lớp phủ nhấp chuột ẩn, pop-under, khóa cuộn trang hoặc chuyển hướng sang tên miền lạ thường xuyên làm gián đoạn trải nghiệm.

Mô hình Userscript hoạt động như thế nào#

Khác với ứng dụng độc lập hoặc bộ lọc mạng toàn hệ thống, userscript là một tệp JavaScript được trình quản lý userscript tiêm (inject) vào trang web.

Khi bạn mở một trang web khớp với *://*/*, trình quản lý userscript sẽ chạy Nvirya AdGuard tại thời điểm document-start (trước khi phần lớn script và cây DOM của trang tải xong). Bên trong môi trường trang, script thực hiện:

1. Áp dụng các quy tắc CSS ẩn quảng cáo (<style data-nvirya-cosmetic>) và quy tắc riêng của từng trang (<style data-nvirya-site-rules>) để ẩn các khung quảng cáo và vị trí tài trợ đã biết.
2. Theo dõi thay đổi động trên trang qua API MutationObserver để thu gọn các khung quảng cáo mới chèn, xóa lớp nền tối bị kẹt và vô hiệu hóa bẫy nhấp chuột trong suốt.
3. Bọc (wrap) các API JavaScript cấp trang—bao gồm Window.fetch, XMLHttpRequest, Navigator.sendBeacon và window.open—khi môi trường thực thi cho phép tiêm script vào ngữ cảnh chính (main world).
4. Hiển thị bảng điều khiển tách biệt bên trong Shadow DOM (<div data-nvirya-ui>) để bạn có thể tạm dừng bảo vệ, mở khóa cuộn trang, ẩn phần tử thủ công hoặc kiểm tra tên miền bên thứ ba ngay trên trang hiện tại.

Kỳ vọng thực tế và những điều không thể cam kết#

Vì Nvirya AdGuard hoạt động hoàn toàn như một userscript bên trong tab trình duyệt, hiệu quả thực tế phụ thuộc vào nhân trình duyệt, trình quản lý userscript, thời điểm tiêm script, quyền được cấp và cấu trúc của từng trang web.

Điều kiện tiên quyết và cài đặt#

Để sử dụng Nvirya AdGuard v11.7.0, môi trường của bạn cần có:

1. Một trình quản lý userscript tương thích hỗ trợ khối metadata (@run-at document-start, @all-frames true) và các quyền @grant sau:
   • GM_addStyle
   • GM_getValue và GM_setValue (tự động chuyển sang window.localStorage theo từng tên miền nếu không khả dụng)
   • GM_registerMenuCommand (tùy chọn, dùng cho menu phím tắt trên thanh công cụ trình duyệt)
   • GM_xmlhttpRequest (dùng để kiểm tra cập nhật, đồng bộ danh sách tên miền từ xa và gửi phản hồi; chuyển sang fetch nếu CORS cho phép)
   • unsafeWindow (dùng để cầu nối bảo vệ ngữ cảnh chính nơi được hỗ trợ)
2. Đường dẫn phân phối chính thức đã xác minh (từ metadata của script):
   • URL Cài đặt & Cập nhật tiêu chuẩn: https://raw.nvirya.com/adguard/nvirya-adguard.user.js
   • URL Cài đặt nhanh qua Stay trên iOS / iPadOS: stay://x-callback-url/install?scriptURL=https%3A%2F%2Fraw.nvirya.com%2Fadguard%2Fnvirya-adguard.user.js

Lưu ý: Luôn cài đặt hoặc cập nhật script từ URL phân phối chính thức ở trên. Vì mỗi trình quản lý userscript trên từng hệ điều hành có giao diện khác nhau, hãy làm theo hướng dẫn của trình quản lý bạn đang dùng để thêm tệp .user.js.

Danh mục tài liệu hướng dẫn#

• Cơ chế hoạt động — So sánh sự khác biệt kiến trúc giữa userscript, tiện ích mở rộng trình duyệt và bộ lọc VPN/DNS, cùng quy trình khởi động 3 giai đoạn trong v11.7.0.
• Hướng dẫn tính năng — Chi tiết cách sử dụng mọi nút điều khiển trong tab Tổng quan, Cài đặt và Giới thiệu, bao gồm Nút thao tác nhanh, công cụ Ẩn phần tử trên trang, Nhật ký kết nối và hộp thoại Xác nhận liên kết ngoài.
• Giới hạn đã biết — Giải thích kỹ thuật về độ trễ xử lý quảng cáo YouTube trên di động, tương tác với VPN/DNS (Shadowrocket, Surge, Loon), mức dùng CPU/pin trên Android và giới hạn WebKit trên iOS Safari.
• Khắc phục sự cố — Quy trình từng bước để xử lý lớp phủ tối còn sót, vòng lặp xác minh Cloudflare/CAPTCHA, liên kết tải xuống bị chặn, lỗi Google/Bing Dịch, trang web bị chậm và quảng cáo bị sót.
• Cấu hình nâng cao & Quy tắc từ xa — Cách cấu hình Đồng bộ từ URL cho danh sách tên miền chặn và xuất/nhập quy tắc lọc CSS theo trang.
• Gửi phản hồi & Báo lỗi — Minh bạch dữ liệu chẩn đoán được thu thập khi gửi báo cáo, cơ chế làm sạch URL và hướng dẫn viết báo lỗi ngắn gọn, dễ hiểu.
• Câu hỏi thường gặp (FAQ) — Giải đáp nhanh 11 câu hỏi phổ biến nhất về phạm vi chặn, sự khác biệt giữa các nền tảng và cách khôi phục trang.