설명
chrome.permissions API를 사용하여 설치 시점이 아닌 런타임에 선언된 선택적 권한을 요청하면 사용자가 권한이 필요한 이유를 이해하고 필요한 권한만 부여할 수 있습니다.
개념 및 사용법
권한 경고는 API에서 부여한 기능을 설명하기 위해 존재하지만, 이러한 경고 중 일부는 명확하지 않을 수 있습니다. Permissions API를 사용하면 개발자가 권한 경고를 설명하고 새로운 기능을 점진적으로 도입할 수 있으므로 사용자에게 위험 부담 없이 확장 프로그램을 소개할 수 있습니다. 이렇게 하면 사용자가 부여할 액세스 수준과 사용 설정할 기능을 지정할 수 있습니다.
예를 들어 선택적 권한 확장 프로그램의 핵심 기능은 새 탭 페이지를 재정의하는 것입니다. 한 가지 기능은 사용자의 오늘의 목표를 표시하는 것입니다. 이 기능에는 저장소 권한만 필요하며, 이 권한에는 경고가 포함되지 않습니다. 확장 프로그램에는 사용자가 다음 버튼을 클릭하여 사용 설정할 수 있는 추가 기능이 있습니다.
사용자의 상위 사이트를 표시하려면 topSites 권한이 필요하며, 이 권한에는 다음과 같은 경고가 있습니다.
topSites API의 확장 프로그램 경고선택적 권한 구현
1단계: 필수 권한과 선택적 권한 결정하기
확장 프로그램은 필수 권한과 선택적 권한을 모두 선언할 수 있습니다. 일반적으로 다음과 같이 수행합니다.
- 확장 프로그램의 기본 기능에 필요한 경우 필수 권한을 사용합니다.
- 확장 프로그램의 선택적 기능에 필요한 경우 선택적 권한을 사용합니다.
필수 권한의 이점:
- 메시지 감소: 확장 프로그램은 사용자에게 모든 권한을 수락하라는 메시지를 한 번 표시할 수 있습니다.
- 더 간단한 개발: 필수 권한이 있는지 확인합니다.
선택적 권한의 이점:
- 보안 개선: 사용자가 필요한 권한만 사용 설정하므로 확장 프로그램이 더 적은 권한으로 실행됩니다.
- 사용자에게 더 나은 정보 제공: 사용자가 관련 기능을 사용 설정할 때 확장 프로그램에서 특정 권한이 필요한 이유를 설명할 수 있습니다.
- 더 쉬운 업그레이드: 확장 프로그램을 업그레이드할 때 업그레이드에서 필수 권한이 아닌 선택적 권한을 추가하는 경우 Chrome에서 사용자를 위해 확장 프로그램을 사용 중지하지 않습니다.
2단계: 매니페스트에서 선택적 권한 선언
permissions 필드와 동일한 형식을 사용하여 optional_permissions 키로 확장 프로그램 매니페스트에서 선택적 권한을 선언합니다.
{
"name": "My extension",
...
"optional_permissions": ["tabs"],
"optional_host_permissions": ["https://www.google.com/"],
...
}
런타임에만 검색하는 호스트를 요청하려면 확장 프로그램의 optional_host_permissions 필드에 "https://*/*"를 포함합니다. 이렇게 하면 일치하는 스키마가 있는 한 "Permissions.origins"에서 출처를 지정할 수 있습니다.
선택사항으로 지정할 수 없는 권한
대부분의 Chrome 확장 프로그램 권한은 선택사항으로 지정할 수 있지만 다음과 같은 예외가 있습니다.
| 권한 | 설명 |
|---|---|
"debugger" |
browser.debugger API는 Chrome의 원격 디버깅 프로토콜의 대체 전송 역할을 합니다. |
"declarativeNetRequest" |
확장 프로그램에 browser.declarativeNetRequest API에 대한 액세스 권한을 부여합니다. |
"devtools" |
확장 프로그램이 Chrome DevTools 기능을 확장할 수 있도록 허용합니다. |
"geolocation" |
확장 프로그램에서 HTML5 geolocation API를 사용할 수 있도록 허용합니다. |
"mdns" |
확장 프로그램에 browser.mdns API에 대한 액세스 권한을 부여합니다. |
"proxy" |
확장 프로그램에 browser.proxy API에 대한 액세스 권한을 부여하여 Chrome의 프록시 설정을 관리합니다. |
"tts" |
browser.tts API는 합성된 TTS (텍스트 음성 변환)를 재생합니다. |
"ttsEngine" |
browser.ttsEngine API는 확장 프로그램을 사용하여 텍스트 음성 변환 (TTS) 엔진을 구현합니다. |
"wallpaper" |
ChromeOS만 해당. browser.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.
browser.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()를 사용하세요.
browser.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()를 호출하면 일반적으로 사용자에게 메시지를 표시하지 않고 권한이 다시 추가됩니다.
browser.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[] 선택사항
이름이 지정된 권한 목록입니다 (호스트 또는 출처는 포함되지 않음).
메서드
addHostAccessRequest()
browser.permissions.addHostAccessRequest(
request: object,
): Promise<void>
호스트 액세스 요청을 추가합니다. 요청의 호스트에 대한 액세스 권한을 확장 프로그램에 부여할 수 있는 경우에만 요청이 사용자에게 표시됩니다. 교차 출처 탐색 시 요청이 재설정됩니다. 수락 시 사이트의 최상위 출처에 대한 영구 액세스 권한을 부여합니다.
매개변수
-
요청
객체
-
documentId
문자열 선택사항
호스트 액세스 요청을 표시할 수 있는 문서의 ID입니다. 탭 내의 최상위 문서여야 합니다. 제공된 경우 요청은 지정된 문서의 탭에 표시되며 문서가 새 출처로 이동하면 삭제됩니다. 새 요청을 추가하면
tabId에 대한 기존 요청이 재정의됩니다.tabId또는 이 필드를 지정해야 합니다. -
패턴
문자열 선택사항
호스트 액세스 요청이 표시될 수 있는 URL 패턴입니다. 제공된 경우 호스트 액세스 요청은 이 패턴과 일치하는 URL에만 표시됩니다.
-
tabId
number 선택사항
호스트 액세스 요청을 표시할 수 있는 탭의 ID입니다. 제공된 경우 요청이 지정된 탭에 표시되고 탭이 새 출처로 이동하면 삭제됩니다. 새 요청을 추가하면
documentId에 대한 기존 요청이 재정의됩니다.documentId또는 이 필드를 지정해야 합니다.
-
반환 값
-
약속<void>
contains()
browser.permissions.contains(
permissions: Permissions,
): Promise<boolean>
확장 프로그램에 지정된 권한이 있는지 확인합니다.
매개변수
-
권한
반환 값
-
Promise<boolean>
Chrome 96 이상 브라우저.*(Chrome 148부터)
반환 값
-
Promise<Permissions>
Chrome 96 이상 브라우저.*(Chrome 148부터)
remove()
browser.permissions.remove(
permissions: Permissions,
): Promise<boolean>
지정된 권한에 대한 액세스 권한을 삭제합니다. 권한을 삭제하는 데 문제가 있으면 프로미스가 거부됩니다.
매개변수
-
권한
반환 값
-
Promise<boolean>
Chrome 96 이상 브라우저.*(Chrome 148부터)
removeHostAccessRequest()
browser.permissions.removeHostAccessRequest(
request: object,
): Promise<void>
호스트 액세스 요청이 있는 경우 삭제합니다.
매개변수
-
요청
객체
-
documentId
문자열 선택사항
호스트 액세스 요청이 삭제될 문서의 ID입니다. 탭 내의 최상위 문서여야 합니다.
tabId또는 이 필드를 지정해야 합니다. -
패턴
문자열 선택사항
호스트 액세스 요청이 삭제될 URL 패턴입니다. 제공되는 경우 기존 호스트 액세스 요청의 패턴과 정확히 일치해야 합니다.
-
tabId
number 선택사항
호스트 액세스 요청이 삭제될 탭의 ID입니다.
documentId또는 이 필드를 지정해야 합니다.
-
반환 값
-
약속<void>
request()
browser.permissions.request(
permissions: Permissions,
): Promise<boolean>
지정된 권한에 대한 액세스를 요청하고 필요한 경우 사용자에게 메시지를 표시합니다. 이러한 권한은 매니페스트의 optional_permissions 필드에 정의되어 있거나 사용자가 보류한 필수 권한이어야 합니다. 출처 패턴의 경로는 무시됩니다. 선택적 출처 권한의 하위 집합을 요청할 수 있습니다. 예를 들어 매니페스트의 optional_permissions 섹션에 *://*\/*를 지정하면 http://example.com/를 요청할 수 있습니다. 권한을 요청하는 데 문제가 있으면 프로미스가 거부됩니다.
매개변수
-
권한
반환 값
-
Promise<boolean>
Chrome 96 이상 브라우저.*(Chrome 148부터)
이벤트
onAdded
browser.permissions.onAdded.addListener(
callback: function,
)
확장 프로그램이 새 권한을 획득하면 실행됩니다.
매개변수
-
callback
함수
callback매개변수는 다음과 같습니다.(permissions: Permissions) => void
-
권한
-
onRemoved
browser.permissions.onRemoved.addListener(
callback: function,
)
확장 프로그램에서 권한에 대한 액세스 권한이 삭제되면 실행됩니다.
매개변수
-
callback
함수
callback매개변수는 다음과 같습니다.(permissions: Permissions) => void
-
권한
-