@wniu/react-native-local-network-permission 0.1.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +39 -99
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,26 +1,16 @@
1
- # react-native-local-network-permission
1
+ # @wniu/react-native-local-network-permission
2
2
 
3
3
  A React Native library for handling **iOS Local Network permission**, built on TurboModule architecture.
4
4
 
5
- > **This is a React Native library, not an Expo-only module.** It works in bare React Native projects and can also be used in Expo projects via prebuild (`npx expo prebuild`).
6
-
7
5
  ## Installation
8
6
 
9
7
  ```sh
10
- npm install react-native-local-network-permission
11
- # or
12
- yarn add react-native-local-network-permission
13
- ```
14
-
15
- ### iOS Setup
16
-
17
- ```sh
18
- cd ios && pod install
8
+ npm install @wniu/react-native-local-network-permission
19
9
  ```
20
10
 
21
- #### Required Info.plist Configuration
11
+ ### Configure Info.plist
22
12
 
23
- You **must** add the following keys to your `ios/<YourApp>/Info.plist`:
13
+ Add the following to your `ios/<YourApp>/Info.plist`:
24
14
 
25
15
  ```xml
26
16
  <key>NSLocalNetworkUsageDescription</key>
@@ -28,120 +18,70 @@ You **must** add the following keys to your `ios/<YourApp>/Info.plist`:
28
18
 
29
19
  <key>NSBonjourServices</key>
30
20
  <array>
31
- <string>_lnp_check._tcp</string>
21
+ <string>_preflight_check._tcp</string>
32
22
  </array>
33
23
  ```
34
24
 
35
- - **`NSLocalNetworkUsageDescription`**: The message shown to the user in the permission dialog. Customize this to explain why your app needs local network access.
36
- - **`NSBonjourServices`**: Must include `_lnp_check._tcp` — this is the Bonjour service type used internally by this library to detect permission status.
37
-
38
- > If your app also browses for other Bonjour services, add those to the array as well.
25
+ - **`NSLocalNetworkUsageDescription`**: The message shown in the permission dialog. Customize it for your app.
26
+ - **`NSBonjourServices`**: Must include `_preflight_check._tcp` — the Bonjour service used internally by this library.
39
27
 
40
28
  ### Expo Setup
41
29
 
42
- This library is **not** an Expo Module — it uses React Native TurboModule architecture. To use it in an Expo managed project:
30
+ This library uses React Native TurboModule architecture. To use it in an Expo project:
43
31
 
44
- 1. Install the library as above.
32
+ 1. Install the library.
45
33
  2. Run `npx expo prebuild` to generate native projects.
46
- 3. Add the Info.plist keys manually, or create a [config plugin](https://docs.expo.dev/guides/config-plugins/) to automate it.
47
-
48
- The library is fully compatible with Expo projects that use prebuild (Continuous Native Generation).
49
-
50
- ## Usage
51
-
52
- ```ts
53
- import {
54
- requestPermission,
55
- isAvailable,
56
- } from 'react-native-local-network-permission';
57
-
58
- // Request / check permission (may show system dialog on first call)
59
- const { status, granted, canAskAgain } = await requestPermission();
60
-
61
- // Check if local network permission is available on this platform
62
- const available = await isAvailable(); // true on iOS 14+, false on Android
63
- ```
64
-
65
- ## API Reference
66
-
67
- ### `requestPermission()`
68
-
69
- ```ts
70
- requestPermission(): Promise<LocalNetworkPermissionResponse>
71
- ```
72
-
73
- Requests local network permission. On iOS, this triggers a detection mechanism that:
74
- - Shows the system permission dialog if the user has not yet made a choice.
75
- - Returns the current status without a dialog if already granted or denied.
76
-
77
- On Android, always returns `{ status: 'granted', granted: true, canAskAgain: false }` since Android does not restrict local network access.
78
-
79
- #### Why only one method instead of separate "get" and "request"?
80
-
81
- Apple provides **no API to silently query** local network permission status. Any detection attempt is itself a local network operation that may trigger the system dialog. Providing separate `getPermission()` and `requestPermission()` methods would be misleading — they would do exactly the same thing.
82
-
83
- ### `isAvailable()`
84
-
85
- ```ts
86
- isAvailable(): Promise<boolean>
34
+ 3. Add the Info.plist keys via `app.json`:
35
+
36
+ ```json
37
+ {
38
+ "expo": {
39
+ "ios": {
40
+ "infoPlist": {
41
+ "NSLocalNetworkUsageDescription": "This app needs local network access to detect nearby devices.",
42
+ "NSBonjourServices": ["_preflight_check._tcp"]
43
+ }
44
+ }
45
+ }
46
+ }
87
47
  ```
88
48
 
89
- Returns `true` on iOS 14+, `false` on Android and older iOS versions.
90
-
91
- ### Types
49
+ ## Usage
92
50
 
93
51
  ```ts
94
- type PermissionStatus = 'granted' | 'denied';
52
+ import { requestPermission } from '@wniu/react-native-local-network-permission';
95
53
 
96
- type LocalNetworkPermissionResponse = {
97
- status: PermissionStatus;
98
- granted: boolean; // true when status === 'granted'
99
- canAskAgain: boolean; // false — iOS only shows the dialog once
100
- };
54
+ const granted = await requestPermission();
55
+ // true = granted, false = denied
101
56
  ```
102
57
 
103
- ## How It Works
58
+ ## API
104
59
 
105
- ### The iOS Local Network Permission Challenge
60
+ ### `requestPermission(): Promise<boolean>`
106
61
 
107
- Unlike Camera, Location, or Microphone permissions, **Apple does not provide any public API** to directly query or request local network permission. There is no equivalent of `AVCaptureDevice.authorizationStatus` for local network access. This is true across all iOS versions including iOS 18.
62
+ Requests local network permission.
108
63
 
109
- ### Detection Mechanism
64
+ - **iOS 14+**: Triggers the NWBrowser/NWListener detection. Shows the system dialog on first call; returns current status on subsequent calls.
65
+ - **Android / other platforms**: Always returns `true` (local network access is unrestricted).
110
66
 
111
- This library uses the widely-adopted **NWBrowser/NWListener self-discovery technique**:
67
+ Returns `true` if granted, `false` if denied.
112
68
 
113
- 1. A Bonjour `NWListener` is started on the device, advertising a custom service (`_lnp_check._tcp`).
114
- 2. A `NWBrowser` is started to search for that same service.
115
- 3. **If permission is granted:** The browser discovers the listener -> returns `"granted"`.
116
- 4. **If permission is denied:** The browser receives a DNS policy error -> returns `"denied"`.
117
- 5. **If permission is undetermined:** The system shows the permission dialog, then the result is determined.
118
-
119
- ### Limitations
120
-
121
- - **No silent query**: `requestPermission()` may trigger the system dialog on first call. This is an iOS platform limitation, not a library design choice.
122
- - **One-time dialog**: iOS shows the local network permission dialog only once. After the user makes a choice, they must go to **Settings > Privacy & Security > Local Network** to change it.
123
- - **`canAskAgain` is always `false`**: Since we cannot determine whether the dialog has been shown before, and it can only be shown once, this field is always `false`.
124
- - **iOS 14+ only**: Local network permission was introduced in iOS 14. On older versions, the library returns `"granted"` (unrestricted access).
125
- - **Android**: Local network access is not restricted on Android. `requestPermission()` returns granted, and `isAvailable()` returns `false`.
69
+ > **Why only one method?** Apple provides no API to silently query local network permission. Any detection attempt may trigger the system dialog, so separate "get" and "request" methods would be misleading.
126
70
 
127
71
  ## Platform Support
128
72
 
129
73
  | Platform | Supported | Notes |
130
74
  |----------|-----------|-------|
131
75
  | iOS 14+ | Yes | Full support via NWBrowser/NWListener |
132
- | iOS < 14 | Partial | Always returns granted (no restriction) |
133
- | Android | N/A | Returns granted; `isAvailable()` returns false |
76
+ | iOS < 14 | N/A | Always returns `true` (no restriction) |
77
+ | Android | N/A | Always returns `true` |
134
78
 
135
- ## Contributing
79
+ ## Limitations
136
80
 
137
- - [Development workflow](CONTRIBUTING.md#development-workflow)
138
- - [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
139
- - [Code of conduct](CODE_OF_CONDUCT.md)
81
+ - `requestPermission()` may show the system dialog on first call — this is an iOS limitation.
82
+ - iOS shows the dialog only once. Users must go to **Settings > Privacy & Security > Local Network** to change it.
83
+ - iOS 14+ only. Older versions return `true`.
140
84
 
141
85
  ## License
142
86
 
143
87
  MIT
144
-
145
- ---
146
-
147
- Made with [create-react-native-library](https://github.com/callstack/react-native-builder-bob)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@wniu/react-native-local-network-permission",
3
- "version": "0.1.0",
3
+ "version": "1.0.0",
4
4
  "description": "Handles iOS local network permission requests.",
5
5
  "main": "./lib/module/index.js",
6
6
  "types": "./lib/typescript/src/index.d.ts",