Cấu hình trang

Mục tiêu

Quản lý cấu hình nâng cao của trang, bao gồm URL mã hóa, script, mô phỏng trình duyệt, proxy, ghi nhận header request/response, điều khiển trang và hành vi truy cập.

Điều kiện tiên quyết

• Trang đích đã được tạo.
• Trước khi phát hành script, hãy kiểm thử trang trước.

Các bước

1. Vào "Quản lý trang > Danh sách trang".
2. Tìm trang đích và nhấp vào cấu hình.
3. Bật URL mã hóa khi cần để tránh frontend người dùng hiển thị trực tiếp địa chỉ trang gốc.
4. Cấu hình mô phỏng trình duyệt, proxy, header request, header response, điều khiển trang và script.
5. Lưu cấu hình trang.
6. Dùng tài khoản kiểm thử để truy cập trang đích và kiểm tra mở trang, đăng nhập, chuyển trang, dữ liệu API và xử lý sự kiện SSE.
7. Nếu cần tùy chỉnh hành vi theo phân loại tài khoản, quay lại danh sách trang và mở "Cấu hình phân loại tài khoản".

Tham chiếu cấu hình

Élément	Utilité	Remarques
URL mã hóa	Ẩn địa chỉ trang gốc hiển thị trong frontend người dùng	Không thay thế xác thực riêng của trang đích
Mô phỏng trình duyệt	Điều chỉnh thương hiệu trình duyệt, mẫu thiết bị di động, múi giờ và thông tin nhận dạng khác	Sau khi thay đổi cần kiểm tra lại tương thích của trang đích
Cài đặt proxy	Cấu hình truy cập trực tiếp, proxy hệ thống, PAC hoặc máy chủ proxy cố định cho trang	Lỗi proxy có thể làm trang không mở được hoặc đăng nhập bất thường
Header request	Ghi nhận header request chỉ định để script trang đọc bằng api.header(name, true)	Chỉ ghi nhận header đã cấu hình và thực sự đi qua trình duyệt từ xa
Header response	Ghi nhận header response chỉ định để script trang đọc bằng api.header(name, false)	Tên header được chuyển thành chữ thường khi đọc
Script trang	Xử lý DOM, biểu mẫu, nút, chuyển trang và tăng cường trang	Nên giới hạn URL khớp để tránh tác động ngoài ý muốn
Script SSE	Viết lại dữ liệu luồng Server-Sent Events	Phù hợp cho tình huống nâng cao; nên kiểm thử trước
Script chặn API thông thường	Viết lại body response của API không phải SSE	Script phải trả về chuỗi body response mới
Điều khiển trang	Ẩn hoặc xóa phần tử trang theo URL và selector	Selector có thể mất hiệu lực sau khi trang đích thay đổi
Cấu hình phân loại tài khoản	Thiết lập logic đăng nhập khác nhau cho từng phân loại tài khoản	Dùng cùng tài khoản trình duyệt của trang

Cấu hình script

Khu vực "Cấu hình script" trên trang cấu hình trang dùng để thêm một nhóm quy tắc script cho trang đích. Mỗi quy tắc chạy khi trình duyệt từ xa truy cập trang đích, dựa trên URL khớp và loại script.

Champ	Type	Description
name	string	Tên script. Nên dùng định dạng "trang-mục đích-phiên bản", ví dụ crm-login-v1.
url	string	URL khớp. Khi để trống thường hiểu là *; môi trường production nên viết càng chính xác càng tốt.
pageScript	boolean	Có phải script trang hay không. Khi bật, script chạy trong môi trường trang và có thể dùng window.api.
sseScript	boolean	Có phải script chặn SSE hay không. Chỉ hiển thị và có hiệu lực khi pageScript = false.
selector	string	Điều kiện thực thi script trang. Khi nhập, script chỉ chạy nếu trang khớp selector CSS hoặc XPath này.
content	string	Nội dung JavaScript của script. Tham số và giá trị trả về khác nhau theo loại script.

Script trang

Khi pageScript = true, script chạy như script trang. Nó phù hợp để xử lý DOM, biểu mẫu, nhấp nút, chuyển trang, overlay, đọc/ghi dữ liệu người dùng và tăng cường trang.

Hành vi chạy:

1. Trình duyệt từ xa truy cập trang đích.
2. Hệ thống khởi tạo window.api trong trang và các iframe có thể truy cập.
3. Nếu đã cấu hình selector, script chỉ chạy khi selector khớp với phần tử.
4. Script có thể dùng trực tiếp api.config, api.user, api.dom, api.utils và api.header(). Xem phụ lục API script để biết API đầy đủ.

Ví dụ: đợi phần tử xuất hiện, ẩn vùng quảng cáo và đọc cấu hình sản phẩm.

await api.utils.wait(
  () => !!api.dom.querySelector(document, '.main-panel'),
  10000,
  200
);

const envName = api.config.envName || 'default';
console.log('current env:', envName);

const banner = api.dom.querySelector(document, '.ad-banner');
if (banner) {
  banner.style.display = 'none';
}

Script SSE

Khi pageScript = false và sseScript = true, script dùng để chặn dữ liệu Server-Sent Events. Hệ thống bọc EventSource và fetch trong trang, rồi xử lý các luồng có URL khớp và content type là text/event-stream.

Dạng thực thi:

async (data) => {
  // Nội dung script nhập trong content
}

Paramètre	Type	Description
data	string	SSE message hiện tại hoặc văn bản chunk dạng luồng.

Giá trị trả về phải là văn bản SSE mới. Nếu không trả về chuỗi, trang có thể nhận dữ liệu bất thường.

Ví dụ: thay thế văn bản trong dữ liệu SSE.

return data.replace('old text', 'new text');

Script chặn API thông thường

Khi pageScript = false và sseScript = false, script dùng để chặn response API thông thường. Hệ thống khớp URL API, đọc body response và chuyển body cho script để viết lại.

Dạng thực thi:

async (data, api, url) => {
  // Nội dung script nhập trong content
}

Paramètre	Type	Description
data	string	Body response gốc.
api	object	API script. Xem phụ lục API script.
url	string	URL API đang bị chặn.

Giá trị trả về phải là chuỗi body response mới.

Ví dụ: viết lại response API JSON.

const obj = JSON.parse(data);
obj.debug = true;
obj.fromScript = url.includes('/api/');
return JSON.stringify(obj);

Quy tắc khớp URL

Trường url hỗ trợ các quy tắc sau:

Écriture	Description	Exemple
*	Khớp tất cả URL	*
regex:<biểu thức>	Dùng biểu thức chính quy để khớp URL	regex:/api/chat
exact:<URL đầy đủ>	Khớp chính xác URL đầy đủ	exact:https://example.com/api/user
script:<biểu thức>	Thực thi biểu thức với URL hiện tại là biến url	script:url.includes('/api/')
Chuỗi thông thường	Kiểm tra URL đích có bắt đầu bằng chuỗi này không	https://example.com/api/

Với script production, nên dùng đường dẫn chính xác hoặc tiền tố ổn định để giảm rủi ro ảnh hưởng đến trang và API không liên quan.

Header request và response

Header request và response trong cấu hình trang dùng để ghi nhận các header được chỉ định. Script trang có thể đọc bằng api.header(). Xem phụ lục API script để biết tham số đầy đủ.

Các bước sử dụng:

1. Trong "Header request", thêm tên header request cần ghi nhận, ví dụ authorization, cookie.
2. Trong "Header response", thêm tên header response cần ghi nhận, ví dụ content-type, set-cookie.
3. Lưu cấu hình và truy cập trang đích qua trình duyệt từ xa.
4. Đọc trong script trang.

const authorization = await api.header('authorization', true);
const contentType = await api.header('content-type', false);

Lưu ý:

• Tên header được chuyển thành chữ thường khi đọc.
• Chỉ có thể đọc header đã cấu hình và thực sự đi qua trình duyệt từ xa.
• Header response có thể là mảng chuỗi; script nên xử lý cả mảng và giá trị rỗng.

Cú pháp selector

Selector script và selector điều khiển trang hỗ trợ CSS và XPath.

Écriture	Description
.button.primary	Selector CSS.
xpath://div[@id="app"]	Selector XPath.
.dialog:p	Trả về phần tử cha của phần tử khớp.
.dialog:p2	Trả về phần tử cha cách phần tử khớp hai cấp.
.header:bottom	Trong phương thức biên overlay, lấy biên dưới của phần tử đích.
.sidebar:right	Trong phương thức biên overlay, lấy biên phải của phần tử đích.

Quy trình thay đổi cấu hình

1. Ghi lại cấu hình hiện tại và nội dung script.
2. Sửa trên trang kiểm thử hoặc tài khoản kiểm thử.
3. Kiểm tra mở trang, đăng nhập, chuyển trang, đăng xuất, response API và sự kiện SSE.
4. Kiểm tra quy tắc điều khiển trang có ẩn hoặc xóa đúng phần tử không.
5. Đồng bộ cấu hình sang trang production.
6. Yêu cầu người dùng liên quan vào lại trang và kiểm tra.

Kiểm tra kết quả

• Thẻ trang trong frontend người dùng hiển thị theo cấu hình.
• Khi bật URL mã hóa, giao diện người dùng không hiển thị trực tiếp URL trang gốc.
• Script tùy chỉnh có hiệu lực theo quy tắc khớp khi trình duyệt từ xa truy cập trang đích.
• Script trang đọc đúng cấu hình, định vị phần tử và xử lý hành vi trang.
• Script SSE chỉ viết lại luồng sự kiện đích và không ảnh hưởng API thông thường.
• Script chặn API thông thường trả về body response hợp lệ.
• Sau khi trang đích thay đổi, script và selector vẫn khớp chính xác.

Câu hỏi thường gặp

• Hãy kiểm thử script trên trang kiểm thử trước khi dùng cho production.
• URL mã hóa chỉ ảnh hưởng hiển thị frontend và đường dẫn truy cập; nó không vượt qua chính sách bảo mật riêng của trang đích.
• Script trang phù hợp để xử lý DOM, biểu mẫu và hành vi trang.
• Script SSE chỉ phù hợp với luồng Server-Sent Events và không nên dùng cho API JSON thông thường.
• Script chặn API thông thường phải trả về chuỗi, nếu không trang đích có thể không phân tích được response.
• Tham số đầy đủ và ví dụ của API script có trong phụ lục API script.
• Cấu hình phân loại tài khoản phù hợp để định nghĩa hành vi khác nhau cho các cách đăng nhập khác nhau trên cùng một trang.