Разрешения
permissions спрашивает у пользователя доступ к камере, микрофону, геопозиции, распознаванию речи
или уведомлениям, сообщает, что он ответил, и после отказа открывает страницу приложения в
настройках. Камерные вью, notifications.schedule, Push.register() и плагины спрашивают сами;
используй его, чтобы спросить раньше или обработать отказ. Выбору фото (openFilePicker) разрешение
не нужно.
- запросить камеру или микрофон до того, как они понадобятся функции (
permissions.request) - проверить без диалога, выдано ли уже разрешение (
permissions.query) - объяснить зачем, до того как покажется системный диалог
- пользователь отказал: отправить его в настройки приложения (
permissions.openSettings) - знать, когда iOS, Android и веб спрашивают снова после отказа
- объявить разрешения, которые запрашивает опубликованное приложение (Info.plist, манифест Android)
Платформы: все хосты; диалог есть на iOS, Android, в вебе и в веб-плеере — на десктопе и в
headless-тестах его нет, и любой вид отвечает "granted"; openSettings ничего не делает в вебе,
в веб-плеере и на десктопе.
Обзор
const hint = UIColumn()
const record = async () => {
const state = await permissions.request('microphone') // диалог ОС в первый раз, потом — ответ
if (state === 'granted') {
hint.setContent([UIText('Recording…')]) // здесь запусти рекордер
} else {
hint.setContent([
UIText('The microphone is off for this app'),
UIButton(UIText('Open Settings')).onClick(() => permissions.openSettings()),
])
}
}
UIScreen(UIButton(UIText('Record')).onClick(record), hint).open()Запросить разрешение: permissions.request
permissions.request(kind): Promise<PermissionState> // диалог, если ещё не спрашивали; потом — состояние
type PermissionKind = 'camera' | 'microphone' | 'location' | 'speech' | 'notifications'
type PermissionState = 'granted' | 'denied' | 'prompt'request спрашивает у пользователя доступ к камере, микрофону, геопозиции, распознаванию речи или
уведомлениям: показывает диалог ОС, если его ещё не спрашивали, и резолвится его ответом. При
повторном запросе он резолвится текущим состоянием — или ОС показывает свой диалог ещё раз: это решает ОС
(ниже). Спрашивай там, где пользователь этого
ждёт, — первый тап по кнопке записи, первое «поделиться геопозицией», — а не при старте приложения:
диалог, которого никто не понял, — это "denied", который останется.
const startCall = async () => {
const camera = await permissions.request('camera') // один диалог,
const mic = await permissions.request('microphone') // затем следующий
if (camera === 'granted' && mic === 'granted') {
console.log('call: starting') // здесь открой звонок
} else {
toast('A video call needs the camera and the microphone')
}
}
UIScreen(UIButton(UIText('Start a video call')).onClick(startCall)).open()cameraиmicrophone— камера и микрофон устройства.location— пока приложение используется; фоновой геопозиции нет.speech— собственное разрешение распознавания речи: на iOS у него свой диалог, на Android и в вебе — диалог микрофона. Плагинspeechзапрашивает иspeech, иmicrophone.notifications— единый переключатель для локальных уведомлений (Уведомления) и удалённых push (Push): iOS и Android 13+ показывают диалог, на Android до 13 его нет (состояние — переключатель уведомлений приложения); на десктопе и в вебе он отвечает"granted", хотя самой функции там нет.- Камерные вью и плагины спрашивают сами:
Router.push(view)иview.open()уCameraView,QRScannerиARSceneспрашивают до показа вью и отклоняются сThe camera permission was denied—UICameraNodeспрашивает, когда стартует его предпросмотр, и отправляет это сообщение вonError;AudioRecorder.start(),Geolocationи плагинspeechотклоняются сe.message === 'denied'.requestдо них лишь переносит диалог на более удачный момент. requestиqueryотклоняются (ошибкой, а не состоянием) для вида, о котором хост не спрашивает:speechв iOS-сборке без плагинаspeech.
на iOS и Android запросы ждут в очереди: две функции, спросившие одновременно, получают диалоги один за другим, а один вид, запрошенный дважды, пока его диалог на экране, получает один диалог и два ответа.
Проверить, выдано ли разрешение: permissions.query
permissions.query(kind): Promise<PermissionState> // состояние сейчас, никогда не диалогquery без диалога проверяет, выдан ли уже доступ к камере, микрофону, геопозиции, распознаванию
речи или уведомлениям: "granted", "denied" (отказано или заблокировано политикой устройства)
или "prompt" (ещё не спрашивали: request покажет диалог). По нему выбирай, что показать на экране, — саму функцию, кнопку, которая
спрашивает, или путь в настройки.
const nearby = UIColumn()
const showNearby = async () => {
const state = await permissions.query('location') // без диалога
if (state === 'granted') {
nearby.setContent([UIText('Places near you')]) // здесь прочитай позицию
} else if (state === 'prompt') { // ещё не спрашивали: предложи кнопку, которая спросит
nearby.setContent([UIButton(UIText('Use my location'))
.onClick(() => permissions.request('location').then(showNearby))])
} else { // отказали раньше
nearby.setContent([UIText('Location is off for this app')])
}
}
UIScreen(nearby).open()
showNearby()Android не хранит состояние «ещё не спрашивали»: query отвечает "prompt", пока это
приложение ни разу не спросило, и "denied" после отказа, даже когда ОС показала бы диалог снова.
В вебе браузер может не знать ответа до запроса (Safari до 16, Firefox для камеры): тогда он
отвечает "prompt".
Объяснить зачем — до системного диалога
iOS показывает диалог один раз, так что, пока состояние "prompt", сначала покажи своё объяснение,
а request вызывай, только когда пользователь пошёл дальше. В самом диалоге — текст назначения из
сборки приложения (его объявляют плагины).
const scan = () => console.log('scanner: open') // здесь открой сканер
const why = UIScreen(
UIText('The camera reads the receipt. Nothing leaves the phone.'),
UIButton(UIText('Continue')).onClick(async () => {
Router.pop()
if ((await permissions.request('camera')) === 'granted') scan() // теперь диалог ОС
}),
)
const onScanTap = async () => {
const state = await permissions.query('camera')
if (state === 'prompt') Router.push(why) // ещё не спрашивали: сначала объясни
else if (state === 'granted') scan()
else toast('Turn the camera on in Settings')
}
Router.init(UIScreen(UIButton(UIText('Scan a receipt')).onClick(onScanTap)))Разрешение отклонено: отправь пользователя в настройки (openSettings)
permissions.openSettings(): void // собственная страница приложения в системных настройкахКогда пользователь отказал в доступе к камере, микрофону или геопозиции, путь назад — системные
настройки: openSettings() открывает там собственную страницу приложения (iOS: страница
приложения в «Настройках»; Android: экран сведений о приложении с его разрешениями). iOS никогда не
показывает диалог дважды; Android перестаёт спрашивать, когда так решит ОС. Пользователь включает
разрешение и возвращается, а приложение перечитывает его на "resume"
(жизненный цикл приложения).
const body = UIColumn()
const ready = () => body.setContent([UIText('Camera ready')]) // здесь открой камеру
const askCamera = async () => {
if ((await permissions.request('camera')) === 'granted') return ready()
body.setContent([ // отказано: путь назад — настройки
UIText('The camera is off for this app'),
UIButton(UIText('Open Settings')).onClick(() => permissions.openSettings()),
])
}
// вернулись из настроек: перечитай состояние (query никогда не показывает диалог)
app.addEventListener('resume', async () => {
if ((await permissions.query('camera')) === 'granted') ready()
})
body.setContent([UIButton(UIText('Use the camera')).onClick(askCamera)])
UIScreen(body).open()openSettingsничего не делает в вебе, в веб-плеере и на десктопе: в вебе скажи пользователю разрешить доступ в настройках браузера для сайта.- Показывай кнопку, которая открывает настройки; не открывай их неожиданно.
- В приложении-вьюере le.codes он открывает собственную страницу вьюера: разрешения там — вьюера, одни и те же для каждого проекта, который он запускает.
на Android диалог разрешения ставит приложение на паузу: вокруг него срабатывают
"pause" и "resume". Перечитывай через query в обработчике "resume", никогда не через
request — тот может возвращать диалог после каждого ответа.
Что отвечает каждая платформа: iOS, Android, веб
| iOS | Android | веб, веб-плеер | |
|---|---|---|---|
query |
статус ОС | "granted", иначе "prompt", пока приложение ни разу не спросило, "denied" после |
Permissions API браузера; "prompt", где браузер не может сказать |
request, ещё не спрашивали |
системный диалог | системный диалог | запрос браузера: поток камеры или микрофона, сразу остановленный, определение позиции (лимит 15 с) |
request после отказа |
сразу "denied", без диалога |
решает ОС: снова диалог или "denied" |
решает браузер |
openSettings |
страница приложения в «Настройках» | экран сведений о приложении | ничего |
- На десктопе и в headless-тестах (
lecodes render/lecodes test) диалога нет:queryиrequestотвечают"granted"для любого вида, аopenSettingsничего не делает. Есть ли там сама функция — отвечает сама функция (CameraView.supported,Geolocation.supported, отклонение вызова). - На Android геопозиция, выданная как «приблизительная», считается
"granted". - В вебе у страницы, которая отдаётся не по https и не с localhost, нет камеры и микрофона:
requestотвечает"denied".speechтам — разрешение микрофона.
Объявить разрешения опубликованного приложения: Info.plist и манифест Android
Сборка твоего собственного приложения (оболочка lecodes app) объявляет разрешение только через
плагины в app.json: текст назначения для iOS (NSCameraUsageDescription и прочие, его показывает
диалог) и <uses-permission> для Android берутся из их манифестов. Перечисли плагин, который
использует разрешение, — и оно объявлено:
| вид | объявляют плагины |
|---|---|
camera |
camera (CameraView), qr-scanner, ar, webrtc |
microphone |
audio-recorder, speech, webrtc |
location |
geolocation |
speech |
speech |
{ "plugins": { "camera": "*" } }- Вид, который не объявляет ни один из перечисленных плагинов, ломается в опубликованном
приложении: iOS закрывает приложение при запросе камеры или микрофона (текст назначения
обязателен), не показывает диалог геопозиции и отклоняет
speech; Android отвечает"denied"без диалога. - Приложение-вьюер le.codes объявляет все виды, так что там проект работает в любом случае:
проверь список
pluginsперед публикацией.
Собственные разрешения плагина: @permission
Контракт плагина помечает метод, которому нужно разрешение (@permission microphone в его
contract.d.ts). Сгенерированный нативный код спрашивает тот же сервис хоста перед вызовом и
отклоняется с denied, если в разрешении отказано, — собственный код плагина никогда не показывает
диалог, — а lecodes plugin gen падает, если в манифестах плагина нет текста назначения для
платформы или <uses-permission>. См. нативные плагины.
Смотрите также
- CameraView, QRScanner, ARScene — пользователи камеры, которые спрашивают до показа
- Geolocation —
location - AudioRecorder, SpeechRecognizer —
микрофон и
speech - Уведомления, Push — разрешение
notifications - Файлы и шеринг —
openFilePicker: системный выбор фото и файлов, без запроса разрешений - Жизненный цикл приложения —
"pause"/"resume"