bluememe-cordova-wifi-connector/README.md

# Bluememe Wi-Fi Connector Cordova Plugin

这个仓库现在是一个可供 OutSystems 11 Android 和 iOS 应用引用的 Cordova 插件仓库。

## 适用场景

- Android 9 及以下: 可直接调用旧版 `WifiManager` API 切换到指定 Wi-Fi。
- Android 10 及以上: 不能再由第三方应用静默强制切换到任意 Wi-Fi。
- Android 10+: 可用 `WifiNetworkSpecifier` 建立应用级本地连接，适合设备配网、IoT、局域网直连。
- Android 10+: 可用 `WifiNetworkSuggestion` 向系统提交候选 Wi-Fi，是否连接由系统决定。
- Android 11+: 可用 `ACTION_WIFI_ADD_NETWORKS` 弹出系统界面让用户确认保存该 Wi-Fi；这是最接近旧版“添加并连接设备 Wi-Fi”的官方替代方案。
- iOS 11+: 可用 `NEHotspotConfigurationManager` 让用户授权加入指定 Wi-Fi。
- iOS 11+: 支持持久化保存网络，也支持 `joinOnce` 的临时连接模式。

## OutSystems 11 接入方式

在移动应用主模块的 `Extensibility Configurations` 中加入插件地址。常见写法如下:

```json
{
  "plugin": {
    "url": "git+https://<your-git-host>/cordova-plugin-bluememe-wifi-connector.git#v1.0.0"
  }
}
```

这里要使用 `git+https://` 前缀，让 Cordova 按 Git 仓库而不是普通下载地址处理这个 URL。

如果你直接使用当前仓库作为插件仓库，把 `<your-git-host>` 换成你的 Git 地址即可；开发阶段也可以临时写成 `#main`，正式发布建议固定到 tag。

## JavaScript 调用

插件加载后可通过 `cordova.plugins.BluememeWifiConnector` 调用。

```javascript
document.addEventListener("deviceready", function () {
  cordova.plugins.BluememeWifiConnector.connect({
    ssid: "Factory_AP_01",
    passphrase: "12345678",
    security: "WPA2",
    mode: "auto"
  }).then(function (result) {
    console.log("Wi-Fi success", result);
  }).catch(function (error) {
    console.error("Wi-Fi error", error);
  });
});
```

iOS 成功时会额外返回 `connectionSucceeded`、`connectionStatus` 和 `details`。其中 `details` 会包含 `configuredSSIDs`、`requestedSSIDConfiguredByApp`、`passphraseLength` 等诊断字段；失败时同样会把输入摘要和 native 错误信息放进 `error.details`，便于定位是参数问题还是系统拒绝。

## 推荐模式

### 1. 设备级保存网络

Android 11+ 推荐:

```javascript
cordova.plugins.BluememeWifiConnector.saveNetwork({
  ssid: "OfficeWifi",
  passphrase: "OfficePass123",
  security: "WPA2"
});
```

说明:

- 会弹出 Android 系统界面。
- 用户确认后，系统保存网络。
- 这是 Android 官方给第三方应用的替代方案，最接近旧版 `addNetwork()` 行为。

### 2. 应用级连接指定 Wi-Fi

适合连接设备热点、IoT 配网、局域网设备:

```javascript
cordova.plugins.BluememeWifiConnector.connectLocalOnly({
  ssid: "Device_AP",
  passphrase: "87654321",
  security: "WPA2",
  bindToProcess: true,
  timeoutMs: 30000
});
```

说明:

- 连接范围主要是当前应用。
- 如果 `bindToProcess` 为 `true`，当前应用进程网络请求会绑定到该 Wi-Fi。
- 不适合作为“静默切换手机整机网络”的通用方案。

### 3. 提交候选 Wi-Fi

```javascript
cordova.plugins.BluememeWifiConnector.addNetworkSuggestion({
  ssid: "BranchWifi",
  passphrase: "BranchPass123",
  security: "WPA2"
});
```

说明:

- 系统会决定是否采用这个候选网络。
- 不保证立即切换。

### 4. iOS 持久化加入指定 Wi-Fi

```javascript
cordova.plugins.BluememeWifiConnector.saveNetwork({
  ssid: "OfficeWifi",
  passphrase: "OfficePass123",
  security: "WPA2"
});
```

说明:

- iOS 会弹出系统授权。
- 成功后等价于用户在系统里加入该 Wi-Fi。
- 依赖 `Hotspot Configuration` entitlement，插件安装时会向 Cordova iOS 工程注入。

### 5. iOS 临时加入指定 Wi-Fi

```javascript
cordova.plugins.BluememeWifiConnector.connectLocalOnly({
  ssid: "Device_AP",
  passphrase: "87654321",
  security: "WPA2"
});
```

说明:

- 在 iOS 上会映射为 `joinOnce` 临时连接。
- 更适合设备热点、IoT 配网、局域网直连。
- iOS 不支持像 Android 那样把网络请求绑定到该 Wi-Fi 进程。

## `connect(options)` 的自动策略

`connect()` 会按平台自动选模式:

- Android 9 及以下: `legacy`
- Android 10 且 `localOnly = true`: `localOnly`
- Android 11 及以上: `save`
- Android 10 其他情况: `suggestion`
- iOS 且 `localOnly = true`: `localOnly`
- iOS 其他情况: `save`

`options` 字段:

```javascript
{
  ssid: "Required",
  passphrase: "Optional for OPEN, required for WPA2/WPA3",
  security: "OPEN | WPA2 | WPA3",
  hidden: false,
  mode: "auto | legacy | localOnly | suggestion | save",
  localOnly: false,
  bindToProcess: true,
  timeoutMs: 30000,
  appInteractionRequired: false
}
```

说明:

- iOS 当前实现支持 `OPEN` 和 `WPA2`。
- `WPA3`、`suggestion`、`legacy` 仅在 Android 上支持。

## OutSystems 页面里的简单调用示例

如果你在 OutSystems 页面或 JavaScript 节点中直接写 JS，可以用:

```javascript
if (!window.cordova || !cordova.plugins || !cordova.plugins.BluememeWifiConnector) {
  console.error("Cordova plugin not loaded yet.");
} else {
  cordova.plugins.BluememeWifiConnector.saveNetwork({
    ssid: "Factory_AP_01",
    passphrase: "12345678",
    security: "WPA2"
  }).then(function (result) {
    console.log(JSON.stringify(result));
  }).catch(function (error) {
    console.error(JSON.stringify(error));
  });
}
```

完整示例见 [examples/outsystems-connect-specific-wifi.js](examples/outsystems-connect-specific-wifi.js)。

## `disconnect()` 行为

```javascript
cordova.plugins.BluememeWifiConnector.disconnect();

cordova.plugins.BluememeWifiConnector.disconnect({
  ssid: "Device_AP"
});
```

说明:

- Android: 释放 `localOnly` 网络；Android 9 及以下还会调用旧版 `WifiManager.disconnect()`。
- iOS: 移除当前应用通过 `NEHotspotConfigurationManager` 配置过的 Wi-Fi；可选传入 `ssid` 只移除单个网络配置。

## 主要文件

- `plugin.xml`: Cordova 插件声明与 Android 权限。
- `src/android/BluememeWifiConnector.java`: Android 原生实现。
- `src/ios/BluememeWifiConnector.m`: iOS 原生实现。
- `www/BluememeWifiConnector.js`: Cordova JS bridge。

## 限制

- Android 10+ 不支持第三方应用静默强制切换整机到任意 Wi-Fi。
- `saveNetwork()` 需要用户确认。
- `connectLocalOnly()` 更适合配网和设备热点通信，不是通用整机联网替代方案。
- WPA Enterprise / EAP 没有在这个版本中实现。
- iOS 不支持 Android 的 `WifiNetworkSuggestion` / `legacy` 路径。
- iOS `disconnect()` 的本质是移除由当前应用添加的 Wi-Fi 配置，不等价于强制断开任意当前网络。
- iOS 需要真机和正确签名；模拟器不能验证这类 Wi-Fi 能力。