위젯 규칙: 크기, 성능 제한, 검사 코드

크기, 파일 형식, 성능 제한, 그리고 검사 실패 시 나오는 모든 코드예요.

8분 분량 2026년 11월 4일 업데이트

위젯은 오버레이에서 다른 모든 것과 함께 실행되고, 느린 PC인 경우도 많아요. 그래서 고정된 제한이 적용돼요. Livedeck은 같은 수치를 세 곳에서 써요: 여기 문서, 승인 전 자동 테스트, 그리고 LIVE 중 오버레이예요.

패키지

ZIP 파일

5 MB

압축 해제 후 전체

5 MB

단일 파일

2 MB

파일

200

경로 길이

180자

폴더 깊이

8

manifest.json

64 KB

허용 파일 형식: html, js, mjs, css, json, svg, txt, md, png, jpg, jpeg, webp, gif, mp3, ogg, wav, woff2. 텍스트 파일은 UTF-8이어야 해요. 이미지, 사운드, 폰트는 실제로 확장자와 일치해야 해요.

허용되지 않는 것

  • HTML, CSS, JavaScript, SVG, JSON 안의 다른 사이트 주소(http://, https://, ws://, wss:// 또는 //host). 주석 안의 주소는 검사에 실패하지 않지만 관리자에게 표시돼요.
  • HTML의 iframe, frame, object, embed, portal, base, meta refresh
  • WebRTC(RTCPeerConnection, STUN 또는 TURN 서버), JavaScript로 만드는 프레임(createElement("iframe") 또는 문자열 안의 "<iframe"), dns-prefetch나 preconnect 같은 연결 힌트. Livedeck은 위젯 안에서 이 기능들도 꺼 둬요.
  • SVG 파일 안의 스크립트, 이벤트 핸들러, foreignObject
  • 암호화된 ZIP 파일, 심볼릭 링크, 압축 파일 안의 압축 파일

관리자에게는 eval, new Function, WebAssembly, WebSocket, 저장소나 오버레이 창 접근, 채굴 패턴, 난독화되거나 압축(minify)된 코드에 대한 힌트도 표시돼요. 힌트만으로 바로 실패하지는 않지만 타당한 이유가 필요해요. 압축된 코드는 읽을 수 있는 소스와 함께 src/ 폴더에 넣어 제출하세요.

manifest.json, src/ 폴더, .md 또는 .txt 파일은 검토용이에요. Livedeck은 이 파일들을 오버레이에 제공하지 않으므로 코드에서 불러올 수 없어요. 사용자마다 각자의 주소로 위젯을 받아요.

성능 제한

페이지 로드 후 준비 완료

3000 ms

LIVE 중 페이지 로드

15,000 ms

이벤트 없을 때 CPU(평균)

2 %

이벤트가 매우 많을 때 CPU(평균)

15 %

메모리(JavaScript)

64 MB

페이지의 요소 수

3000

한 번에 가장 긴 블로킹

200 ms

LIVE 중

  • 오버레이는 2000ms마다 확인해요. 1000ms보다 느린 응답이 3번 연속되거나 6000ms 동안 응답이 없으면 위젯이 꺼져요.
  • 오버레이 자체가 멈춘 경우(예: 탭이 백그라운드에 있을 때)는 위젯 탓으로 계산되지 않아요.
  • 꺼진 위젯은 다음에 새로고침할 때까지 꺼진 상태로 유지돼요. 그동안 에디터에는 "위젯 중지됨"이 표시돼요.
팁: 페이지를 가볍게 유지하세요. 오래된 요소는 지우고(스타터 키트는 카드를 최대 maxCards개까지만 보여줘요), JavaScript 루프 대신 CSS 애니메이션을 쓰고, 아무 일도 없을 때는 타이머를 돌리지 마세요.

검사 코드

검사에 실패하면 에디터나 판매자 스튜디오에 실패 사유 목록이 표시돼요. 모든 코드를 여기에 정리했어요.

ZIP 파일

zip_too_large

ZIP 파일이 5 MB보다 커요.

zip_total_too_large

압축을 풀면 5 MB보다 커요.

zip_file_too_large

2 MB보다 큰 파일이 있어요.

zip_too_many_files

파일이 200개보다 많아요.

zip_not_zip

ZIP 파일이 아니거나 비어 있어요.

zip_multi_disk

여러 파트로 분할돼 있어요. 전부 하나의 파일로 압축하세요.

zip64_unsupported

ZIP64는 지원하지 않아요.

zip_trailing_data

ZIP 파일 끝 뒤에 추가 데이터가 있어요.

zip_corrupt

ZIP 파일이 손상됐어요.

zip_encrypted

ZIP 파일에 비밀번호가 걸려 있어요.

zip_unsupported_method

지원하지 않는 압축 방식이에요. Stored(압축 없음)와 Deflate(기본값)만 허용돼요.

zip_header_mismatch

아카이브 정보가 서로 맞지 않아요.

zip_overlap

아카이브 안에서 파일이 서로 겹쳐요.

zip_crc_mismatch

체크섬이 맞지 않아요. 파일이 손상됐어요.

zip_symlink

패키지에 심볼릭 링크가 있어요.

zip_bad_name

잘못된 파일 이름: UTF-8이 아닌 비ASCII 문자, ../, 절대 경로, 특수 문자, 180자 초과 또는 8단계보다 깊은 폴더.

zip_duplicate_name

아카이브에 같은 파일이 두 번 들어 있어요.

zip_nested_archive

아카이브 안에 또 다른 아카이브가 있어요(예: ZIP 안의 ZIP).

파일과 콘텐츠

manifest_missing

manifest.json이 없어요. ZIP 최상위나 ZIP 안의 유일한 폴더 안에 있어야 해요.

manifest_invalid

manifest.json이 올바르지 않아요. 오류는 그 아래에 표시돼요(코드는 "manifest.json 레퍼런스" 참고).

entry_missing

entry에 지정한 시작 파일이 패키지에 없어요.

file_type_not_allowed

허용되지 않는 파일 형식이에요.

file_content_mismatch

내용이 확장자와 맞지 않아요(예: .png라는 이름의 JPG).

file_not_utf8

텍스트 파일이 UTF-8로 저장되지 않았어요.

file_empty

파일이 비어 있어요.

external_reference

파일에 다른 사이트의 주소가 들어 있어요(해당 줄 표시).

forbidden_markup

허용되지 않는 HTML(iframe, frame, object, embed, portal, base, meta refresh)이나 SVG 파일 안의 스크립트가 있어요.

forbidden_api

네트워크 차단을 우회하는 코드가 있어요: WebRTC(RTCPeerConnection, STUN/TURN), JavaScript로 만든 프레임(createElement("iframe"), 문자열 안의 "<iframe") 또는 연결 힌트(dns-prefetch, preconnect, prerender, prefetch).

자동 테스트

test_failed는 자동 테스트에서 하나 이상의 한도를 넘었다는 뜻이에요. 개별 사유는 그 아래에 측정값과 한도와 함께 표시돼요.

perf_no_ready

위젯이 로드된 뒤 오버레이에 한 번도 응답하지 않았어요. 보통 <script src="/sdk/v1.js">가 빠졌거나 페이지 로딩이 끝나지 않는 경우예요.

perf_ready_slow

준비가 너무 늦어요: 페이지 로드 후 3000 ms가 넘었어요.

perf_unresponsive

오버레이의 확인 요청에 응답하지 않거나 너무 느려요(코드가 브라우저를 막고 있어요).

perf_navigated

위젯이 다른 페이지로 이동했거나 페이지를 새로고침했어요.

perf_flood

위젯이 오버레이에 메시지를 너무 많이 보내요.

perf_idle_cpu

아무 일도 없을 때 CPU를 2 % 넘게 써요.

perf_storm_cpu

이벤트가 많을 때 CPU를 15 % 넘게 써요.

perf_heap

메모리를 64 MB 넘게 써요.

perf_dom

페이지 요소가 3000개를 넘어요.

perf_long_task

브라우저를 한 번에 200 ms 넘게 막아요.

network_attempt

다른 사이트에서 무언가를 불러오려고 해요(호스트가 표시돼요).

runtime_errors

실패 사유가 아닌 참고용이에요: 테스트 중 JavaScript 오류가 났어요. 관리자는 첫 번째 오류를 볼 수 있어요.

이 글이 도움이 되었나요?