# Extension not detected

Your page loaded `@beacio/core` (or the CDN script) but `navigator.bluetooth.getAvailability()` returns `false` and `requestDevice()` rejects. This page enumerates every reason the extension fails to connect to Safari and how to fix each one.

## Symptom

```js
await navigator.bluetooth.getAvailability(); // → false
await navigator.bluetooth.requestDevice(...); // → rejects with NotSupportedError
```

Or, at import time, `navigator.bluetooth` is `undefined` entirely.

## 1. Extension not enabled in Safari

Most common cause. iOS installs Safari Web Extensions disabled by default.

**Fix:**

1. Open **Settings → Apps → Safari → Extensions**.
2. Tap **beacio**.
3. Toggle **Allow Extension** on.
4. Set **Permission → Other Websites** to **Allow**.

Reload the page. `navigator.bluetooth` should now be defined.

## 2. "Always Allow on Every Website" not granted

iOS Safari extensions default to per-origin opt-in: the first time a tab uses the extension, Safari shows a banner asking for permission. If the banner was dismissed with "Deny" or ignored, the extension is inert on that site.

**Fix:**

1. Navigate to the site.
2. Tap the **`A`A** button in the address bar.
3. Tap **Manage Extensions**, choose **beacio**, and grant **Always Allow on Every Website** (or at least on this origin).

Reload the page.

## 3. Private Browsing tab

iOS Safari disables most extensions in Private Browsing. There is no per-extension opt-in; this is by design.

**Fix:** open the site in a standard Safari tab (close Private Browsing or switch tab groups).

## 4. iOS version too old

beacio requires **iOS 26.0 or later** — the minimum OS version of the App Store listing. (Safari Web Extensions as a platform date back to iOS 15, but the beacio app itself targets iOS 26.0.)

**Fix:**

- Open **Settings → General → About** and check the iOS version.
- Update iOS from **Settings → General → Software Update**.
- If the device cannot update (older hardware), beacio is not supported on that device.

## 5. beacio app never launched

The extension only registers with Safari after the host app has been launched at least once.

**Fix:** open the beacio app from the home screen, let it finish first-run setup, then reload the site.

## 6. Non-HTTPS origin

Web Bluetooth (and the beacio polyfill) requires a secure context. `http://` pages and custom schemes don't get `navigator.bluetooth`.

**Fix:** serve over HTTPS. For local development, `localhost` is treated as secure and works without a certificate.

## 7. The polyfill script didn't load

Verify the `<script src="https://beacio.com/beacio.js">` tag is present and the response was not blocked by a content-security-policy header. Check the Safari Web Inspector console for a 4xx on the script URL.

If using npm, verify you imported `@beacio/core` on a client-side boundary (not inside a Node-only SSR pathway; see [Next.js quickstart](../quickstart-next.md)).

## Still stuck?

Open an issue at [github.com/wklm/beacio-sdk/issues](https://github.com/wklm/beacio-sdk/issues) with: iOS version, Safari version, the page URL (or a repro), and the exact message Safari's console printed.