Quy tắc widget: kích thước, giới hạn hiệu năng và mã kiểm tra

Kích thước, loại file, giới hạn hiệu năng và mọi mã lỗi mà bước kiểm tra có thể trả về.

8 phút đọc Cập nhật 4 thg 11, 2026

Widget chạy trong overlay cùng mọi thứ khác, thường trên PC yếu. Vì vậy có các giới hạn cố định. Livedeck dùng cùng các con số ở ba nơi: tại tài liệu này, trong bài kiểm tra tự động trước khi duyệt và trong overlay khi LIVE.

Gói

File ZIP

5 MB

Tổng dung lượng sau giải nén

5 MB

Một file

2 MB

Tệp

200

Độ dài đường dẫn

180 ký tự

Độ sâu thư mục

8

manifest.json

64 KB

Loại file được phép: html, js, mjs, css, json, svg, txt, md, png, jpg, jpeg, webp, gif, mp3, ogg, wav, woff2. File văn bản phải là UTF-8. Ảnh, âm thanh và font phải đúng với phần mở rộng của chúng.

Những gì không được phép

  • Địa chỉ của trang khác trong HTML, CSS, JavaScript, SVG hoặc JSON (http://, https://, ws://, wss:// hoặc //host). Địa chỉ trong comment không làm trượt kiểm tra, nhưng admin sẽ thấy.
  • iframe, frame, object, embed, portal, base và meta refresh trong HTML
  • WebRTC (RTCPeerConnection, máy chủ STUN hoặc TURN), frame từ JavaScript (createElement("iframe") hoặc "<iframe" trong chuỗi) và gợi ý kết nối như dns-prefetch hoặc preconnect. Livedeck cũng tắt các tính năng này bên trong widget.
  • Script, event handler hoặc foreignObject trong file SVG
  • File ZIP mã hóa, liên kết tượng trưng và file nén nằm trong file nén

Admin cũng thấy cảnh báo về eval, new Function, WebAssembly, WebSocket, truy cập bộ nhớ hoặc cửa sổ overlay, mẫu đào coin và code bị làm rối hoặc minify. Cảnh báo không làm trượt kiểm tra ngay, nhưng cần có lý do chính đáng. Hãy gửi code minify kèm mã nguồn dễ đọc trong thư mục src/.

manifest.json, thư mục src/ và các file .md hoặc .txt chỉ dùng để duyệt. Livedeck không bao giờ cung cấp chúng cho overlay, nên code của bạn không thể tải chúng. Mỗi người dùng nhận widget của bạn qua một địa chỉ riêng.

Giới hạn hiệu năng

Sẵn sàng sau khi trang tải xong

3000 ms

Tải trang trong LIVE

15,000 ms

CPU khi không có sự kiện (trung bình)

2 %

CPU khi có rất nhiều sự kiện (trung bình)

15 %

Bộ nhớ (JavaScript)

64 MB

Số phần tử trên trang

3000

Lần chặn dài nhất

200 ms

Trong LIVE

  • Overlay kiểm tra mỗi 2000 ms. 3 lần phản hồi liên tiếp chậm hơn 1000 ms, hoặc 6000 ms không có phản hồi nào, sẽ khiến widget bị tắt.
  • Khi chính overlay bị treo (ví dụ vì tab đang chạy nền), điều đó không bao giờ bị tính cho widget của bạn.
  • Widget đã bị tắt sẽ tắt cho đến lần tải lại tiếp theo. Khi đó trình chỉnh sửa hiển thị "Widget đã dừng".
Mẹo: Giữ trang thật nhẹ: xóa các phần tử cũ (starter kit hiển thị tối đa maxCards thẻ), dùng hoạt ảnh CSS thay cho vòng lặp JavaScript và không chạy bộ hẹn giờ khi không có gì xảy ra.

Mã kiểm tra

Khi kiểm tra thất bại, trình chỉnh sửa hoặc seller studio sẽ hiển thị danh sách lý do. Tất cả các mã đều được liệt kê tại đây.

File ZIP

zip_too_large

File ZIP lớn hơn 5 MB.

zip_total_too_large

Lớn hơn 5 MB sau khi giải nén.

zip_file_too_large

Có file lớn hơn 2 MB.

zip_too_many_files

Nhiều hơn 200 file.

zip_not_zip

Không phải file ZIP hoặc file ZIP rỗng.

zip_multi_disk

Bị chia thành nhiều phần. Hãy nén tất cả vào một file.

zip64_unsupported

Không hỗ trợ ZIP64.

zip_trailing_data

Có dữ liệu thừa sau phần cuối của file ZIP.

zip_corrupt

File ZIP bị hỏng.

zip_encrypted

File ZIP được bảo vệ bằng mật khẩu.

zip_unsupported_method

Phương thức nén không được hỗ trợ. Chỉ cho phép Stored (không nén) và Deflate (mặc định).

zip_header_mismatch

Archive có thông tin mâu thuẫn.

zip_overlap

Các file bị chồng lấn trong archive.

zip_crc_mismatch

Checksum sai, có file bị hỏng.

zip_symlink

Có liên kết tượng trưng (symbolic link) trong gói.

zip_bad_name

Tên file không hợp lệ: ký tự không phải ASCII mà không có UTF-8, ../, đường dẫn tuyệt đối, ký tự đặc biệt, dài hơn 180 ký tự hoặc sâu hơn 8 thư mục.

zip_duplicate_name

Một file xuất hiện hai lần trong archive.

zip_nested_archive

Có archive bên trong archive (ví dụ ZIP trong ZIP).

File và nội dung

manifest_missing

Thiếu manifest.json. File này phải nằm ở cấp cao nhất của ZIP hoặc trong thư mục duy nhất của nó.

manifest_invalid

manifest.json không hợp lệ. Các lỗi được liệt kê bên dưới (mã trong "Tham chiếu manifest.json").

entry_missing

File khởi động được khai báo trong entry không có trong gói.

file_type_not_allowed

Loại file này không được phép.

file_content_mismatch

Nội dung không khớp với đuôi file (ví dụ file JPG đặt tên .png).

file_not_utf8

File văn bản không được lưu ở dạng UTF-8.

file_empty

File rỗng.

external_reference

File chứa địa chỉ của trang web khác (kèm số dòng).

forbidden_markup

HTML không được phép (iframe, frame, object, embed, portal, base, meta refresh) hoặc script trong file SVG.

forbidden_api

Code tìm cách vượt qua lớp chặn mạng: WebRTC (RTCPeerConnection, STUN/TURN), frame tạo từ JavaScript (createElement("iframe"), "<iframe" trong chuỗi) hoặc gợi ý kết nối (dns-prefetch, preconnect, prerender, prefetch).

Kiểm tra tự động

test_failed nghĩa là bài kiểm tra tự động đã vượt ít nhất một giới hạn. Từng lý do được liệt kê bên dưới, kèm giá trị đo được và giới hạn.

perf_no_ready

Widget không hề báo cho overlay sau khi tải. Thường là do thiếu <script src="/sdk/v1.js"> hoặc trang không bao giờ tải xong.

perf_ready_slow

Sẵn sàng quá muộn: hơn 3000 ms sau khi trang đã tải.

perf_unresponsive

Không phản hồi lệnh kiểm tra của overlay, hoặc phản hồi quá chậm (code làm treo trình duyệt).

perf_navigated

Widget đã chuyển sang trang khác hoặc tự tải lại trang.

perf_flood

Widget gửi quá nhiều tin nhắn đến overlay.

perf_idle_cpu

Hơn 2 % CPU khi không có gì xảy ra.

perf_storm_cpu

Hơn 15 % CPU khi có nhiều sự kiện.

perf_heap

Hơn 64 MB bộ nhớ.

perf_dom

Hơn 3000 phần tử trên trang.

perf_long_task

Làm treo trình duyệt lâu hơn 200 ms mỗi lần.

network_attempt

Cố tải nội dung từ trang web khác (có hiển thị host).

runtime_errors

Chỉ là gợi ý, không phải lý do thất bại: lỗi JavaScript trong lúc kiểm tra. Admin sẽ thấy lỗi đầu tiên.

Bài viết này có hữu ích không?