chrome.runtime

설명

chrome.runtime API를 사용하여 서비스 워커를 검색하고, 매니페스트에 관한 세부정보를 반환하고, 확장 프로그램 수명 주기에서 이벤트를 수신 대기하고 이에 응답합니다. 또한 이 API를 사용하여 URL의 상대 경로를 정규화된 URL로 변환할 수 있습니다.

이 API의 구성원은 대부분 권한이 필요하지 않습니다. connectNative(), sendNativeMessage(), onNativeConnect에 필요한 권한입니다.

다음 예는 매니페스트에서 "nativeMessaging" 권한을 선언하는 방법을 보여줍니다.

manifest.json:

{
  "name": "My extension",
  ...
  "permissions": [
    "nativeMessaging"
  ],
  ...
}

개념 및 사용법

Runtime API는 확장 프로그램이 실행되는 여러 영역을 지원하는 메서드를 제공합니다. 사용할 수 있습니다.

메시지 전달

확장 프로그램은 다음 메서드 및 이벤트를 사용하여 확장 프로그램 내의 다양한 컨텍스트 및 다른 확장 프로그램과 통신할 수 있습니다. connect(), onConnect님, onConnectExternal, sendMessage(), onMessage 및 onMessageExternal 또한 확장 프로그램은 connectNative() 및 sendNativeMessage()

를 통해 개인정보처리방침을 정의할 수 있습니다.

를 통해 개인정보처리방침을 정의할 수 있습니다.

참고: 제목에 대한 개요는 메시지 전달을 참조하세요.

확장 프로그램 및 플랫폼 메타데이터 액세스

이러한 메서드를 사용하면 확장 프로그램 및 있습니다. 이 카테고리의 메서드는 다음과 같습니다. getManifest() 외 getPlatformInfo()

확장 프로그램 수명 주기 및 옵션 관리

이러한 속성을 사용하면 확장 프로그램에서 몇 가지 메타 작업을 실행하고 옵션 페이지를 표시할 수 있습니다. 이 카테고리의 메서드와 이벤트에는 다음이 포함됩니다. onInstalled님, onStartup님, openOptionsPage()님, reload(), requestUpdateCheck() 및 setUninstallURL()

도우미 유틸리티

이러한 메서드는 내부 리소스 표현을 데이터 세트로 변환하는 것과 같은 지원합니다. 이 카테고리의 메서드는 다음과 같습니다. getURL()

키오스크 모드 유틸리티

이러한 메서드는 ChromeOS에서만 사용할 수 있으며 주로 키오스크 구현을 지원하기 위해 존재합니다. 이 카테고리의 메서드는 다음과 같습니다. restart() 및 restartAfterDelay()`

압축해제된 확장 프로그램 동작

압축해제된 확장 프로그램이 다시 로드되면 업데이트로 처리됩니다. 즉, chrome.runtime.onInstalled 이벤트가 "update" 이유와 함께 실행됩니다. 이 확장 프로그램이 chrome.runtime.reload()로 새로고침되는 경우가 포함됩니다.

사용 사례

웹페이지에 이미지 추가

웹페이지가 다른 도메인에서 호스팅되는 애셋에 액세스하려면 리소스의 전체 URL을 지정해야 합니다. (예: <img src="https://example.com/logo.png">) 확장 애셋을 웹페이지일 것입니다. 두 가지 차이점은 확장 프로그램의 애셋은 웹으로 노출되어야 한다는 것입니다. 리소스와 일반적으로 콘텐츠 스크립트가 광고 확장 애셋을 선택합니다.

이 예에서 확장 프로그램은 콘텐츠가 표시되는 페이지에 logo.png을 스크립트가 runtime.getURL()를 사용하여 삽입됩니다. URL을 입력합니다. 하지만 먼저 매니페스트에서 애셋을 웹 액세스 가능 리소스로 선언해야 합니다.

manifest.json:

{
  ...
  "web_accessible_resources": [
    {
      "resources": [ "logo.png" ],
      "matches": [ "https://*/*" ]
    }
  ],
  ...
}

content.js:

{ // Block used to avoid setting global variables
  const img = document.createElement('img');
  img.src = chrome.runtime.getURL('logo.png');
  document.body.append(img);
}

콘텐츠 스크립트에서 서비스 워커로 데이터 전송

확장 프로그램의 콘텐츠 스크립트에는 확장 프로그램의 다른 부분에서 관리하는 데이터가 필요한 경우가 많습니다. 같은 역할을 할 수 있습니다 두 개의 브라우저 창이 동일한 웹페이지에 열리는 것처럼 두 컨텍스트가 서로의 값에 직접 액세스할 수 없습니다. 대신 확장 프로그램에서 message를 사용할 수 있습니다. 를 전달하여을 조정합니다.

이 예에서 콘텐츠 스크립트에는 확장 프로그램 서비스 워커의 일부 데이터가 UI를 초기화합니다. 이 데이터를 가져오기 위해 개발자가 정의한 get-user-data 메시지를 전달합니다. 서비스 워커에 연결하고 사용자 정보의 사본으로 응답합니다.

content.js:

// 1. Send a message to the service worker requesting the user's data
chrome.runtime.sendMessage('get-user-data', (response) => {
  // 3. Got an asynchronous response with the data from the service worker
  console.log('received user data', response);
  initializeUI(response);
});

service-worker.js:

// Example of a simple user data object
const user = {
  username: 'demo-user'
};

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
  // 2. A page requested user data, respond with a copy of `user`
  if (message === 'get-user-data') {
    sendResponse(user);
  }
});

제거에 관한 의견 수집

많은 확장 프로그램이 제거 후 설문조사를 사용하여 확장 프로그램이 더 나은 서비스를 제공할 수 있는 방법을 파악합니다. 사용자 유지율을 높일 수 있습니다. 다음 예는 이 기능을 추가하는 방법을 보여줍니다.

background.js:

chrome.runtime.onInstalled.addListener(details => {
  if (details.reason === chrome.runtime.OnInstalledReason.INSTALL) {
    chrome.runtime.setUninstallURL('https://example.com/extension-survey');
  }
});

예

더 많은 Runtime API 예시는 Manifest V3 - 웹 액세스 가능한 리소스 데모를 참고하세요.

유형

ContextFilter

Chrome 114 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

특정 확장 프로그램 컨텍스트와 일치시킬 필터입니다. 일치하는 컨텍스트는 지정된 모든 필터와 일치해야 합니다. 지정되지 않은 필터는 사용 가능한 모든 컨텍스트와 일치합니다. 따라서 `{}` 필터는 이용 가능한 모든 컨텍스트와 일치합니다.

속성

• contextIds

  string[] 선택사항

• contextTypes

  ContextType[] 선택사항

• documentIds

  string[] 선택사항

• documentOrigins

  string[] 선택사항

• documentUrls

  string[] 선택사항

• frameIds

  number[] 선택사항

• 시크릿 모드

  불리언 선택사항

• tabIds

  number[] 선택사항

• windowIds

  number[] 선택사항

ContextType

Chrome 114 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

열거형

"TAB"
컨텍스트 유형을 탭으로 지정

"POPUP"
컨텍스트 유형을 확장 프로그램 팝업 창으로 지정

"BACKGROUND"
컨텍스트 유형을 서비스 워커로 지정합니다.

"OFFSCREEN_DOCUMENT"
컨텍스트 유형을 오프스크린 문서로 지정합니다.

"SIDE_PANEL"
컨텍스트 유형을 측면 패널로 지정합니다.

ExtensionContext

Chrome 114 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

확장 프로그램 콘텐츠를 호스팅하는 컨텍스트입니다.

속성

• 컨텍스트 ID

  문자열

  이 컨텍스트의 고유 식별자입니다.

• contextType

  ContextType

  여기에 해당하는 컨텍스트 유형입니다.

• documentId

  문자열(선택사항)

  이 컨텍스트와 연결된 문서의 UUID이거나 이 컨텍스트가 문서에 없는 경우 정의되지 않습니다.

• documentOrigin

  문자열(선택사항)

  이 컨텍스트와 연결된 문서의 출처이거나, 컨텍스트가 문서에서 호스팅되지 않은 경우 정의되지 않습니다.

• documentUrl

  문자열(선택사항)

  이 컨텍스트와 연결된 문서의 URL입니다. 또는 컨텍스트가 문서에서 호스팅되지 않은 경우 정의되지 않습니다.

• frameId

  숫자

  이 컨텍스트의 프레임 ID 또는 이 컨텍스트가 프레임에서 호스팅되지 않은 경우 -1입니다.

• 시크릿 모드

  부울

  컨텍스트가 시크릿 프로필과 연결되어 있는지 여부입니다.

• tabId

  숫자

  이 컨텍스트의 탭 ID 또는 이 컨텍스트가 탭에서 호스팅되지 않은 경우 -1입니다.

• windowId

  숫자

  이 컨텍스트의 창 ID 또는 이 컨텍스트가 창에서 호스팅되지 않는 경우 -1입니다.

MessageSender

메시지 또는 요청을 보낸 스크립트 컨텍스트에 대한 정보가 포함된 객체입니다.

속성

• documentId

  문자열(선택사항)

  Chrome 106 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  연결을 연 문서의 UUID입니다.

• documentLifecycle

  문자열(선택사항)

  Chrome 106 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  연결을 연 문서의 수명 주기는 포트가 생성된 시점입니다. 포트 생성 이후 문서의 수명 주기 상태가 변경되었을 수 있습니다.

• frameId

  숫자 선택사항

  연결을 연 프레임입니다. 최상위 프레임은 0, 하위 프레임은 양수입니다. tab가 설정된 경우에만 설정됩니다.

• id

  문자열(선택사항)

  연결을 연 확장 프로그램의 ID입니다(있는 경우).

• nativeApplication

  문자열(선택사항)

  Chrome 74 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  연결을 연 네이티브 애플리케이션의 이름입니다(있는 경우).

• 출처

  문자열(선택사항)

  Chrome 80 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  연결을 시작한 페이지 또는 프레임의 출처입니다. URL 속성 (예: about:blank)과 다르거나 불투명 (예: 샌드박스 처리된 iframe)일 수 있습니다. 이 속성은 URL에서 즉시 확인할 수 없는 경우 출처를 신뢰할 수 있는지 식별하는 데 유용합니다.

• 탭

  탭 선택사항

  연결을 연 tabs.Tab입니다(있는 경우). 이 속성은 탭 (콘텐츠 스크립트 포함)에서 연결이 열린 경우에만 존재하며, 수신기가 앱이 아닌 확장 프로그램인 경우에만 표시됩니다.

• tlsChannelId

  문자열(선택사항)

  연결을 연 페이지 또는 프레임의 TLS 채널 ID(확장 프로그램에서 요청한 경우 및 사용 가능한 경우)입니다.

• URL

  문자열(선택사항)

  연결을 연 페이지 또는 프레임의 URL입니다. 발신자가 iframe에 있다면 메일을 호스팅하는 페이지의 URL이 아니라 iframe의 URL입니다.

OnInstalledReason

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

이 이벤트가 전달되는 이유입니다.

열거형

"install"
이벤트 이유를 설치로 지정합니다.

"update"
이벤트 이유를 확장 프로그램 업데이트로 지정합니다.

"chrome_update"
이벤트 이유를 Chrome 업데이트로 지정합니다.

"shared_module_update"
이벤트 이유를 공유 모듈의 업데이트로 지정합니다.

OnRestartRequiredReason

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

이벤트가 전달되는 이유입니다. 'app_update' 이 사용됩니다. 'os_update' 는 브라우저/OS가 최신 버전으로 업데이트되어 다시 시작해야 할 때 사용됩니다. '주기적' 시스템이 기업 정책에 설정된 허용된 가동 시간을 초과하여 실행될 때 사용됩니다.

열거형

"app_update"
이벤트 이유를 앱 업데이트로 지정합니다.

"os_update"
이벤트 이유를 운영체제 업데이트로 지정합니다.

"periodic"
이벤트 이유를 앱의 주기적인 다시 시작으로 지정합니다.

PlatformArch

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

머신의 프로세서 아키텍처

열거형

"arm"
프로세서 아키텍처를 arm으로 지정합니다.

"arm64"
프로세서 아키텍처를 arm64로 지정합니다.

"x86-32"
프로세서 아키텍처를 x86-32로 지정합니다.

"x86-64"
프로세서 아키텍처를 x86-64로 지정합니다.

"mips"
프로세서 아키텍처를 mips로 지정합니다.

"mips64"
프로세서 아키텍처를 mips64로 지정합니다.

PlatformInfo

현재 플랫폼에 대한 정보가 포함된 객체입니다.

속성

• arch

  PlatformArch

  머신의 프로세서 아키텍처

• nacl_arch

  PlatformNaclArch

  기본 클라이언트 아키텍처 이는 일부 플랫폼의 아치와 다를 수 있습니다.

• os

  PlatformOs

  Chrome이 실행 중인 운영체제입니다.

PlatformNaclArch

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

기본 클라이언트 아키텍처 이는 일부 플랫폼의 아치와 다를 수 있습니다.

열거형

"arm"
네이티브 클라이언트 아키텍처를 arm으로 지정합니다.

"x86-32"
네이티브 클라이언트 아키텍처를 x86-32로 지정합니다.

"x86-64"
네이티브 클라이언트 아키텍처를 x86-64로 지정합니다.

"mips"
네이티브 클라이언트 아키텍처를 mips로 지정합니다.

"mips64"
네이티브 클라이언트 아키텍처를 mips64로 지정합니다.

PlatformOs

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

Chrome이 실행 중인 운영체제입니다.

열거형

"mac"
MacOS 운영체제를 지정합니다.

"win"
Windows 운영체제를 지정합니다.

"android"
Android 운영체제를 지정합니다.

"cros"
Chrome 운영체제를 지정합니다.

"linux"
Linux 운영체제를 지정합니다.

"openbsd"
OpenBSD 운영체제를 지정합니다.

"fuchsia"
Fuchsia 운영체제를 지정합니다.

Port

다른 페이지와 양방향 통신을 할 수 있는 객체입니다. 자세한 내용은 수명이 긴 연결을 참고하세요.

속성

• 이름

  문자열

  runtime.connect 호출에 지정된 포트 이름입니다.

• onDisconnect

  이벤트<functionvoid>

  포트가 다른 쪽 끝에서 연결 해제되면 실행됩니다. 오류로 인해 포트의 연결이 해제된 경우 runtime.lastError를 설정할 수 있습니다. 연결 해제를 통해 포트가 닫히면 이 이벤트는 다른 쪽에서만 실행됩니다. 이 이벤트는 최대 한 번 시작됩니다 (포트 수명 참고).

  onDisconnect.addListener 함수는 다음과 같습니다.

  (callback: function) => {...}

  • 콜백

    함수

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

    (port: Port) => void

    • 포트

      포트

• onMessage

  이벤트<functionvoid>

  이 이벤트는 포트의 다른 쪽 끝에서 postMessage를 호출하면 시작됩니다.

  onMessage.addListener 함수는 다음과 같습니다.

  (callback: function) => {...}

  • 콜백

    함수

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

    (message: any, port: Port) => void

    • 메시지

      모두

    • 포트

      포트

• sender

  MessageSender 선택사항

  이 속성은 onConnect / onConnectExternal / onConnectNative 리스너로 전달된 포트에만 존재합니다.

• 연결 해제

  void

  포트 연결을 즉시 해제합니다. 이미 연결이 끊긴 포트에서 disconnect()를 호출해도 효과가 없습니다. 포트가 연결 해제되면 이 포트로 새 이벤트가 디스패치되지 않습니다.

  disconnect 함수는 다음과 같습니다.

  () => {...}

• postMessage

  void

  포트의 다른 쪽 끝으로 메시지를 전송합니다. 포트의 연결이 끊어지면 오류가 발생합니다.

  postMessage 함수는 다음과 같습니다.

  (message: any) => {...}

  • 메시지

    모두

    Chrome 52 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    전송할 메시지입니다. 이 객체는 JSON 지정이 가능해야 합니다.

RequestUpdateCheckStatus

Chrome 44 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

업데이트 확인 결과입니다.

열거형

"throttled"
상태 확인이 제한되었음을 지정합니다. 이는 짧은 시간 내에 확인을 반복한 후에 발생할 수 있습니다.

"no_update"
설치할 수 있는 업데이트가 없음을 명시합니다.

"update_available"
설치할 수 있는 업데이트가 있음을 명시합니다.

속성

id

확장 프로그램/앱의 ID입니다.

유형

문자열

lastError

API 함수 호출이 실패하면 오류 메시지로 채워집니다. 정의되지 않습니다. 이는 해당 함수의 콜백 범위 내에서만 정의됩니다. 오류가 생성되었지만 콜백 내에서 runtime.lastError에 액세스하지 않으면 오류가 발생한 API 함수가 나열된 메시지가 콘솔에 로깅됩니다. 프로미스를 반환하는 API 함수는 이 속성을 설정하지 않습니다.

유형

객체

속성

• 메시지

  문자열(선택사항)

  발생한 오류에 대한 세부정보입니다.

메서드

connect()

chrome.runtime.connect(
  extensionId?: string,
  connectInfo?: object,
)

확장 프로그램 (예: 백그라운드 페이지) 또는 다른 확장 프로그램/앱 내에서 리스너의 연결을 시도합니다. 이는 확장 프로그램 프로세스에 연결하는 콘텐츠 스크립트, 앱/확장 프로그램 간 통신, 웹 메시지에 유용합니다. 콘텐츠 스크립트의 리스너에는 연결되지 않습니다. 확장 프로그램은 tabs.connect를 통해 탭에 삽입된 콘텐츠 스크립트에 연결할 수 있습니다.

매개변수

• extensionId

  문자열(선택사항)

  연결할 확장 프로그램의 ID입니다. 생략하면 자체 확장 프로그램으로 연결을 시도합니다. 웹 메시징을 위해 웹페이지에서 메시지를 보내는 경우 필수 항목입니다.

• connectInfo

  객체(선택사항)

  • includeTlsChannelId

    불리언 선택사항

    연결 이벤트를 수신 대기하는 프로세스의 경우 TLS 채널 ID를 onConnectExternal로 전달할지 여부를 나타냅니다.

  • 이름

    문자열(선택사항)

    연결 이벤트를 수신 대기하는 프로세스의 경우 onConnect로 전달됩니다.

반환 값

• 포트

  메시지를 보내고 받을 수 있는 포트입니다. 확장 프로그램이 없으면 포트의 onDisconnect 이벤트가 실행됩니다.

connectNative()

chrome.runtime.connectNative(
  application: string,
)

호스트 머신의 네이티브 애플리케이션에 연결합니다. 이 메서드에는 "nativeMessaging" 권한이 필요합니다. 자세한 내용은 기본 메시지를 참고하세요.

매개변수

• 애플리케이션

  문자열

  연결할 등록된 애플리케이션의 이름입니다.

반환 값

• 포트

  애플리케이션과 함께 메시지를 보내고 받을 수 있는 포트입니다.

getBackgroundPage()

<ph type="x-smartling-placeholder"></ph> 프로미스 에서 확인하세요. 포그라운드만

chrome.runtime.getBackgroundPage(
  callback?: function,
)

JavaScript 'window'를 가져옵니다. 백그라운드 페이지용 객체를 정의합니다. 백그라운드 페이지가 이벤트 페이지인 경우 시스템은 콜백을 호출하기 전에 페이지가 로드되도록 합니다. 백그라운드 페이지가 없으면 오류가 설정됩니다.

매개변수

• 콜백

  함수 선택사항

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

  (backgroundPage?: Window) => void

  • backgroundPage

    기간은 선택사항입니다.

    JavaScript 'window' 객체를 지정합니다.

반환 값

• Promise&lt;Window | 정의되지 않음>

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getContexts()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 116 이상 MV3 이상

chrome.runtime.getContexts(
  filter: ContextFilter,
  callback?: function,
)

이 확장 프로그램과 연결된 활성 컨텍스트에 대한 정보를 가져옵니다.

매개변수

• filter

  ContextFilter

  일치하는 컨텍스트를 찾는 필터입니다. 컨텍스트는 필터에 지정된 모든 필드와 일치하면 일치합니다. 필터의 지정되지 않은 필드는 모든 컨텍스트와 일치합니다.

• 콜백

  함수 선택사항

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

  (contexts: ExtensionContext[]) => void

  • contexts

    ExtensionContext[]

    일치하는 컨텍스트입니다(있는 경우).

반환 값

• Promise&lt;ExtensionContext[]&gt;

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getManifest()

chrome.runtime.getManifest()

매니페스트에서 앱 또는 확장 프로그램에 관한 세부정보를 반환합니다. 반환된 객체는 전체 매니페스트 파일의 직렬화입니다.

반환 값

• 객체

  매니페스트 세부정보입니다.

getPackageDirectoryEntry()

<ph type="x-smartling-placeholder"></ph> 프로미스 에서 확인하세요. 포그라운드만

chrome.runtime.getPackageDirectoryEntry(
  callback?: function,
)

패키지 디렉터리의 DirectoryEntry를 반환합니다.

매개변수

• 콜백

  함수 선택사항

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

  (directoryEntry: DirectoryEntry) => void

  • directoryEntry

    DirectoryEntry

반환 값

• Promise&lt;DirectoryEntry&gt;

  Chrome 122 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getPlatformInfo()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.getPlatformInfo(
  callback?: function,
)

현재 플랫폼에 관한 정보를 반환합니다.

매개변수

• 콜백

  함수 선택사항

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

  (platformInfo: PlatformInfo) => void

  • platformInfo

    PlatformInfo

반환 값

• Promise&lt;PlatformInfo&gt;

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

getURL()

chrome.runtime.getURL(
  path: string,
)

앱/확장 프로그램 설치 디렉터리 내의 상대 경로를 정규화된 URL로 변환합니다.

매개변수

• 경로

  문자열

  설치 디렉터리를 기준으로 표현된 앱/확장 프로그램 내의 리소스 경로입니다.

반환 값

• 문자열

  리소스의 정규화된 URL.

openOptionsPage()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.openOptionsPage(
  callback?: function,
)

가능한 경우 확장 프로그램의 옵션 페이지를 엽니다.

정확한 동작은 매니페스트의 [options_ui](https://developer.chrome.com/docs/extensions/develop/ui/options-page#embedded_options) 또는 [options_page](https://developer.chrome.com/docs/extensions/develop/ui/options-page#full_page) 키 또는 Chrome에서 해당 시점에 어떤 작업을 지원하는지에 따라 다를 수 있습니다. 예를 들어 페이지가 새 탭, chrome://extensions 또는 앱 내에서 열리거나 열려 있는 옵션 페이지에 초점을 맞출 수 있습니다. 호출자 페이지가 새로고침되지는 않습니다.

확장 프로그램이 옵션 페이지를 선언하지 않거나 Chrome에서 다른 이유로 옵션 페이지를 만들지 못한 경우 콜백이 lastError를 설정합니다.

매개변수

• 콜백

  함수 선택사항

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

  () => void

반환 값

• 프로미스<void>

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

reload()

chrome.runtime.reload()

앱 또는 확장 프로그램을 새로고침합니다. 이 방법은 키오스크 모드에서 지원되지 않습니다. 키오스크 모드의 경우 chrome.runtime.restart() 메서드를 사용합니다.

requestUpdateCheck()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.requestUpdateCheck(
  callback?: function,
)

이 앱/확장 프로그램에 대한 즉시 업데이트 확인을 요청합니다.

중요: Chrome에서 이미 몇 시간마다 자동 확인을 실행하고 있으므로 requestUpdateCheck를 호출하지 않고도 runtime.onUpdateAvailable 이벤트를 수신 대기할 수 있으므로 대부분의 확장 프로그램/앱에서 이 메서드를 사용하면 안 됩니다.

이 메서드는 확장 프로그램이 백엔드 서비스와 통신하고 백엔드 서비스가 클라이언트 확장 프로그램 버전이 매우 오래되었다고 판단하여 사용자에게 업데이트하라는 메시지를 표시하려는 경우와 같이 매우 제한된 상황에서만 호출하는 데 적합합니다. 반복되는 타이머에 따라 무조건적으로 호출하는 등 requestUpdateCheck의 다른 용도는 대부분 클라이언트, 네트워크 및 서버 리소스를 낭비할 뿐입니다.

참고: 콜백으로 호출하면 객체를 반환하는 대신 이 함수가 콜백에 전달된 별도의 인수로 두 속성을 반환합니다.

매개변수

• 콜백

  함수 선택사항

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

  (result: object) => void

  • 결과

    객체

    Chrome 109 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

    업데이트 확인 상태 및 사용 가능한 업데이트가 있는 경우 결과의 세부정보를 보유하는 RequestUpdateCheckResult 객체입니다.

    • 상태

      RequestUpdateCheckStatus

      업데이트 확인 결과입니다.

    • version

      문자열(선택사항)

      사용 가능한 업데이트가 있는 경우 사용 가능한 업데이트 버전이 포함됩니다.

반환 값

• Promise&lt;object&gt;

  Chrome 109 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

restart()

chrome.runtime.restart()

앱이 키오스크 모드로 실행되면 ChromeOS 기기를 다시 시작합니다. 그렇지 않으면 작동하지 않습니다.

restartAfterDelay()

<ph type="x-smartling-placeholder"></ph> 프로미스 Chrome 53 이상

chrome.runtime.restartAfterDelay(
  seconds: number,
  callback?: function,
)

주어진 몇 초 후에 앱이 키오스크 모드로 실행되면 ChromeOS 기기를 다시 시작합니다. 이 시간이 끝나기 전에 다시 호출하면 재부팅이 지연됩니다. -1 값으로 호출하면 재부팅이 취소됩니다. 키오스크 이외의 모드에서는 작동하지 않습니다. 이 API를 호출하기 위해 첫 번째 확장 프로그램에서만 반복적으로 호출할 수 있습니다.

매개변수

• 초

  숫자

  기기를 재부팅하기 전에 대기하는 시간(초) 또는 -1로 예약된 재부팅을 취소합니다.

• 콜백

  함수 선택사항

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

  () => void

반환 값

• 프로미스<void>

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

sendMessage()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.sendMessage(
  extensionId?: string,
  message: any,
  options?: object,
  callback?: function,
)

확장 프로그램 또는 다른 확장 프로그램/앱 내의 이벤트 리스너로 단일 메시지를 보냅니다. runtime.connect와 유사하지만 선택적 응답과 함께 단일 메시지만 전송합니다. 확장 프로그램으로 전송하는 경우 확장 프로그램의 모든 프레임(발신자 프레임 제외) 또는 runtime.onMessageExternal(다른 확장 프로그램인 경우)에서 runtime.onMessage 이벤트가 실행됩니다. 확장 프로그램은 이 방법을 사용하여 콘텐츠 스크립트로 메시지를 보낼 수 없습니다. 콘텐츠 스크립트로 메시지를 보내려면 tabs.sendMessage을 사용합니다.

매개변수

• extensionId

  문자열(선택사항)

  메시지를 전송할 확장 프로그램의 ID입니다. 생략하면 메시지가 자체 확장 프로그램/앱으로 전송됩니다. 웹 메시징을 위해 웹페이지에서 메시지를 보내는 경우 필수 항목입니다.

• 메시지

  모두

  전송할 메시지입니다. 이 메시지는 JSON-ifiable 객체여야 합니다.

• 옵션

  객체(선택사항)

  • includeTlsChannelId

    불리언 선택사항

    연결 이벤트를 수신 대기하는 프로세스의 경우 TLS 채널 ID를 onMessageExternal에 전달할지 여부입니다.

• 콜백

  함수 선택사항

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

  (response: any) => void

  • 응답

    모두

    메시지의 핸들러에서 보낸 JSON 응답 객체입니다. 확장 프로그램에 연결하는 동안 오류가 발생하면 인수 없이 콜백이 호출되고 runtime.lastError이 오류 메시지로 설정됩니다.

반환 값

• 약속<any>

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

sendNativeMessage()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.sendNativeMessage(
  application: string,
  message: object,
  callback?: function,
)

네이티브 애플리케이션에 단일 메시지를 전송합니다. 이 메서드에는 "nativeMessaging" 권한이 필요합니다.

매개변수

• 애플리케이션

  문자열

  기본 메시지 호스트의 이름입니다.

• 메시지

  객체

  기본 메시지 호스트에 전달될 메시지입니다.

• 콜백

  함수 선택사항

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

  (response: any) => void

  • 응답

    모두

    기본 메시지 호스트에서 보낸 응답 메시지입니다. 네이티브 메시지 호스트에 연결하는 동안 오류가 발생하면 인수 없이 콜백이 호출되며 runtime.lastError이 오류 메시지로 설정됩니다.

반환 값

• 약속<any>

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

setUninstallURL()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.setUninstallURL(
  url: string,
  callback?: function,
)

제거 시 방문할 URL을 설정합니다. 이는 서버 측 데이터 정리, 분석, 설문조사 구현에 사용될 수 있습니다. 최대 1,023자(영문 기준)까지 허용됩니다.

매개변수

• URL

  문자열

  확장 프로그램이 제거된 후 열 URL입니다. 이 URL에는 http: 또는 https: 스키마가 있어야 합니다. 제거 시 새 탭이 열리지 않도록 빈 문자열을 설정합니다.

• 콜백

  함수 선택사항

  Chrome 45 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

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

  () => void

반환 값

• 프로미스<void>

  Chrome 99 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

  프로미스는 Manifest V3 이상에서 지원되지만 이전 버전과의 호환성입니다. 같은 함수 호출에서 두 가지를 모두 사용할 수는 없습니다. 이 프로미스는 콜백에 전달된 것과 동일한 유형으로 확인됩니다.

이벤트

onBrowserUpdateAvailable

<ph type="x-smartling-placeholder"></ph> 지원 중단됨

chrome.runtime.onBrowserUpdateAvailable.addListener(
  callback: function,
)

runtime.onRestartRequired을(를) 사용하세요.

Chrome 업데이트를 사용할 수 있지만 브라우저를 다시 시작해야 하기 때문에 즉시 설치되지는 않을 때 실행됩니다.

매개변수

• 콜백

  함수

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

  () => void

onConnect

chrome.runtime.onConnect.addListener(
  callback: function,
)

확장 프로그램 프로세스 또는 콘텐츠 스크립트에서 runtime.connect에 의해 연결되면 실행됩니다.

매개변수

• 콜백

  함수

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

  (port: Port) => void

  • 포트

    포트

onConnectExternal

chrome.runtime.onConnectExternal.addListener(
  callback: function,
)

다른 확장 프로그램 (runtime.connect에 의해) 또는 외부에서 연결 가능한 웹사이트에서 연결이 이루어질 때 실행됩니다.

매개변수

• 콜백

  함수

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

  (port: Port) => void

  • 포트

    포트

onConnectNative

Chrome 76 이상 를 통해 개인정보처리방침을 정의할 수 있습니다.

chrome.runtime.onConnectNative.addListener(
  callback: function,
)

네이티브 애플리케이션에서 연결할 때 실행됩니다. 이 이벤트에는 "nativeMessaging" 권한이 필요합니다. Chrome OS에서만 지원됩니다.

매개변수

• 콜백

  함수

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

  (port: Port) => void

  • 포트

    포트

onInstalled

chrome.runtime.onInstalled.addListener(
  callback: function,
)

확장 프로그램이 처음 설치될 때, 확장 프로그램이 새 버전으로 업데이트될 때, Chrome이 새 버전으로 업데이트될 때 실행됩니다.

매개변수

• 콜백

  함수

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

  (details: object) => void

  • 세부정보

    객체

    • id

      문자열(선택사항)

      가져온 공유 모듈 확장 프로그램의 ID를 나타냅니다. '이유'인 경우에만 표시됩니다. 'shared_module_update'입니다.

    • previousVersion

      문자열(선택사항)

      방금 업데이트된 확장 프로그램의 이전 버전을 나타냅니다. '이유'인 경우에만 표시됩니다. '업데이트'입니다.

    • reason

      OnInstalledReason

      이 이벤트가 전달되는 이유입니다.

onMessage

chrome.runtime.onMessage.addListener(
  callback: function,
)

메시지가 확장 프로그램 프로세스 (runtime.sendMessage에 의해) 또는 콘텐츠 스크립트 (tabs.sendMessage에 의해)에서 전송될 때 실행됩니다.

매개변수

• 콜백

  함수

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

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • 메시지

    모두

  • sender

    MessageSender

  • sendResponse

    함수

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

    () => void

  • returns

    boolean | 정의되지 않음

onMessageExternal

chrome.runtime.onMessageExternal.addListener(
  callback: function,
)

메시지가 다른 확장 프로그램에서 (runtime.sendMessage에 의해) 전송되면 실행됩니다. 콘텐츠 스크립트에 사용할 수 없습니다.

매개변수

• 콜백

  함수

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

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • 메시지

    모두

  • sender

    MessageSender

  • sendResponse

    함수

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

    () => void

  • returns

    boolean | 정의되지 않음

onRestartRequired

chrome.runtime.onRestartRequired.addListener(
  callback: function,
)

앱 또는 앱이 실행되는 기기를 다시 시작해야 할 때 실행됩니다. 앱은 다시 시작이 이루어질 수 있도록 가장 빠른 시간에 모든 창을 닫아야 합니다. 앱이 아무런 동작도 하지 않는 경우 24시간의 유예 기간이 지난 후 앱이 다시 시작됩니다. 현재 이 이벤트는 Chrome OS 키오스크 앱에서만 실행됩니다.

매개변수

• 콜백

  함수

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

  (reason: OnRestartRequiredReason) => void

  • reason

    OnRestartRequiredReason

onStartup

chrome.runtime.onStartup.addListener(
  callback: function,
)

이 확장 프로그램이 설치된 프로필이 처음 시작될 때 실행됩니다. 이 이벤트는 확장 프로그램이 '분할'에서 작동하더라도 시크릿 프로필이 시작되면 실행되지 않습니다. 시크릿 모드를 사용합니다.

매개변수

• 콜백

  함수

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

  () => void

onSuspend

chrome.runtime.onSuspend.addListener(
  callback: function,
)

로드 취소되기 직전에 이벤트 페이지로 전송됩니다. 이렇게 하면 확장 프로그램에서 정리 작업을 할 수 있습니다. 페이지가 로드 취소되고 있으므로 이 이벤트를 처리하는 동안 시작된 비동기 작업은 완료되지 않을 수도 있습니다. 로드 취소되기 전에 이벤트 페이지에 대한 추가 활동이 발생하면 onSuspendCanceled 이벤트가 전송되고 페이지가 언로드되지 않습니다.

매개변수

• 콜백

  함수

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

  () => void

onSuspendCanceled

chrome.runtime.onSuspendCanceled.addListener(
  callback: function,
)

앱이 결국 언로드되지 않음을 나타내기 위해 onSuspend 이후에 전송됩니다.

매개변수

• 콜백

  함수

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

  () => void

onUpdateAvailable

chrome.runtime.onUpdateAvailable.addListener(
  callback: function,
)

업데이트를 사용할 수 있지만 앱이 현재 실행 중이므로 즉시 설치되지 않을 때 실행됩니다. 아무 조치도 취하지 않으면 다음에 백그라운드 페이지가 언로드될 때 업데이트가 설치됩니다. 더 빨리 설치하려면 chrome.runtime.reload()를 명시적으로 호출하면 됩니다. 확장 프로그램에서 영구 백그라운드 페이지를 사용하는 경우 백그라운드 페이지는 당연히 언로드되지 않으므로, 이 이벤트에 대한 응답으로 chrome.runtime.reload()를 수동으로 호출하지 않으면 다음에 Chrome이 다시 시작될 때까지 업데이트가 설치되지 않습니다. 이 이벤트를 수신 대기하는 핸들러가 없고 확장 프로그램에 영구적인 백그라운드 페이지가 있는 경우, 이 이벤트에 대한 응답으로 chrome.runtime.reload()가 호출되는 것처럼 작동합니다.

매개변수

• 콜백

  함수

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

  (details: object) => void

  • 세부정보

    객체

    • version

      문자열

      사용 가능한 업데이트의 버전 번호입니다.

onUserScriptConnect

Chrome 115 이상 MV3 이상

chrome.runtime.onUserScriptConnect.addListener(
  callback: function,
)

이 확장 프로그램의 사용자 스크립트에서 연결되면 실행됩니다.

매개변수

• 콜백

  함수

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

  (port: Port) => void

  • 포트

    포트

onUserScriptMessage

Chrome 115 이상 MV3 이상

chrome.runtime.onUserScriptMessage.addListener(
  callback: function,
)

동일한 확장 프로그램에 연결된 사용자 스크립트에서 메시지가 전송되면 실행됩니다.

매개변수

• 콜백

  함수

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

  (message: any, sender: MessageSender, sendResponse: function) => boolean | undefined

  • 메시지

    모두

  • sender

    MessageSender

  • sendResponse

    함수

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

    () => void

  • returns

    boolean | 정의되지 않음