Разрешения

permissions спрашивает у пользователя доступ к камере, микрофону, геопозиции, распознаванию речи или уведомлениям, сообщает, что он ответил, и после отказа открывает страницу приложения в настройках. Камерные вью, notifications.schedule, Push.register() и плагины спрашивают сами; используй его, чтобы спросить раньше или обработать отказ. Выбору фото (openFilePicker) разрешение не нужно.

  • запросить камеру или микрофон до того, как они понадобятся функции (permissions.request)
  • проверить без диалога, выдано ли уже разрешение (permissions.query)
  • объяснить зачем, до того как покажется системный диалог
  • пользователь отказал: отправить его в настройки приложения (permissions.openSettings)
  • знать, когда iOS, Android и веб спрашивают снова после отказа
  • объявить разрешения, которые запрашивает опубликованное приложение (Info.plist, манифест Android)

Платформы: все хосты; диалог есть на iOS, Android, в вебе и в веб-плеере — на десктопе и в headless-тестах его нет, и любой вид отвечает "granted"; openSettings ничего не делает в вебе, в веб-плеере и на десктопе.

Обзор

TypeScript
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

TypeScript
permissions.request(kind): Promise<PermissionState>   // диалог, если ещё не спрашивали; потом — состояние

type PermissionKind = 'camera' | 'microphone' | 'location' | 'speech' | 'notifications'
type PermissionState = 'granted' | 'denied' | 'prompt'

request спрашивает у пользователя доступ к камере, микрофону, геопозиции, распознаванию речи или уведомлениям: показывает диалог ОС, если его ещё не спрашивали, и резолвится его ответом. При повторном запросе он резолвится текущим состоянием — или ОС показывает свой диалог ещё раз: это решает ОС (ниже). Спрашивай там, где пользователь этого ждёт, — первый тап по кнопке записи, первое «поделиться геопозицией», — а не при старте приложения: диалог, которого никто не понял, — это "denied", который останется.

TypeScript
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.
Note

на iOS и Android запросы ждут в очереди: две функции, спросившие одновременно, получают диалоги один за другим, а один вид, запрошенный дважды, пока его диалог на экране, получает один диалог и два ответа.

Проверить, выдано ли разрешение: permissions.query

TypeScript
permissions.query(kind): Promise<PermissionState>   // состояние сейчас, никогда не диалог

query без диалога проверяет, выдан ли уже доступ к камере, микрофону, геопозиции, распознаванию речи или уведомлениям: "granted", "denied" (отказано или заблокировано политикой устройства) или "prompt" (ещё не спрашивали: request покажет диалог). По нему выбирай, что показать на экране, — саму функцию, кнопку, которая спрашивает, или путь в настройки.

TypeScript
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()
Note

Android не хранит состояние «ещё не спрашивали»: query отвечает "prompt", пока это приложение ни разу не спросило, и "denied" после отказа, даже когда ОС показала бы диалог снова. В вебе браузер может не знать ответа до запроса (Safari до 16, Firefox для камеры): тогда он отвечает "prompt".

Объяснить зачем — до системного диалога

iOS показывает диалог один раз, так что, пока состояние "prompt", сначала покажи своё объяснение, а request вызывай, только когда пользователь пошёл дальше. В самом диалоге — текст назначения из сборки приложения (его объявляют плагины).

TypeScript
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)

TypeScript
permissions.openSettings(): void   // собственная страница приложения в системных настройках

Когда пользователь отказал в доступе к камере, микрофону или геопозиции, путь назад — системные настройки: openSettings() открывает там собственную страницу приложения (iOS: страница приложения в «Настройках»; Android: экран сведений о приложении с его разрешениями). iOS никогда не показывает диалог дважды; Android перестаёт спрашивать, когда так решит ОС. Пользователь включает разрешение и возвращается, а приложение перечитывает его на "resume" (жизненный цикл приложения).

TypeScript
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 он открывает собственную страницу вьюера: разрешения там — вьюера, одни и те же для каждого проекта, который он запускает.
Note

на 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
JSON
{ "plugins": { "camera": "*" } }
  • Вид, который не объявляет ни один из перечисленных плагинов, ломается в опубликованном приложении: iOS закрывает приложение при запросе камеры или микрофона (текст назначения обязателен), не показывает диалог геопозиции и отклоняет speech; Android отвечает "denied" без диалога.
  • Приложение-вьюер le.codes объявляет все виды, так что там проект работает в любом случае: проверь список plugins перед публикацией.

Собственные разрешения плагина: @permission

Контракт плагина помечает метод, которому нужно разрешение (@permission microphone в его contract.d.ts). Сгенерированный нативный код спрашивает тот же сервис хоста перед вызовом и отклоняется с denied, если в разрешении отказано, — собственный код плагина никогда не показывает диалог, — а lecodes plugin gen падает, если в манифестах плагина нет текста назначения для платформы или <uses-permission>. См. нативные плагины.

Смотрите также