Device & platform APIs

Why device APIs feel different

Most JavaScript you have written so far changes data, the DOM, forms, storage, or network requests. Device and platform APIs cross a more personal boundary: they can read the clipboard, ask where the device is, show system notifications, or start media through speakers and screens. That is useful, but it also touches privacy and attention.

The professional pattern is simple: check support in the real browser, explain the benefit, start from a user action, handle no, and keep a fallback. This lesson uses the same event skills from Introduction to events, the promise skills from Promises, and the Blob idea from the previous Files & Blobs lesson.

In most browsers, these APIs need a secure context: HTTPS in production or localhost during development. That rule matters because a network attacker should not be able to rewrite a page that asks for your location or clipboard. A framework cannot bypass this; the browser decides.

Support also differs by browser and platform. For browser lessons, that creates a React rule: feature detection happens after mount or after a user action, never during server render. The server does not have navigator, window, permissions, or an audio device, so guessing during render can create hydration mismatches.

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

The replay is a model of a good permission flow, not a browser debugger. It teaches the shape: name the feature, notice the state is still undecided, wait for the person to click, and explain why before the real request.

The Clipboard API lives at navigator.clipboard. The safe, common case is writing text after a click: writeText() returns a promise, so show success only after it resolves and show the real error if it rejects. In some browsers clipboard writing needs transient user activation, which means the call should happen directly from the click handler.

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();

Notice the difference between the paste field and the explicit read button. A normal paste event starts with the person choosing Paste, so the event carries the text for that field. readText() asks the browser to hand your page whatever is currently on the shared tray; in most browsers that is more sensitive and may prompt or show a menu.

navigator.permissions.query() checks some permission states without showing a prompt. That makes it useful for dashboards, disabled buttons, and helpful explanations. It does not support every name in every browser, so the code catches TypeError and still uses feature detection.

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}

The returned PermissionStatus can fire a change event. That matters when someone changes a browser setting while your page is open. Do not treat prompt as permission; it means “ask later, when the person actually wants this feature.”

navigator.geolocation.getCurrentPosition() accepts three arguments: a success callback, an error callback, and options. The result gives latitude, longitude, and accuracy in meters. The options shape the trade-off: enableHighAccuracy may be slower or use more power, timeout limits waiting, and maximumAge says how old a cached answer may be.

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 decimals so examples stay readable. Real apps should be clear about whether they need exact location, approximate region, or a manual city. The lab never stores or sends coordinates, and the simulated path is there for readers who decline.

The Notifications API has its own state at Notification.permission: granted, denied, or default. The request method is Notification.requestPermission(), and it should run only after the person chooses a notification feature.

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 create a test notification while it is open. Real apps often use a service worker for push notifications so messages can arrive when the page is not focused. Some platforms restrict web notifications even more, for example allowing them only for installed web apps. When behavior varies, say “in most browsers” instead of pretending every platform is identical.

An <audio> or <video> element is an HTMLMediaElement. It has methods like play() and pause(), properties like currentTime, volume, and playbackRate, plus events such as play, pause, timeupdate, 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);

The lab generates a tiny WAV file in the page with a Blob URL, so it does not fetch external media. Autoplay rules are why the Play button matters: in most browsers, trying to start unmuted media without a user gesture can reject with NotAllowedError. A video element shares the same core API.

Product code often starts with a sentence, not an API name: “copy the invite link,” “show nearby classrooms,” “remind me when export is done,” or “slow down the lesson video.” Sort by what the task touches, then ask what permission or user gesture is required.

• “Permission is global.” Permission is per capability and usually per origin. Location does not grant notifications.
• “prompt means I can use it.” It means the browser has not received a final answer. Ask only from a relevant action.
• “permissions.query tells me everything.” Names vary by browser; unsupported names can throw. Feature-detect too.
• “Geolocation is exact.” Coordinates include an accuracy radius and can be stale, unavailable, or denied.
• “play() always starts sound.” The promise can reject because of autoplay policy, missing data, or unsupported media.
• “Clipboard reads are the same as paste.” A paste event is user-initiated; explicit clipboard reads are more sensitive.

Key takeaways

• Powerful browser APIs usually require a secure context and real browser feature detection.
• Permission prompts belong behind user intent, not page load.
• Clipboard reads, geolocation, notifications, and media playback all have normal failure paths.
• Geolocation includes accuracy and error codes; never assume exact coordinates.
• HTMLMediaElement powers both audio and video with promises, properties, and events.

Up next: Web Workers.