chrome.permissions

설명

chrome.permissions API를 사용하여 설치 시점이 아닌 런타임에 선언된 선택적 권한을 요청하세요. 그러면 사용자가 권한이 필요한 이유를 이해하고 필요한 권한만 부여할 수 있습니다.

개념 및 사용

권한 경고는 API에서 부여된 기능을 설명하기 위해 존재하지만 이러한 경고 중 일부는 명확하지 않을 수 있습니다. Permissions API를 사용하면 개발자가 권한 경고를 설명하고 새로운 기능을 점진적으로 도입하여 사용자에게 확장 프로그램을 위험 없이 소개할 수 있습니다. 이렇게 하면 사용자가 부여할 액세스 수준과 사용 설정할 기능을 지정할 수 있습니다.

예를 들어 선택적 권한 확장 프로그램의 핵심 기능이 새 탭 페이지를 재정의합니다. 한 가지 기능은 사용자의 오늘의 목표를 표시하는 것입니다. 이 기능에는 경고가 포함되지 않은 저장소 권한만 필요합니다. 확장 프로그램에는 사용자가 다음 버튼을 클릭하여 사용 설정할 수 있는 추가 기능이 있습니다.

추가 기능을 사용 설정하는 확장 프로그램 버튼
추가 기능을 사용 설정하는 확장 프로그램 버튼입니다.

사용자의 인기 사이트를 표시하려면 다음과 같은 경고가 포함된 topSites 권한이 필요합니다.

topSites API의 확장 프로그램 경고
topSites API 확장 프로그램 경고

선택적 권한 구현

1단계: 필수 권한과 선택적 권한 결정하기

확장 프로그램은 필수 권한과 선택적 권한을 모두 선언할 수 있습니다. 일반적으로 다음과 같이 해야 합니다.

  • 확장 프로그램의 기본 기능에 필요한 경우 필수 권한을 사용합니다.
  • 확장 프로그램의 선택적 기능에 선택적 권한이 필요한 경우에만 선택적 권한을 사용하세요.

필수 권한의 이점:

  • 메시지 감소: 확장 프로그램은 사용자에게 한 번만 메시지를 표시하여 모든 권한을 수락하도록 요청할 수 있습니다.
  • 더 간단한 개발: 필수 권한이 있는지 확인할 필요가 없습니다.

선택사항 권한의 이점:

  • 보안 강화: 사용자가 필요한 권한만 사용 설정하므로 확장 프로그램이 더 적은 권한으로 실행됩니다.
  • 사용자에게 더 나은 정보 제공: 확장 프로그램은 사용자가 관련 기능을 사용 설정할 때 특정 권한이 필요한 이유를 설명할 수 있습니다.
  • 더 쉬운 업그레이드: 확장 프로그램을 업그레이드할 때 업그레이드에서 필수 권한이 아닌 선택적 권한을 추가하는 경우 Chrome에서 사용자를 위해 확장 프로그램을 사용 중지하지 않습니다.

2단계: 매니페스트에서 선택적 권한 선언

권한 필드와 동일한 형식을 사용하여 optional_permissions 키로 확장 프로그램 매니페스트에서 선택적 권한을 선언합니다.

{
  "name": "My extension",
  ...
  "optional_permissions": ["tabs"],
  "optional_host_permissions": ["https://www.google.com/"],
  ...
}

런타임에만 검색되는 호스트를 요청하려면 확장 프로그램의 optional_host_permissions 필드에 "https://*/*"를 포함합니다. 이렇게 하면 일치하는 스키마가 있는 한 "Permissions.origins"에서 출처를 지정할 수 있습니다.

선택사항으로 지정할 수 없는 권한

대부분의 Chrome 확장 프로그램 권한은 다음과 같은 예외를 제외하고 선택사항으로 지정할 수 있습니다.

권한 설명
"debugger" chrome.debugger API는 Chrome의 원격 디버깅 프로토콜에 대한 대체 전송 수단 역할을 합니다.
"declarativeNetRequest" 확장 프로그램에 chrome.declarativeNetRequest API에 대한 액세스 권한을 부여합니다.
"devtools" 확장 프로그램이 Chrome DevTools 기능을 확장할 수 있도록 허용합니다.
"geolocation" 확장 프로그램이 HTML5 위치정보 API를 사용할 수 있도록 허용합니다.
"mdns" 확장 프로그램에 chrome.mdns API에 대한 액세스 권한을 부여합니다.
"proxy" Chrome의 프록시 설정을 관리하도록 확장 프로그램에 chrome.proxy API에 대한 액세스 권한을 부여합니다.
"tts" chrome.tts API는 합성 TTS (텍스트 음성 변환)를 재생합니다.
"ttsEngine" chrome.ttsEngine API는 확장 프로그램을 사용하여 텍스트 음성 변환 (TTS) 엔진을 구현합니다.
"wallpaper" ChromeOS만 해당. chrome.wallpaper API를 사용하여 ChromeOS 배경화면을 변경합니다.

사용 가능한 권한 및 경고에 관한 자세한 내용은 권한 선언을 참고하세요.

3단계: 선택적 권한 요청

permissions.request()를 사용하여 사용자 동작 내에서 권한을 요청합니다.

document.querySelector('#my-button').addEventListener('click', (event) => {
  // Permissions must be requested from inside a user gesture, like a button's
  // click handler.
  chrome.permissions.request({
    permissions: ['tabs'],
    origins: ['https://www.google.com/']
  }, (granted) => {
    // The callback argument will be true if the user granted the permissions.
    if (granted) {
      doSomething();
    } else {
      doSomethingElse();
    }
  });
});

권한을 추가하면 사용자가 이미 확인하고 수락한 것과 다른 경고 메시지가 표시되는 경우 Chrome에서 사용자에게 메시지를 표시합니다. 예를 들어 이전 코드로 인해 다음과 같은 프롬프트가 표시될 수 있습니다.

권한 확인 메시지의 예
권한 확인 메시지의 예

4단계: 확장 프로그램의 현재 권한 확인

확장 프로그램에 특정 권한 또는 권한 집합이 있는지 확인하려면 permission.contains()를 사용하세요.

chrome.permissions.contains({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (result) => {
  if (result) {
    // The extension has the permissions.
  } else {
    // The extension doesn't have the permissions.
  }
});

5단계: 권한 삭제

더 이상 필요하지 않은 권한은 삭제해야 합니다. 권한이 삭제된 후에는 일반적으로 permissions.request()를 호출하면 사용자에게 메시지를 표시하지 않고 권한이 다시 추가됩니다.

chrome.permissions.remove({
  permissions: ['tabs'],
  origins: ['https://www.google.com/']
}, (removed) => {
  if (removed) {
    // The permissions have been removed.
  } else {
    // The permissions have not been removed (e.g., you tried to remove
    // required permissions).
  }
});

유형

Permissions

속성

  • origins

    string[] 선택사항

    매니페스트의 optional_permissions 또는 permissions 키에 지정된 권한과 콘텐츠 스크립트와 연결된 권한을 포함한 호스트 권한 목록입니다.

  • 권한

    string[] 선택사항

    이름이 지정된 권한 목록입니다 (호스트 또는 출처는 포함되지 않음).

메서드

addSiteAccessRequest()

약속 대기 중MV3 이상 
chrome.permissions.addSiteAccessRequest(
  request: object,
  callback?: function,
)

사이트 액세스 요청을 추가합니다. 요청에서 확장 프로그램에 사이트 액세스 권한을 부여할 수 있는 경우에만 요청이 사용자에게 전달됩니다. 교차 출처 탐색 시 요청이 재설정됩니다. 수락하면 사이트의 최상위 출처에 대한 지속적인 액세스 권한이 부여됩니다.

매개변수

  • 요청

    객체

    • documentId

      문자열 선택사항

      사이트 액세스 요청을 표시할 수 있는 문서의 ID입니다. 탭 내 최상위 문서여야 합니다. 제공된 경우 요청은 지정된 문서의 탭에 표시되며 문서가 새 출처로 이동하면 삭제됩니다. 새 요청을 추가하면 tabId에 대한 기존 요청이 재정의됩니다. 이 필드 또는 tabId를 지정해야 합니다.

    • 패턴

      문자열 선택사항

      사이트 액세스 요청을 표시할 수 있는 URL 패턴입니다. 이 패턴이 제공되면 사이트 액세스 요청이 이 패턴과 일치하는 URL에만 표시됩니다.

    • tabId

      번호 선택사항

      사이트 액세스 요청을 표시할 수 있는 탭의 ID입니다. 지정된 경우 요청이 지정된 탭에 표시되고 탭이 새 출처로 이동하면 삭제됩니다. 새 요청을 추가하면 documentId에 대한 기존 요청이 재정의됩니다. 이 필드 또는 documentId를 지정해야 합니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

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

contains()

Promise 
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

확장 프로그램에 지정된 권한이 있는지 확인합니다.

매개변수

  • 권한

    권한

  • 콜백

    함수 선택사항

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

    (result: boolean) => void

    • 결과

      부울

      확장 프로그램에 지정된 권한이 있는 경우 true입니다. 출처가 선택적 권한과 콘텐츠 스크립트 일치 패턴으로 모두 지정된 경우 두 권한이 모두 부여되지 않으면 false이 반환됩니다.

반환 값

  • Promise<boolean>

    Chrome 96 이상

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

getAll()

Promise 
chrome.permissions.getAll(
  callback?: function,
)

확장 프로그램의 현재 권한 집합을 가져옵니다.

매개변수

  • 콜백

    함수 선택사항

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

    (permissions: Permissions) => void

    • 권한

      권한

      확장 프로그램의 활성 권한입니다. origins 속성에는 매니페스트의 permissions 및 optional_permissions 키에 지정된 출처와 콘텐츠 스크립트와 연결된 출처에서 부여된 출처가 포함됩니다.

반환 값

  • Promise<Permissions>

    Chrome 96 이상

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

remove()

Promise 
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

지정된 권한에 대한 액세스 권한을 삭제합니다. 권한을 삭제하는 데 문제가 있는 경우 runtime.lastError이 설정됩니다.

매개변수

  • 권한

    권한

  • 콜백

    함수 선택사항

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

    (removed: boolean) => void

    • 삭제됨

      부울

      권한이 삭제된 경우 true입니다.

반환 값

  • Promise<boolean>

    Chrome 96 이상

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

removeSiteAccessRequest()

약속 대기 중MV3 이상 
chrome.permissions.removeSiteAccessRequest(
  request: object,
  callback?: function,
)

사이트 액세스 요청이 있는 경우 삭제합니다.

매개변수

  • 요청

    객체

    • documentId

      문자열 선택사항

      사이트 액세스 요청이 삭제될 문서의 ID입니다. 탭 내 최상위 문서여야 합니다. 이 필드 또는 tabId를 지정해야 합니다.

    • 패턴

      문자열 선택사항

      사이트 액세스 요청이 삭제되는 URL 패턴입니다. 이 필드는 제공된 경우 기존 사이트 액세스 요청의 패턴과 정확하게 일치해야 합니다.

    • tabId

      번호 선택사항

      사이트 액세스 요청이 삭제되는 탭의 ID입니다. 이 필드 또는 documentId를 지정해야 합니다.

  • 콜백

    함수 선택사항

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

    () => void

반환 값

  • Promise<void>

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

request()

Promise 
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

지정된 권한에 대한 액세스를 요청하고 필요한 경우 사용자에게 메시지를 표시합니다. 이러한 권한은 매니페스트의 optional_permissions 필드에 정의되어 있거나 사용자가 보류한 필수 권한이어야 합니다. 출처 패턴의 경로는 무시됩니다. 선택적 출처 권한의 하위 집합을 요청할 수 있습니다. 예를 들어 매니페스트의 optional_permissions 섹션에 *://*\/*를 지정하면 http://example.com/를 요청할 수 있습니다. 권한을 요청하는 데 문제가 있으면 runtime.lastError이 설정됩니다.

매개변수

  • 권한

    권한

  • 콜백

    함수 선택사항

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

    (granted: boolean) => void

    • 동의함

      부울

      사용자가 지정된 권한을 부여한 경우 True입니다.

반환 값

  • Promise<boolean>

    Chrome 96 이상

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

이벤트

onAdded

chrome.permissions.onAdded.addListener(
  callback: function,
)

확장 프로그램이 새 권한을 획득할 때 실행됩니다.

매개변수

  • 콜백

    함수

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

    (permissions: Permissions) => void

onRemoved

chrome.permissions.onRemoved.addListener(
  callback: function,
)

확장 프로그램에서 권한 액세스 권한이 삭제될 때 실행됩니다.

매개변수

  • 콜백

    함수

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

    (permissions: Permissions) => void