Puppeteer DeviceRequestPromptDevice: Device Details Explained

DeviceRequestPromptDevice is Puppeteer’s type for a device entry shown in a device request prompt. Its documented fields are id: string, the device id during that prompt, and name: string, the name shown in the prompt. It is not documented as a permanent hardware identifier or a complete device specification.

To use an entry, start page.waitForDevicePrompt() before triggering the page’s device request, find a matching entry with prompt.waitForDevice(), then pass it to prompt.select(). The prompt also exposes its current selectable entries in prompt.devices and can be dismissed with prompt.cancel().

1. What the type represents

Puppeteer describes the type as a “Device in a request prompt.” The larger DeviceRequestPrompt workflow lets automation respond when a page requests a device through an API such as WebBluetooth. The type represents an entry in that prompt; it is not an emulator profile or an inventory of hardware capabilities.

That distinction matters when reading the fields. They describe what Puppeteer exposes for a particular prompt entry. The API reference does not define additional fields for manufacturer, Bluetooth address, supported services, connection state, or hardware specifications.

2. The documented fields

Field	Type	Documented meaning	Practical use
id	string	Device id during a prompt.	Identifier associated with the entry in this prompt. The docs do not say it is a Bluetooth address or permanent hardware ID.
name	string	Device name as it appears in the prompt.	Human-readable value useful for filtering. The docs do not guarantee it is unique or stable.

Both values are strings. Treat names as display labels: two entries could have similar names, and a name match alone should not be taken as proof of a particular physical device. If the page may show multiple matching entries, inspect the current list and add selection logic appropriate to the page’s behavior.

3. Wait for the prompt, then select a device

The ordering is essential. page.waitForDevicePrompt() must be started before the page triggers the device request. The Page API says it will not return a prompt that is already active. Start waiting and perform the action that opens the request together, then filter and select.

Runnable Puppeteer example

Install Puppeteer in a Node.js project with npm install puppeteer. This example assumes the page has a button with the selector #connect-bluetooth that causes its device request. Replace the URL and selector with those for your page.

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({ headless: false });
  try {
    const page = await browser.newPage();
    await page.goto('https://example.com', { waitUntil: 'domcontentloaded' });

    // Begin waiting before the click triggers the device request.
    const [devicePrompt] = await Promise.all([
      page.waitForDevicePrompt(),
      page.click('#connect-bluetooth'),
    ]);

    // Match the displayed name. Choose a filter specific to your page.
    const device = await devicePrompt.waitForDevice(({ name }) =>
      name.includes('My Device'),
    );

    await devicePrompt.select(device);
  } finally {
    await browser.close();
  }
})();

The filter pattern follows Puppeteer’s documented example: match a substring of the displayed name. It is an example, not a guarantee that names are unique. A production flow should account for the page’s possible device names and for a matching entry never appearing.

Inspect the current list or cancel

If the list is already available and you want to inspect its current contents, devices is the prompt’s current list of selectable devices. You can then select an entry from that list, or cancel the prompt when no choice is appropriate.

const devices = devicePrompt.devices;

for (const device of devices) {
  console.log({ id: device.id, name: device.name });
}

if (devices.length === 0) {
  await devicePrompt.cancel();
} else {
  await devicePrompt.select(devices[0]);
}

This selects the first current entry only as an example. In real automation, use an explicit predicate or handle multiple candidates deliberately rather than assuming list order has a particular meaning.

4. Timing, filters, and edge cases

• Start waiting before the trigger. If the prompt is already active when waitForDevicePrompt() is called, the Page API says that call will not return it. Start the wait before clicking or running the page action that requests a device.
• Handle a missing match. waitForDevice() waits for an entry matching its filter. If the expected name never appears, the wait may not resolve successfully. Set an appropriate timeout using the options supported by the installed Puppeteer version, and handle the timeout in your flow.
• Do not assume name uniqueness. A substring filter can match more than one plausible label over time. Make the predicate as specific as the available prompt-visible names allow.
• Use the entry from the prompt. select(device) selects an entry from that prompt’s list. Do not manufacture an object with an assumed id or pass an unrelated object.
• Cancel when selection is not possible. If the flow cannot safely choose an entry, call cancel() so the prompt does not remain waiting for a decision.
• Keep the type’s scope narrow. The documented shape is only id and name. Do not build logic around undocumented hardware properties.

Check the API reference for the Puppeteer version in your project when relying on optional wait settings or version-specific behavior: DeviceRequestPromptDevice, DeviceRequestPrompt, and Page.waitForDevicePrompt().

5. Troubleshooting

Symptom	Likely cause	Fix
waitForDevicePrompt() never produces the prompt	The wait began after the page had already opened the prompt, or the page action did not trigger a device request.	Start the wait before the triggering action, typically in Promise.all() with the click. Confirm the action really requests a device.
waitForDevice() times out or does not find an entry	The filter does not match the prompt-visible name, the expected device is not listed, or the prompt did not open.	Inspect prompt.devices, adjust the predicate to the displayed name, and handle timeout or an empty list.
The wrong entry is selected	A broad substring matched a different entry or code assumed the first list item was the intended device.	Use a more specific predicate and inspect the candidates before selecting when ambiguity matters.
TypeScript reports a type or property error	Code assumes fields beyond the documented id and name, or its installed Puppeteer version differs from the reference being followed.	Restrict access to documented fields and check the API reference and package version used by the project.
The page action hangs while the prompt is open	The prompt has not been selected or cancelled.	Ensure every successful prompt path ends in select() or cancel(), including error-handling paths.

6. Performance, reliability, and cost

This type is a small part of an interactive browser flow; the practical reliability issue is synchronization with the page’s request and handling the prompt’s candidate list. Waiting for the prompt concurrently with the triggering action avoids the ordering mistake of waiting after the event. Keep name matching explicit, give waits a suitable timeout, and make timeout and cancellation paths visible in logs.

The type reference provides no performance benchmark or cost figure. Puppeteer automation costs depend on where and how you run the browser, which is outside the definition of this type. For visual checks of the page itself, a screenshot capture service can avoid maintaining browser capture setup; it does not replace this device-prompt interaction.

7. Or skip the browser setup

If your task is capturing a page image rather than handling a device request, ScreenshotNeo is a website screenshot API and MCP server for developers. Its API accepts one GET request with a URL and returns a screenshot or PDF. See the ScreenshotNeo API documentation for options.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const image = Buffer.from(await res.arrayBuffer());
await require('node:fs/promises').writeFile('shot.webp', image);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and the response includes page-verdict and billing headers. Its MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents. The free plan includes 1,000 shots a month without a card; paid plans start at $5 for 3,000 shots. Every feature is on every plan.

Sign up free for 1,000 screenshots a month, no card required.

8. FAQ

Is DeviceRequestPromptDevice a physical-device specification?

No. It is the prompt entry type, with documented id and name string fields.

Does id mean Bluetooth address?

The API reference calls it the device id during a prompt. It does not define it as a Bluetooth address or a permanent identifier.

Can I use the device name as a unique key?

The documentation does not promise uniqueness or stability. Use it as a prompt-visible label and make matching logic account for ambiguity.

Why must I wait before clicking Connect?

waitForDevicePrompt() is intended to be set up before the page triggers its request and does not return a prompt that is already active.

References

• Puppeteer: DeviceRequestPromptDevice
• Puppeteer: DeviceRequestPrompt
• Puppeteer: Page.waitForDevicePrompt()