Device & platform APIs

Device APIs need the person's trust

An API is a set of objects and functions that the browser gives your code. So far, your JavaScript has changed data, the page, forms, storage, and network requests. Device APIs reach further, into the person's own device. With them, a page can:

• copy text to the clipboard, the place where copied text waits until you paste it, and read it back;
• ask where the device is (this is called geolocation);
• show notifications, the small messages that pop up from the operating system;
• play sound and video.

These are useful. They also touch the person's privacy and attention, so the browser guards them. Good code follows the same steps every time:

1. Check that this browser has the feature.
2. Say why the page needs it.
3. Wait until the person clicks or acts.
4. Handle a "no".
5. Keep another way to finish the task.

This lesson uses events from Introduction to events and promises from Promises. It also uses a Blob from the Files & Blobs lesson. A Blob is a chunk of raw data, like a small file made in code.

Most browsers allow these APIs only in a secure context. That means a page that came over HTTPS, or from localhost while you build on your own computer. HTTPS stops other people on the network from changing the page on its way to you. Without it, an attacker could change a page that asks for your location. No library or framework can skip this rule; the browser decides.

Browsers also differ in which APIs they have. This matters in React. React often builds the page first on a server, and the server has no navigator, no window, no permissions, and no speakers. So check for browser features only in the browser:

• after the page has loaded there (React calls this after mount), or
• inside a click handler.

If the server guesses one answer and the browser finds another, React sees two different pages. It then shows a warning called a hydration mismatch.

The step-through below is a small model of a good permission request. It shows the order: name the feature, see that the person has not decided yet, wait for a click, and say why before the real request.

1const feature = "clipboard-write";Run2const state = "prompt";3 4if (state === "prompt") {5  console.log("wait for a click before requesting " + feature);6}7 8console.log("explain why the app needs " + feature);

A feature check asks a smaller question than a permission does: "Does this browser have this function?" Check before you turn a button on. The code below uses a made-up browser object in place of the real navigator, so it gives the same answers everywhere.

1const browser = {2  mediaDevices: { getUserMedia() {} },3  vibrate: true,4  getBattery: false,5};6 7console.log(typeof browser.mediaDevices?.getUserMedia === "function");8console.log(browser.vibrate === true);9console.log(typeof browser.getBattery === "function");

Line 7 uses ?. (optional chaining). If mediaDevices were missing, it would give undefined instead of an error. typeof gives the type of a value as text, so typeof x === "function" is true only for a function. In plain words, line by line:

1. Line 7 prints true. getUserMedia is a function, so the page could ask for the microphone.
2. Line 8 prints true. In this model, vibrate is true.
3. Line 9 prints false. getBattery is false, not a function, so battery info is missing.

Having a function is not the same as having permission. The function can exist, and the person can still say no.

The Clipboard API lives at navigator.clipboard. Its most common use is copying text after a click, with writeText().

writeText() returns a promise. A promise is a value that later says "done" (it resolves) or "failed" (it rejects). So show "Copied" only after it resolves, and show the real error if it rejects.

Some browsers let a page write to the clipboard only right after the person clicks or presses a key. So call writeText() directly inside the click handler, not later.

1const text = messageInput.value;2await navigator.clipboard.writeText(text);3status.textContent = "Copied!";4 5pasteBox.addEventListener("paste", (event) => {6  status.textContent = event.clipboardData.getData("text");7});8 9const pasted = await navigator.clipboard.readText();

The lab has two ways to read text:

• The paste field. You choose Paste yourself, so the browser fires a paste event. The event carries the pasted text in event.clipboardData.
• The Read clipboard button. It calls readText(), which asks the browser for whatever is on the clipboard right now. That is more private, so most browsers show a question or a small Paste menu first.

A permission is the person's yes or no for one feature on one site. navigator.permissions.query() reads the current answer without showing the person a question. That helps you:

• turn a button on or off;
• show a helpful note next to a feature;
• build a dashboard like the one below.

Not every browser knows every permission name. An unknown name can throw a TypeError. So the code catches that error, and you still check the feature itself.

1const names = ["geolocation", "notifications", "camera"];2 3for (const name of names) {4  try {5    const status = await navigator.permissions.query({ name });6    render(name, status.state);7    status.addEventListener("change", () => render(name, status.state));8  } catch (error) {9    render(name, "unsupported");10  }11}

Each row below is one state that query() can report. Read across to see what it means and what your page should do.

A denied answer should change what the page offers. The page should not ask again and again. The code below keeps the task useful: when location is denied, the person types a city instead.

1const permission = "denied";2const message = permission === "granted"3  ? "Use device location"4  : "Let the person type a city";5 6console.log(message);

In plain words, line by line:

1. Line 1 sets the state to "denied".
2. Lines 2 to 4 pick a message. Only "granted" gets the device location; every other state gets line 4.
3. Line 6 prints Let the person type a city.

query() gives back a PermissionStatus object. It fires a change event when the person changes a browser setting while your page is open.

Remember: prompt does not mean yes. It means "not decided yet". Ask later, when the person wants this feature.

navigator.geolocation.getCurrentPosition() asks where the device is. It takes three arguments:

• a success callback (a function the browser calls later), which gets the position;
• an error callback, which gets an error with a number in code;
• an options object.

The position holds latitude, longitude, and accuracy. Accuracy is in meters: how far off the answer might be.

The options let you choose:

• enableHighAccuracy: try for a more exact answer. It may be slower or use more battery.
• timeout: how many milliseconds to wait before giving up.
• maximumAge: how old a saved answer may be, in milliseconds.

1navigator.geolocation.getCurrentPosition(2  (position) => {3    const { latitude, longitude, accuracy } = position.coords;4    show(formatCoordinates(latitude, longitude, accuracy));5  },6  (error) => show(mapGeolocationError(error.code)),7  { enableHighAccuracy: true, timeout: 8000, maximumAge: 60000 },8);

This lesson rounds coordinates to two decimal places so they are easy to read. A real app should decide what it needs: an exact location, a rough area, or a city the person types. The lab never saves or sends your coordinates. If you don't want to share, use Simulate Mumbai result.

The Notifications API keeps its own permission in Notification.permission. It has one of three values: granted, denied, or default (not decided yet).

To ask, call Notification.requestPermission(). Call it only after the person chooses a notification feature, such as a "Remind me" button.

1if (Notification.permission === "default") {2  const permission = await Notification.requestPermission();3  if (permission === "granted") {4    new Notification("Device APIs lab", { body: "Thanks for opting in." });5  }6}

A page can show a test notification while it is open. Real apps usually send notifications from a service worker, a script that keeps running in the background, so messages arrive even when the page is not in front. Some platforms limit web notifications even more, for example to web apps that the person installed. When browsers differ like this, say "in most browsers", not "always".

An <audio> or <video> element is an HTMLMediaElement. Both have the same tools:

• methods: play() and pause();
• properties: currentTime (seconds played), volume (0 to 1), and playbackRate (speed, where 1 is normal);
• events: play, pause, timeupdate (the time moved on), and ended.

1const audio = document.querySelector("audio");2 3try {4  await audio.play();5  log("play() resolved");6} catch (error) {7  log(error.name);8}9 10audio.volume = 0.4;11audio.playbackRate = 1.25;12audio.addEventListener("timeupdate", updateClock);

To use the camera or microphone, call navigator.mediaDevices.getUserMedia(). It needs a secure page and the person's permission. So ask from a button, and stop each track (one stream of sound or video) when you no longer need it. You can't run the code below here, because its result depends on a real microphone and the browser's question.

1async function askForMicrophone() {2  if (!navigator.mediaDevices?.getUserMedia) {3    throw new Error("Microphone capture is unavailable here.");4  }5  return navigator.mediaDevices.getUserMedia({ audio: true });6}7 8button.addEventListener("click", async () => {9  try {10    const stream = await askForMicrophone();11    status.textContent = "Microphone ready.";12    stream.getTracks().forEach((track) => track.stop());13  } catch (error) {14    status.textContent = error instanceof Error ? error.name : "Microphone unavailable.";15  }16});

In plain words, line by line:

1. Line 2 checks that getUserMedia exists. If not, line 3 throws an error.
2. Line 5 asks for sound only: { audio: true }.
3. Line 8 waits for a click on the button.
4. Line 10 waits for the person's answer.
5. Line 12 stops every track, so the microphone turns off again.

Vibration is a small extra signal, and many devices don't have it. Check with "vibrate" in navigator first, and respect people who turn off motion. Battery info is missing even more often: navigator.getBattery() may not exist, or may be blocked. Never make the main task depend on the battery level.

1if ("vibrate" in navigator) {2  navigator.vibrate(200);3}4 5if ("getBattery" in navigator) {6  const battery = await navigator.getBattery();7  console.log(Math.round(battery.level * 100) + "%");8} else {9  console.log("Battery status is unavailable.");10}

In plain words, line by line:

1. Lines 1 to 3 vibrate for 200 milliseconds, but only if vibrate exists.
2. Lines 5 to 7 read the battery and print its level as a percent.
3. Line 9 prints a message when battery info is missing.

The media lab makes a tiny WAV sound file inside the page. It plays it from a Blob URL, a short address that points to data made in the page, so nothing is downloaded.

The Play button matters because of autoplay rules. In most browsers, starting sound without a click makes play() reject with NotAllowedError. A video element works the same way.

Real tasks start as plain sentences, not API names: "copy the invite link", "show nearby classes", "remind me when the export is done", or "slow down the video". For each task below, ask what it touches. Then ask what permission or click it needs.

• "One permission covers everything." Each feature has its own permission, usually per site. Allowing location does not allow notifications.
• "prompt means I can use it." It means the person has not decided yet. Ask only when they choose the feature.
• "permissions.query tells me everything." Browsers know different names, and an unknown name can throw. Check the feature too.
• "Geolocation is exact." The answer comes with an accuracy in meters. It can also be old, missing, or denied.
• "play() always starts the sound." Its promise can reject because of autoplay rules, missing data, or a file type the browser can't play.
• "Reading the clipboard is the same as a paste." In a paste, the person chose to hand you the text. readText() takes it without that step, so browsers guard it more.

Key takeaways

• Most device APIs work only on secure pages (HTTPS or localhost). Check that the browser has the feature before you use it.
• Ask for a permission only after the person clicks, never when the page loads.
• Clipboard reads, geolocation, notifications, and media playback can all fail in normal use. Plan for it.
• Geolocation gives an accuracy in meters and has three error codes. Never assume the answer is exact.
• HTMLMediaElement runs both audio and video, with a promise from play(), properties, and events.

Up next: Web Workers.