Add macOS support (#23)
* Add macOS support * Update README * Update to v0.2.0 * Document breaking changes * Delete widget tests
This commit is contained in:
Ben Hagen
@@ -13,8 +13,8 @@ Nearby Service Flutter Plugin is used to create connections in a P2P network.
|
||||
The plugin supports sending text messages and files. With it,
|
||||
you can easily create any kind of information sharing application **without Internet connection**.
|
||||
|
||||
The package does not support communication between Android and IOS devices, the connection is available for
|
||||
**Android-Android** and **IOS-IOS** relations.
|
||||
The package does not support communication between Android and IOS/macOS (Darwin) devices, the connection is available for
|
||||
**Android-Android** and **Darwin-Darwin** relations.
|
||||
|
||||
Your feedback and suggestions would be greatly
|
||||
appreciated! [You can leave your opinion here](https://forms.gle/FbAtW2dG5RYCxb1DA)
|
||||
@@ -32,11 +32,11 @@ Or find the GIF demo at the end of the README:
|
||||
|
||||
- [About](#about)
|
||||
- [Android](#about-android-plugin)
|
||||
- [IOS](#about-ios-plugin)
|
||||
- [IOS and macOS](#about-ios-and-macos-plugin)
|
||||
- [Features](#features)
|
||||
- [Setup](#setup)
|
||||
- [Android](#android-setup)
|
||||
- [IOS](#ios-setup)
|
||||
- [IOS and macOS](#ios-and-macos-setup)
|
||||
- [Usage](#usage)
|
||||
- [Data sharing](#data-sharing)
|
||||
- [Text messages](#text-messages)
|
||||
@@ -44,6 +44,9 @@ Or find the GIF demo at the end of the README:
|
||||
- [Exceptions](#exceptions)
|
||||
- [Additional options](#additional-options)
|
||||
- [Demo](#demo)
|
||||
- [Migration Guide](#migration-guide)
|
||||
- [Migrating from v0.1.0 to v0.2.0](#migrating-from-v010-to-v020)
|
||||
|
||||
## About
|
||||
|
||||
> A peer-to-peer (P2P) network is a decentralized network architecture in which each participant, called a peer, can act
|
||||
@@ -65,14 +68,14 @@ To check permissions and Wi-fi status, the
|
||||
- `checkWifiService()` (Android only): returns true if Wi-fi is enabled
|
||||
- `requestPermissions()` (Android only): requests permissions for location and nearby devices and returns true if
|
||||
granted
|
||||
- `openServicesSettings()`: opens Wi-fi settings for Android and general settings for iOS
|
||||
- `openServicesSettings()`: opens Wi-fi settings for Android and general settings for iOS and macOS
|
||||
|
||||
> Testing the plugin **is not possible** on Android emulators, as they usually do not contain the Wi-fi Direct function
|
||||
> in general! Use physical devices for that.
|
||||
|
||||
### About IOS Plugin
|
||||
### About IOS and macOS Plugin
|
||||
|
||||
For IOS, the P2P connection is implemented through the `Multipeer Connectivity` framework.
|
||||
For IOS and macOS, the P2P connection is implemented through the `Multipeer Connectivity` framework.
|
||||
|
||||
This framework **automatically selects** the best network technology depending on the situation—using **Wi-Fi**
|
||||
if both devices are on the same network, or using **peer-to-peer Wi-Fi** or **Bluetooth** otherwise.
|
||||
@@ -85,8 +88,8 @@ the `nearby_service` plugin to open the settings and prompt the user to turn Wi-
|
||||
- **Device Preparation**
|
||||
- Requesting permissions to use Wi-Fi Direct (Android only)
|
||||
- Checking Wi-Fi status (Android only)
|
||||
- Opening settings to enable Wi-Fi (Android and iOS)
|
||||
- Role selection - Browser or Advertiser (IOS only)
|
||||
- Opening settings to enable Wi-Fi (Android and IOS/macOS)
|
||||
- Role selection - Browser or Advertiser (IOS and macOS only)
|
||||
|
||||
- **Connecting to the Device from a P2P Network**
|
||||
- Listening for discovered devices (peers)
|
||||
@@ -110,9 +113,9 @@ the `nearby_service` plugin to open the settings and prompt the user to turn Wi-
|
||||
All necessary Android permissions are already in the **AndroidManifest.xml** of the plugin,
|
||||
so you don't need to add anything **to work with p2p network**.
|
||||
|
||||
### IOS setup
|
||||
### IOS and macOS setup
|
||||
|
||||
For IOS, you need to add the following values to **Info.plist**:
|
||||
For IOS and macOS, you need to add the following values to **Info.plist**:
|
||||
|
||||
```
|
||||
<key>NSBonjourServices</key>
|
||||
@@ -161,11 +164,11 @@ For IOS, you need to add the following values to **Info.plist**:
|
||||
> final _nearbyService = NearbyService.getInstance();
|
||||
> _nearbyService.android..
|
||||
> ```
|
||||
> For IOS:
|
||||
> For IOS and macOS:
|
||||
>
|
||||
> ```dart
|
||||
> final _nearbyService = NearbyService.getInstance();
|
||||
> _nearbyService.ios..
|
||||
> _nearbyService.darwin..
|
||||
> ```
|
||||
|
||||
1. Import the package:
|
||||
@@ -185,9 +188,9 @@ final _nearbyService = NearbyService.getInstance();
|
||||
|
||||
```dart
|
||||
// You can change the device name on a P2P network only for iOS.
|
||||
// Optionally pass the [iosDeviceName].
|
||||
// Optionally pass the [darwinDeviceName].
|
||||
await _nearbyService.initialize(
|
||||
data: NearbyInitializeData(iosDeviceName: iosDeviceName),
|
||||
data: NearbyInitializeData(darwinDeviceName: darwinDeviceName),
|
||||
);
|
||||
```
|
||||
|
||||
@@ -207,9 +210,9 @@ if (isWifiEnabled ?? false) {
|
||||
}
|
||||
```
|
||||
|
||||
**Extra step for IOS:** ask the user to choose whether they are a Browser or Advertiser:
|
||||
**Extra step for IOS and macOS:** ask the user to choose whether they are a Browser or Advertiser:
|
||||
|
||||
> In IOS Multipeer Connectivity, there are 2 roles for the discovery process and connection between devices: **browser**
|
||||
> In IOS and macOS Multipeer Connectivity, there are 2 roles for the discovery process and connection between devices: **browser**
|
||||
> and **advertiser**.
|
||||
>
|
||||
> **Browser**: This component discovers nearby devices that report their availability. It is
|
||||
@@ -221,7 +224,7 @@ if (isWifiEnabled ?? false) {
|
||||
The code for selecting a role:
|
||||
|
||||
```dart
|
||||
_nearbyService.ios?.setIsBrowser(value: isBrowser);
|
||||
_nearbyService.darwin?.setIsBrowser(value: isBrowser);
|
||||
// go to the starting discovery step
|
||||
```
|
||||
|
||||
@@ -243,7 +246,7 @@ _nearbyService.getPeersStream().listen((event) => peers = event);
|
||||
6. Each of the peers is a `NearbyDevice` and you can connect to it:
|
||||
|
||||
> Remember that when used on the Android platform, you can only pass `NearbyAndroidDevice` to the `connect()` method.
|
||||
> Similarly for iOS, `NearbyIOSDevice`. Devices automatically come from the discovery state in the correct type, so you
|
||||
> Similarly for iOS and macOS, `NearbyDarwinDevice`. Devices automatically come from the discovery state in the correct type, so you
|
||||
> just need to use the received data.
|
||||
|
||||
```dart
|
||||
@@ -270,7 +273,7 @@ _connectedDeviceSubscription = _nearbyService.getConnectedDeviceStream(device).l
|
||||
```
|
||||
|
||||
8. Once you have connected over a P2P network, you still need to create a **communication channel** to transfer data.
|
||||
For Android, this is a **socket** embedded in `NearbyService`, for iOS it's a setup to listen to messages and
|
||||
For Android, this is a **socket** embedded in `NearbyService`, for iOS and macOS it's a setup to listen to messages and
|
||||
resources from the desired device. There is a method `startCommunicationChannel()` for this purpose. You should pass
|
||||
to it listeners for messages and resources received from the connected device. There can only be one communication
|
||||
channel, if you create a new one, the previous one will be **cancelled**.
|
||||
@@ -541,4 +544,63 @@ the Android platform
|
||||
|
||||
### IOS
|
||||
|
||||
|
||||
|
||||
|
||||
## Migration Guide
|
||||
|
||||
### Migrating from v0.1.0 to v0.2.0
|
||||
|
||||
Version 0.2.0 adds support for macOS but introduces breaking changes to accommodate the unified Darwin platform (iOS and macOS).
|
||||
|
||||
#### API Changes
|
||||
|
||||
1. **Property Renaming**
|
||||
- `.ios` property has been renamed to `.darwin`
|
||||
```dart
|
||||
// Before (v0.1.0)
|
||||
_nearbyService.ios?.setIsBrowser(value: isBrowser);
|
||||
|
||||
// After (v0.2.0)
|
||||
_nearbyService.darwin?.setIsBrowser(value: isBrowser);
|
||||
```
|
||||
|
||||
2. **Class Renaming**
|
||||
- `NearbyIOSDevice` has been renamed to `NearbyDarwinDevice`
|
||||
- `NearbyIOSService` has been renamed to `NearbyDarwinService`
|
||||
- `NearbyServiceIOSExceptionMapper` has been renamed to `NearbyServiceDarwinExceptionMapper`
|
||||
|
||||
3. **Parameter Renaming in NearbyInitializeData**
|
||||
- `iosDeviceName` has been renamed to `darwinDeviceName`
|
||||
```dart
|
||||
// Before (v0.1.0)
|
||||
await _nearbyService.initialize(
|
||||
data: NearbyInitializeData(iosDeviceName: deviceName),
|
||||
);
|
||||
|
||||
// After (v0.2.0)
|
||||
await _nearbyService.initialize(
|
||||
data: NearbyInitializeData(darwinDeviceName: deviceName),
|
||||
);
|
||||
```
|
||||
|
||||
#### Assert Statements
|
||||
|
||||
If you have assertions in your code that check for specific types, make sure to update them:
|
||||
|
||||
```dart
|
||||
// Before (v0.1.0)
|
||||
assert(
|
||||
device is NearbyIOSDevice,
|
||||
'The Nearby IOS Service can only work with the NearbyIOSDevice'
|
||||
);
|
||||
|
||||
// After (v0.2.0)
|
||||
assert(
|
||||
device is NearbyDarwinDevice,
|
||||
'The Nearby Darwin Service can only work with the NearbyDarwinDevice'
|
||||
);
|
||||
```
|
||||
|
||||
#### Flutter Configuration
|
||||
|
||||
If you're developing a plugin based on `nearby_service`, note that the `pubspec.yaml` now uses `sharedDarwinSource: true` to share code between iOS and macOS platforms.
|
||||
Reference in New Issue
Block a user