chrome.userScripts

설명

userScripts API를 사용하여 사용자 스크립트 컨텍스트에서 사용자 스크립트를 실행합니다.

권한

userScripts

chrome.userScripts API를 사용하려면 manifest.json에 "userScripts" 권한을 추가하고 스크립트를 실행하려는 사이트의 경우 "host_permissions"를 추가합니다.

{
  "name": "User script test extension",
  "manifest_version": 3,
  "minimum_chrome_version": "120",
  "permissions": [
    "userScripts"
  ],
  "host_permissions": [
    "*://example.com/*"
  ]
}

가용성

Chrome 120 이상 MV3 이상

개념 및 사용

사용자 스크립트는 웹페이지의 모양이나 동작을 수정하기 위해 웹페이지에 삽입되는 코드입니다. 스크립트는 사용자가 만들거나 스크립트 저장소 또는 사용자 스크립트 확장 프로그램에서 다운로드합니다.

확장 프로그램 사용자를 위한 개발자 모드

확장 프로그램 개발자는 Chrome 설치 시 이미 개발자 모드를 사용 설정합니다. 사용자 스크립트 확장 프로그램의 경우 사용자도 개발자 모드를 사용 설정해야 합니다. 다음은 자체 문서에 복사하여 붙여넣을 수 있는 안내입니다.

  1. 새 탭에서 chrome://extensions를 입력하여 확장 프로그램 페이지로 이동합니다. (기본적으로 chrome:// URL은 연결할 수 없습니다.)

  2. 개발자 모드 옆에 있는 전환 스위치를 클릭하여 개발자 모드를 사용 설정합니다.

    광고 확장 페이지

    확장 프로그램 페이지 (chrome://extensions)

chrome.userScripts에서 오류가 발생하는지 확인하여 개발자 모드가 사용 설정되었는지 확인할 수 있습니다. 예를 들면 다음과 같습니다.

function isUserScriptsAvailable() {
  try {
    // Property access which throws if developer mode is not enabled.
    chrome.userScripts;
    return true;
  } catch {
    // Not available.
    return false;
  }
}

격리된 환경에서 작업

사용자 스크립트와 콘텐츠 스크립트는 모두 격리된 월드 또는 기본 월드에서 실행할 수 있습니다. 격리된 세계는 호스트 페이지나 다른 확장 프로그램에서 액세스할 수 없는 실행 환경입니다. 이렇게 하면 사용자 스크립트가 호스트 페이지 또는 다른 확장 프로그램의 사용자 및 콘텐츠 스크립트에 영향을 미치지 않고 JavaScript 환경을 변경할 수 있습니다. 반대로 사용자 스크립트 (및 콘텐츠 스크립트)는 호스트 페이지 또는 다른 확장 프로그램의 사용자 및 콘텐츠 스크립트에 표시되지 않습니다. 기본 세계에서 실행되는 스크립트는 호스트 페이지 및 기타 확장 프로그램에 액세스할 수 있으며 호스트 페이지 및 기타 확장 프로그램에 표시됩니다. 지구를 선택하려면 userScripts.register()를 호출할 때 "USER_SCRIPT" 또는 "MAIN"를 전달합니다.

USER_SCRIPT 환경에 콘텐츠 보안 정책을 구성하려면 userScripts.configureWorld()를 호출합니다.

chrome.userScripts.configureWorld({
  csp: "script-src 'self'"
});

메시지

콘텐츠 스크립트 및 오프스크린 문서와 마찬가지로 사용자 스크립트는 메시지를 사용하여 확장 프로그램의 다른 부분과 통신합니다. 즉, 확장 프로그램의 다른 부분과 마찬가지로 runtime.sendMessage() 및 runtime.connect()를 호출할 수 있습니다. 그러나 전용 이벤트 핸들러를 사용하여 수신됩니다 (즉, onMessage 또는 onConnect를 사용하지 않음). 이러한 핸들러는 runtime.onUserScriptMessage 및 runtime.onUserScriptConnect라고 합니다. 전용 핸들러를 사용하면 신뢰도가 낮은 컨텍스트인 사용자 스크립트의 메시지를 더 쉽게 식별할 수 있습니다.

메시지를 보내기 전에 messaging 인수를 true로 설정하여 configureWorld()를 호출해야 합니다. csp 및 messaging 인수를 동시에 전달할 수 있습니다.

chrome.userScripts.configureWorld({
  messaging: true
});

확장 프로그램 업데이트

확장 프로그램이 업데이트되면 사용자 스크립트가 삭제됩니다. 확장 프로그램 서비스 워커의 runtime.onInstalled 이벤트 핸들러에서 코드를 실행하여 다시 추가할 수 있습니다. 이벤트 콜백에 전달된 "update" 이유에만 응답합니다.

예

이 예는 샘플 저장소의 userScript 샘플에서 가져온 것입니다.

스크립트 등록

다음 예는 register()의 기본 호출을 보여줍니다. 첫 번째 인수는 등록할 스크립트를 정의하는 객체 배열입니다. 여기에 표시된 것보다 더 많은 옵션이 있습니다.

chrome.userScripts.register([{
  id: 'test',
  matches: ['*://*/*'],
  js: [{code: 'alert("Hi!")'}]
}]);

유형

ExecutionWorld

사용자 스크립트가 실행되는 JavaScript 세계입니다.

열거형

'MAIN'
호스트 페이지의 JavaScript와 공유되는 실행 환경인 DOM의 실행 환경을 지정합니다.

'USER_SCRIPT'
사용자 스크립트에만 해당하며 페이지의 CSP에서 제외되는 실행 환경을 지정합니다.

RegisteredUserScript

속성

  • allFrames

    불리언 선택사항

    이 값이 true이면 프레임이 탭에서 최상위 프레임이 아니더라도 모든 프레임에 삽입됩니다. 각 프레임은 URL 요구사항에 대해 개별적으로 확인됩니다. URL 요구사항이 충족되지 않으면 하위 프레임에 삽입되지 않습니다. 기본값은 false이며, 즉 최상위 프레임만 일치합니다.

  • excludeGlobs

    string[] 선택사항

    이 사용자 스크립트가 삽입되지 않는 페이지의 와일드 카드 패턴을 지정합니다.

  • excludeMatches

    string[] 선택사항

    이 사용자 스크립트가 삽입될 페이지를 제외합니다. 이러한 문자열의 문법에 관한 자세한 내용은 일치 패턴을 참고하세요.

  • id

    문자열

    API 호출에 지정된 사용자 스크립트의 ID입니다. 이 속성은 생성된 스크립트 ID의 접두사로 예약되어 있으므로 '_'로 시작해서는 안 됩니다.

  • includeGlobs

    string[] 선택사항

    이 사용자 스크립트가 삽입될 페이지의 와일드 카드 패턴을 지정합니다.

  • js

    ScriptSource[] 선택사항

    일치하는 페이지에 삽입할 스크립트의 소스를 정의하는 ScriptSource 객체 목록입니다. 이 속성은 ${ref:register}에 지정해야 하며 지정된 경우 비어 있지 않은 배열이어야 합니다.

  • 일치

    string[] 선택사항

    이 사용자 스크립트가 삽입될 페이지를 지정합니다. 이러한 문자열의 문법에 관한 자세한 내용은 일치 패턴을 참고하세요. 이 속성은 ${ref:register}에 지정해야 합니다.

  • runAt

    RunAt 선택사항

    JavaScript 파일이 웹페이지에 삽입되는 시점을 지정합니다. 기본값은 document_idle입니다.

  • 세계

    ExecutionWorld 선택사항

    스크립트를 실행할 JavaScript 실행 환경입니다. 기본값은 `USER_SCRIPT`입니다.

  • worldId

    문자열 선택사항

    대기 중

    지정된 경우 실행할 특정 사용자 스크립트 월드 ID를 지정합니다. world가 생략되었거나 USER_SCRIPT인 경우에만 유효합니다. 생략하면 스크립트가 기본 사용자 스크립트 세계에서 실행됩니다. 선행 밑줄 (_)이 있는 값은 예약되어 있습니다.

ScriptSource

속성

  • 코드

    문자열 선택사항

    삽입할 JavaScript 코드가 포함된 문자열입니다. file 또는 code 중 정확히 하나만 지정해야 합니다.

  • 파일

    문자열 선택사항

    확장 프로그램의 루트 디렉터리를 기준으로 삽입할 JavaScript 파일의 경로입니다. file 또는 code 중 정확히 하나만 지정해야 합니다.

UserScriptFilter

속성

  • ids

    string[] 선택사항

    getScripts는 이 목록에 지정된 ID가 있는 스크립트만 반환합니다.

WorldProperties

속성

  • csp

    문자열 선택사항

    세계 csp를 지정합니다. 기본값은 `ISOLATED` 전 세계 csp입니다.

  • 메시지

    불리언 선택사항

    메시지 API가 노출되는지 여부를 지정합니다. 기본값은 false입니다.

  • worldId

    문자열 선택사항

    대기 중

    업데이트할 특정 사용자 스크립트 월드의 ID를 지정합니다. 제공하지 않으면 기본 사용자 스크립트 월드의 속성을 업데이트합니다. 선행 밑줄 (_)이 있는 값은 예약되어 있습니다.

메서드

configureWorld()

Promise 
chrome.userScripts.configureWorld(
  properties: WorldProperties,
  callback?: function,
)

`USER_SCRIPT` 실행 환경을 구성합니다.

매개변수

  • 사용자 스크립트 월드 구성을 포함합니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • Promise<void>

    Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getScripts()

Promise 
chrome.userScripts.getScripts(
  filter?: UserScriptFilter,
  callback?: function,
)

이 확장 프로그램에 대해 동적으로 등록된 모든 사용자 스크립트를 반환합니다.

매개변수

  • filter

    UserScriptFilter 선택사항

    지정된 경우 이 메서드는 일치하는 사용자 스크립트만 반환합니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    (scripts: RegisteredUserScript[]) => void

반환 값

  • Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getWorldConfigurations()

Promise 대기 중
chrome.userScripts.getWorldConfigurations(
  callback?: function,
)

등록된 모든 세계 구성을 검색합니다.

매개변수

반환 값

  • Promise<WorldProperties[]>

    Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

register()

Promise 
chrome.userScripts.register(
  scripts: RegisteredUserScript[],
  callback?: function,
)

이 확장 프로그램에 하나 이상의 사용자 스크립트를 등록합니다.

매개변수

  • 스크립트

    RegisteredUserScript[]

    등록할 사용자 스크립트 목록을 포함합니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • Promise<void>

    Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

resetWorldConfiguration()

Promise 대기 중
chrome.userScripts.resetWorldConfiguration(
  worldId?: string,
  callback?: function,
)

사용자 스크립트 월드의 구성을 재설정합니다. 지정된 ID로 월드에 삽입하는 모든 스크립트는 기본 월드 구성을 사용합니다.

매개변수

  • worldId

    문자열 선택사항

    재설정할 사용자 스크립트 월드의 ID입니다. 생략하면 기본 월드의 구성을 재설정합니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • Promise<void>

    Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

unregister()

Promise 
chrome.userScripts.unregister(
  filter?: UserScriptFilter,
  callback?: function,
)

이 확장 프로그램에 대해 동적으로 등록된 모든 사용자 스크립트를 등록 취소합니다.

매개변수

  • filter

    UserScriptFilter 선택사항

    지정된 경우 이 메서드는 일치하는 사용자 스크립트만 등록 취소합니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • Promise<void>

    Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

update()

Promise 
chrome.userScripts.update(
  scripts: RegisteredUserScript[],
  callback?: function,
)

이 확장 프로그램의 사용자 스크립트를 하나 이상 업데이트합니다.

매개변수

  • 스크립트

    RegisteredUserScript[]

    업데이트할 사용자 스크립트 목록을 포함합니다. 속성은 이 객체에 지정된 경우에만 기존 스크립트에 대해 업데이트됩니다. 스크립트 파싱/파일 유효성 검사 중에 오류가 발생하거나 지정된 ID가 완전히 등록된 스크립트에 해당하지 않으면 스크립트가 업데이트되지 않습니다.

  • 콜백

    함수 선택사항

    callback 매개변수는 다음과 같습니다. 

    () => void

반환 값

  • Promise<void>

    Promise는 매니페스트 V3 이상에서 지원되지만 이전 버전과의 호환성을 위해 콜백이 제공됩니다. 동일한 함수 호출에서 둘 다 사용할 수는 없습니다. 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.