# Extension not detected

Your page loaded `@ios-web-bluetooth/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 **WebBLE**.
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 **WebBLE**, 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

WebBLE requires Safari Web Extensions, which ship in **iOS 15** and later. Some premium background-sync features require iOS 17+.

**Fix:**

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

## 5. WebBLE app never launched

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

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

## 6. Non-HTTPS origin

Web Bluetooth (and the WebBLE 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://cdn.ioswebble.com/v1.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 `@ios-web-bluetooth/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/ioswebble-sdk/issues](https://github.com/wklm/ioswebble-sdk/issues) with: iOS version, Safari version, the page URL (or a repro), and the exact message Safari's console printed.