A page that is on the screen can record sound, use the camera and get one position of the device. A function cannot use them.
| Permission | Access row | What the page can do |
|---|---|---|
microphone.use | Microphone | Record sound with getUserMedia |
camera.use | Camera | See through the camera with getUserMedia |
location.read | Location | Get one position with location.current({}) |
Declare each permission in the manifest actions of the app. Without it,
Access shows no row and the page cannot use the device. Access shows each row
under This computer. The levels are Off, Ask and Allow. The default is Ask for
an app that is not from a draft. The app can keep or send what it records, what
the camera sees and the position with its other permissions, for example to the
agent or by email.
An app that Chat makes is a draft first. In a draft, each row starts at Off. After install, a new row (for example a permission that an update adds) also starts at Off. In the Draft tab, the owner can set the microphone and the camera to Off or Ask (a write cannot be Allow in a draft), and the location to Off, Ask or Allow. The Install dialog shows each row at its draft level, and the owner can change it there, also to Allow. A draft check cannot use these devices: the microphone and the camera are Off during a check, and Chat has no Location row. Mark such a check row "Not checked" and ask the owner to try the page in the Draft tab.
"actions": ["microphone.use", "camera.use", "location.read"]
Record sound or use the camera
Use the standard navigator.mediaDevices.getUserMedia in the page. No SDK call
is needed.
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const recorder = new MediaRecorder(stream);
recorder.start();
// Later: recorder.stop(); stream.getTracks().forEach((track) => track.stop());
Ask for audio, video or both. A request for both asks one question and needs
both permissions. Redac refuses the request, and getUserMedia rejects, when:
- the page is not on the screen, or a function makes the request;
- the app does not declare the permission, or one level is Off;
- the page has a child frame (
iframe); - the person selects Don't allow;
- macOS blocks the device for Redac.
At Ask, Redac asks "<App> wants to use the microphone" (or the camera, or the
camera and the microphone). At Allow, Redac does not ask. On the first use,
macOS also asks once for Redac. Screen capture (getDisplayMedia) is always
refused.
While a device is on, the title bar shows "Recording", "Camera on" or "Camera and microphone on" with Stop. Capture stops when the person selects Stop, when the page leaves the screen, when a level changes to Off, or when the page adds a frame. Redac then stops the tracks, closes the page within 1 second and shows "Recording stopped." in its place. Stop your own tracks when you no longer need them.
Get the location
location.current({}) returns {latitude, longitude, accuracy, timestamp}.
accuracy is in meters. timestamp is in milliseconds since 1970. Each call
gets one position. Redac does not keep it and does not watch the position.
try {
const here = await client.cap.call('location.current', {});
showMap(here.latitude, here.longitude);
} catch (error) {
// unauthorized, denied or unavailable: show a short message.
}
At Ask, Redac asks "<App> wants to know where you are" for each call. At Allow, the title bar shows "<App> used your location" for 3 seconds. Redac waits at most 15 seconds for a position.
| Error | When |
|---|---|
unauthorized | The page is not on the screen, a function calls, the level is Off, or macOS blocks location for Redac |
denied | The person selects Don't allow |
unavailable | Redac could not find where you are |
The page cannot use navigator.geolocation. Use location.current.
Lines in the title bar
| Line | Action |
|---|---|
| "Microphone is off for this app." | Access settings |
| "Camera is off for this app." | Access settings |
| "Location is off for this app." | Access settings |
| "macOS blocks the microphone for Redac" | Open System Settings |
| "macOS blocks the camera for Redac" | Open System Settings |
| "macOS blocks location for Redac" | Open System Settings |
| "Finding where you are…" | None |
| "Redac could not find where you are" | None |
On the iPhone
A page on the iPhone uses the microphone, the camera and the location of the
iPhone, with the same Access level that the desktop shows. iOS asks once for
Redac. The phone answers location.current itself; the position is not sent
through the desktop.