작성 안내
여기서 게시한 스크립트는 쿤쿤 브라우저에 설치됩니다. 클라이언트는 유저스크립트 관리자에 가깝지만 데스크톱 전체 기능은 아닙니다. 게시 전에 아래 규칙을 확인하면 설치 실패와 업데이트 누락을 줄일 수 있습니다.
사이트 언어는 URL 디렉터리입니다. 예: /zh-CN/, /zh-TW/, /ja/, /ko/, /id/, /en/. 목록은 기본적으로 그 언어의 스크립트만 보여 줍니다. 설치 주소 /s/번호.user.js 에는 언어 디렉터리가 없습니다.
게시
- 가입하고 로그인합니다.
- 「게시」를 열고 전체 소스를 붙여 넣습니다. 소스에는 ==UserScript== 헤더가 있어야 합니다.
- 업데이트할 때는 해당 스크립트의 「새 버전 게시」를 열고 새 소스를 붙여 넣습니다. 스크립트 ID는 바꾸지 마세요. 바꾸면 이미 설치한 사용자에게 업데이트가 가지 않습니다.
1인당 최대 50개입니다. 비공개로 하면 설치 링크는 404가 되고 검색에도 나오지 않습니다.
최소 동작 스크립트
// ==UserScript==
// @name 예시 스크립트
// @namespace https://scripts.ikunbrowser.com
// @version 1.0.0
// @description 예시 페이지에 한 줄을 추가
// @match https://example.com/*
// @grant none
// ==/UserScript==
(function () {
document.body.insertAdjacentHTML("beforeend", "<p>예시 스크립트가 실행됨</p>");
})();
메타데이터
최소한 @name과 @match 또는 @include 중 하나가 필요합니다.
| 필드 | 설명 |
|---|---|
@name | 언어 접미사가 없는 이름을 우선합니다. @name:zh-CN 같은 지역화 이름만 있으면 첫 번째를 씁니다. |
@name:zh-CN @description:ja | 언어가 붙은 이름과 설명입니다. 해당 디렉터리에서는 이것을 우선합니다. 단독 @name 이 없으면 첫 지역화 이름으로 스크립트 언어를 정합니다. |
@namespace @version @description | 모두 적는 것이 좋습니다. @description:xx는 기본 설명이 없을 때만 사용됩니다. |
@match | Chrome 일치 규칙입니다. *://, *.example.com, <all_urls>를 쓸 수 있습니다. 사이트 페이지는 이 규칙의 도메인으로 스크립트를 나열합니다. 주소는 /scripts/by-site/example.com 형태입니다. |
@include @exclude | 와일드카드 * ?, 또는 /정규식/i. |
@exclude-match | match 규칙으로 제외합니다. |
@run-at | document-start / document-end / document-body / document-idle. 생략하면 idle입니다. |
@noframes | 하위 프레임에서는 실행되지 않습니다. |
@grant | 알 수 없는 권한 때문에 설치가 실패하지는 않습니다. 구현되지 않은 함수는 있지만 아무 일도 하지 않습니다. |
@require @resource | http 또는 https만 가능합니다. 각각 최대 8개입니다. data:, file:, 상대 경로는 설치에 실패합니다. |
@connect @icon @author | 클라이언트는 무시하며 설치에 영향을 주지 않습니다. |
일치와 제외 규칙은 각각 최대 64개입니다. @require는 하나당 512KB 이하, 합계 약 1MB입니다. @resource는 하나당 256KB 이하입니다.
업데이트
클라이언트는 시맨틱 버전을 비교하지 않습니다. 새 @version은 앞뒤 공백을 뺀 문자열이 현재와 달라야 하며, 사용자가 수동으로 업데이트를 확인할 때만 바뀝니다. 둘 다 비어 있어도 같은 것으로 봅니다.
/s/{id}.user.js 를 내려줄 때 이 사이트는 메타데이터 블록 맨 앞에 @downloadURL과 @updateURL을 넣고 둘 다 그 주소를 가리킵니다. 클라이언트는 첫 항목만 보므로 뒤에 적은 업데이트 주소는 쓰이지 않습니다. @updateURL을 .meta.js로 두지 마세요. 클라이언트는 그 주소를 건너뜁니다.
브라우저는 백그라운드에서 자동 업데이트하지 않습니다. 사용자는 「설정 → 사용자 스크립트」에서 수동으로 확인합니다.
설치 링크
상세 페이지의 「설치」는 일반 .user.js 링크입니다. 쿤쿤 브라우저는 .user.js로 끝나는 http(s) 주소를 가로채 확인 창을 띄웁니다. 별도 프로토콜은 필요 없습니다.
Greasy Fork 주소도 그대로 됩니다. /scripts/번호.user.js, /scripts/번호.meta.js, /scripts/번호/code/이름.user.js, /scripts/번호-이름 상세, /scripts/번호.json 입니다. 쿤쿤 브라우저 업데이트 주소는 계속 /s/번호.user.js 입니다.
같은 스크립트, 같은 날, 같은 IP는 설치 1회로만 셉니다.
클라이언트에서 쓸 수 있는 API
동기 GM_*와 Promise 버전 GM.*가 모두 주입됩니다. 스크립트는 페이지 컨텍스트에서 실행되며 unsafeWindow는 페이지의 window입니다. 별도의 샌드박스는 없습니다.
| API | 동작 |
|---|---|
GM_addStyle GM_addElement | 스타일이나 요소를 넣습니다. |
GM_getValue | 스크립트별로 격리해 로컬에 저장합니다. 값 하나는 최대 32KB입니다. 변경 감시는 현재 페이지만 되며 탭을 넘지 않습니다. |
GM_xmlhttpRequest | 일반적인 메서드와 arraybuffer / blob을 지원합니다. 요청 본문은 최대 256KB, 응답은 최대 1MB입니다. 공개 인터넷 http(s)만 가능하고 로컬 주소는 거부됩니다. 페이지 JS와 브라우저 프록시를 거치지 않습니다. |
GM_setClipboard GM_download GM_openInTab | 클립보드, 앱 안 다운로드 확인, 새 탭에서 http(s) 열기. |
GM_getResourceText GM_getResourceURL | 설치할 때 캐시한 리소스를 읽습니다. |
GM_registerMenuCommand | 현재 페이지에 명령을 등록하면 하단 막대에 「스크립트 명령」이 나타납니다. |
GM_notification | 알림만 보여 주고 클릭 콜백은 없습니다. |
GM_getTab | 현재 스크립트 프로세스 안의 메모리 객체일 뿐, 여러 창이 아닙니다. |
다음은 @grant를 적어도 설치되지만 함수는 아무 일도 하지 않습니다. GM_cookie, GM_webRequest, 그리고 위 표에 없는 다른 권한입니다. 요청 변경이나 쿠키 읽기/쓰기에 의존하지 마세요.
실행 시 주의
- 소스는 512KB 이하입니다. 설치된 스크립트는 최대 64개입니다.
- 페이지 CSP가 unsafe-eval을 막으면 스크립트는 조용히 실패합니다.
- SPA에서 주소가 바뀌면, 새로 일치하고 아직 실행되지 않은 스크립트만 실행됩니다. 이미 실행된 것은 다시 실행하지 않습니다.
- document-start는 새로 연 탭에서 더 완전합니다. 방금 설치한 현재 페이지는 문서 맨 앞 시점을 놓칠 수 있습니다.
- 홈과 about:에는 주입하지 않습니다. 스크립트 오류는 삼켜지며, 페이지에서 관리자형 실행 로그는 보이지 않습니다.
어떤 스크립트가 적합한가
DOM 변경, 스타일 추가, 적은 설정 저장, 가끔 요청, 클립보드, 파일 다운로드, 메뉴로 켜고 끄기, jQuery 같은 @require에 적합합니다.
쿠키에 크게 의존하거나, 네트워크를 가로채거나, 문서의 정확한 시작에 맞추거나, CSP가 엄격하거나, 스크립트와 의존성이 매우 크면 적합하지 않습니다.