aria/bluememe-cordova-wifi-connector

0 Fork 0

Files

T

aria 41739ef881 Update README for git+https plugin URL

2026-03-28 05:20:12 +09:00

6.6 KiB

Raw Blame History

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 中加入插件地址。常见写法如下:

{
  "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 调用。

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

推荐模式

1. 设备级保存网络

Android 11+ 推荐:

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

说明:

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

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

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

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

说明:

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

3. 提交候选 Wi-Fi

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

说明:

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

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

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

说明:

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

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

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 字段:

{
  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，可以用:

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。

`disconnect()` 行为

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 能力。

6.6 KiB Raw Blame History