설명
chrome.permissions
API를 사용하여 설치 시점이 아닌 런타임에 선언된 선택적 권한을 요청하세요. 그러면 사용자가 권한이 필요한 이유를 이해하고 필요한 권한만 부여할 수 있습니다.
개요
권한 경고는 API에서 부여된 기능을 설명하기 위해 존재하지만 이러한 경고 중 일부는 명확하지 않을 수 있습니다. Permissions API를 사용하면 개발자가 권한 경고를 설명하고 새로운 기능을 점진적으로 도입하여 사용자에게 확장 프로그램을 위험 없이 소개할 수 있습니다. 이렇게 하면 사용자가 부여할 액세스 수준과 사용 설정할 기능을 지정할 수 있습니다.
예를 들어 선택적 권한 확장 프로그램의 핵심 기능이 새 탭 페이지를 재정의합니다. 사용자의 오늘의 목표를 표시하는 기능이 있습니다. 이 기능에는 경고가 포함되지 않은 저장소 권한만 필요합니다. 확장 프로그램에는 사용자가 다음 버튼을 클릭하여 사용 설정할 수 있는 추가 기능이 있습니다.
사용자의 인기 사이트를 표시하려면 다음과 같은 경고가 포함된 topSites 권한이 필요합니다.
선택적 권한 구현
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 기능을 확장할 수 있도록 허용합니다. |
"experimental" |
Canary 및 개발자 채널만 해당 확장 프로그램에 chrome.experimental API에 대한 액세스 권한을 부여합니다. |
"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[] 선택사항
이름이 지정된 권한 목록입니다 (호스트 또는 출처는 포함되지 않음).
메서드
contains()
chrome.permissions.contains(
permissions: Permissions,
callback?: function,
)
확장 프로그램에 지정된 권한이 있는지 확인합니다.
매개변수
-
권한
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.(result: boolean) => void
-
결과
부울
확장 프로그램에 지정된 권한이 있는 경우 true입니다. 출처가 선택적 권한과 콘텐츠 스크립트 일치 패턴으로 모두 지정된 경우 두 권한이 모두 부여되지 않으면
false
이 반환됩니다.
-
반환 값
-
Promise<boolean>
Chrome 96 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
getAll()
chrome.permissions.getAll(
callback?: function,
)
확장 프로그램의 현재 권한 집합을 가져옵니다.
매개변수
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.(permissions: Permissions) => void
반환 값
-
Promise<Permissions>
Chrome 96 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
remove()
chrome.permissions.remove(
permissions: Permissions,
callback?: function,
)
지정된 권한에 대한 액세스 권한을 삭제합니다. 권한을 삭제하는 데 문제가 있는 경우 runtime.lastError
이 설정됩니다.
매개변수
-
권한
-
콜백
함수 선택사항
callback
매개변수는 다음과 같습니다.(removed: boolean) => void
-
삭제됨
부울
권한이 삭제된 경우 true입니다.
-
반환 값
-
Promise<boolean>
Chrome 96 이상Promise는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
request()
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는 Manifest V3 이상에서만 지원되며 다른 플랫폼에서는 콜백을 사용해야 합니다.
이벤트
onAdded
chrome.permissions.onAdded.addListener(
callback: function,
)
확장 프로그램이 새 권한을 획득할 때 실행됩니다.
매개변수
-
콜백
함수
callback
매개변수는 다음과 같습니다.(permissions: Permissions) => void
-
권한
-
onRemoved
chrome.permissions.onRemoved.addListener(
callback: function,
)
확장 프로그램에서 권한 액세스 권한이 삭제될 때 실행됩니다.
매개변수
-
콜백
함수
callback
매개변수는 다음과 같습니다.(permissions: Permissions) => void
-
권한
-