chrome.permissions

설명

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

개념 및 사용법

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

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

<ph type="x-smartling-placeholder">
</ph> 추가 기능을 사용 설정하는 확장 프로그램 버튼.
추가 기능을 사용 설정하는 확장 프로그램 버튼.

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

<ph type="x-smartling-placeholder">
</ph> topSites API 관련 확장 경고
topSites API에 대한 확장 프로그램 경고

선택적 권한 구현

1단계: 필요한 권한 및 선택사항 권한 결정하기

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

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

필수 권한의 장점:

  • 메시지 적게 표시: 확장 프로그램에서 사용자에게 모든 권한을 수락하라는 메시지를 한 번 표시할 수 있습니다.
  • 간단한 개발: 필수 권한이 존재합니다.

선택적 권한의 장점:

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

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

optional_permissions 키를 사용하여 확장 프로그램 매니페스트에서 선택적 권한을 선언합니다. 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 Geocoding API를 사용하도록 허용합니다.
"mdns" 확장 프로그램에 chrome.mdns API로 설정할 수 있습니다.
"proxy" 확장 프로그램에 chrome.proxy API에 대한 액세스 권한을 부여하여 Chrome의 프록시를 관리합니다. 설정을 변경할 수 있습니다.
"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에서 사용자에게 메시지를 표시합니다. 사용자가 이미 확인하고 수락했습니다. 예를 들어 이전 코드로 인해 다음과 같은 프롬프트가 표시될 수 있습니다. 다음과 같습니다.

<ph type="x-smartling-placeholder">
</ph> 권한 확인 메시지 예시
권한 확인 메시지 예시

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[] 선택사항

    이름이 지정된 권한 목록 (호스트나 출처 제외)

메서드

contains()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.permissions.contains(
  permissions: Permissions,
  callback?: function,
)

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

매개변수

  • 권한
  • 콜백

    함수 선택사항

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

    (result: boolean) => void

    • 결과

      부울

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

반환 값

  • Promise&lt;boolean&gt;

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

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

getAll()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.permissions.getAll(
  callback?: function,
)

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

매개변수

  • 콜백

    함수 선택사항

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

    (permissions: Permissions) => void

    • 권한

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

반환 값

  • Promise&lt;Permissions&gt;

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

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

remove()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.permissions.remove(
  permissions: Permissions,
  callback?: function,
)

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

매개변수

  • 권한
  • 콜백

    함수 선택사항

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

    (removed: boolean) => void

    • 삭제됨

      부울

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

반환 값

  • Promise&lt;boolean&gt;

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

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

request()

<ph type="x-smartling-placeholder"></ph> 프로미스 를 통해 개인정보처리방침을 정의할 수 있습니다.
chrome.permissions.request(
  permissions: Permissions,
  callback?: function,
)

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

매개변수

  • 권한
  • 콜백

    함수 선택사항

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

    (granted: boolean) => void

    • 동의함

      부울

      사용자가 지정된 권한을 부여했다면 true입니다.

반환 값

  • Promise&lt;boolean&gt;

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

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

이벤트

onAdded

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

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

매개변수

  • 콜백

    함수

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

    (permissions: Permissions) => void

onRemoved

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

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

매개변수

  • 콜백

    함수

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

    (permissions: Permissions) => void