Skip to content

Commit 205cd9a

Browse files
OutdatedGuyOutdatedGuy
authored
docs: improved over-all documentation (#96)
* docs: improved over-all documentation * docs: made URI links clickable * feat: add customizable connectivity check logic to features list
1 parent d451fea commit 205cd9a

File tree

1 file changed

+77
-91
lines changed

1 file changed

+77
-91
lines changed

‎README.md‎

Lines changed: 77 additions & 91 deletions
Original file line numberDiff line numberDiff line change
@@ -3,46 +3,47 @@
33
A Flutter package to check your internet connection with subsecond response
44
times, even on mobile networks!
55

6-
[![pub package][package_svg]][package]
7-
[![GitHub][license_svg]](LICENSE)
6+
[![pub package][package_svg]][package] [![GitHub][license_svg]](LICENSE)
87

98
[![GitHub issues][issues_svg]][issues]
109
[![GitHub issues closed][issues_closed_svg]][issues_closed]
1110

1211
<hr />
1312

1413
This library provides functionality to monitor and verify internet connectivity
15-
by checking reachability to various `Uri`s. It relies on the `connectivity_plus`
14+
by checking reachability to various URIs. It relies on the `connectivity_plus`
1615
package for listening to connectivity changes and the `http` package for making
1716
network requests.
1817

1918
## Features
2019

21-
- Check internet connectivity status
22-
- Listen for internet connectivity changes
20+
- ✅ Check internet connectivity status
21+
- ✅ Listen to internet connectivity changes
22+
- ✅ Customizable endpoints and success criteria
23+
- ✅ Customizable connectivity check logic
2324

2425
## Supported Platforms
2526

2627
| Features | Android | iOS | macOS | Linux | Windows | Web |
2728
| :----------------: | :-----: | :-: | :---: | :---: | :-----: | :-: |
2829
| Check Connectivity | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
29-
| Listen for Changes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
30+
| Listen to Changes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
3031

3132
## Permissions
3233

3334
### Android
3435

35-
Add the following permissions to your `AndroidManifest.xml` file:
36+
Add the following permission to your `AndroidManifest.xml`:
3637

3738
```xml
3839
<uses-permission android:name="android.permission.INTERNET" />
3940
```
4041

4142
### macOS
4243

43-
Add the following permissions to your macOS `.entitlements` files:
44+
Add the following to your macOS `.entitlements` files:
4445

45-
```entitlements
46+
```xml
4647
<key>com.apple.security.network.client</key>
4748
<true/>
4849
```
@@ -51,84 +52,70 @@ For more information, see the [Flutter Networking Documentation].
5152

5253
## Usage
5354

54-
### 1. Add dependency
55-
56-
Add the `internet_connection_checker_plus` package to your `pubspec.yaml` file:
57-
58-
```yaml
59-
dependencies:
60-
internet_connection_checker_plus: ^2.8.0
61-
```
55+
### Checking for internet connectivity (one-time)
6256

63-
### 2. Import the package
64-
65-
Import the `internet_connection_checker_plus` package into your Dart file:
57+
The simplest way to check if you have internet access:
6658

6759
```dart
68-
import 'package:internet_connection_checker_plus/internet_connection_checker_plus.dart';
69-
```
70-
71-
### 3. Checking for internet connectivity
72-
73-
The simplest way to check for internet connectivity is to use the
74-
`InternetConnection` class:
75-
76-
```dart
77-
bool result = await InternetConnection().hasInternetAccess;
60+
final bool isConnected = await InternetConnection().hasInternetAccess;
61+
if (isConnected) {
62+
print('Connected!');
63+
} else {
64+
print('No internet connection.');
65+
}
7866
```
7967

80-
### 4. Listening for internet connectivity changes
68+
### Listening to internet connectivity changes
8169

82-
The `InternetConnection` class also provides a stream of `InternetStatus` that
83-
can be used to listen for changes in internet connectivity:
70+
The `InternetConnection` class exposes a stream of `InternetStatus` updates,
71+
allowing you to react to changes in connectivity:
8472

8573
```dart
86-
final listener = InternetConnection().onStatusChange.listen((InternetStatus status) {
87-
switch (status) {
88-
case InternetStatus.connected:
89-
// The internet is now connected
90-
break;
91-
case InternetStatus.disconnected:
92-
// The internet is now disconnected
93-
break;
94-
}
95-
});
74+
final subscription = InternetConnection().onStatusChange.listen(
75+
(InternetStatus status) {
76+
if (status == InternetStatus.connected) {
77+
// Internet is connected
78+
} else {
79+
// Internet is disconnected
80+
}
81+
},
82+
);
9683
```
9784

98-
Don't forget to cancel the subscription when it is no longer needed.
99-
This will prevent memory leaks and free up resources:
100-
101-
```dart
102-
listener.cancel();
103-
```
85+
> [!NOTE]
86+
>
87+
> Don't forget to cancel the subscription when it is no longer needed. This will
88+
> prevent memory leaks and free up resources:
89+
>
90+
> ```dart
91+
> @override
92+
> void dispose() {
93+
> subscription.cancel();
94+
> super.dispose();
95+
> }
96+
> ```
10497
105-
### 5. Add custom `Uri`s to check
98+
### Using custom endpoints (URIs)
10699
107-
The `InternetConnection` class can be configured to check custom `Uri`s for
108-
internet connectivity:
100+
You can specify your own endpoints to check for connectivity:
109101
110102
```dart
111103
final connection = InternetConnection.createInstance(
112104
customCheckOptions: [
113105
InternetCheckOption(uri: Uri.parse('https://example.com')),
114106
],
115107
);
108+
final isConnected = await connection.hasInternetAccess;
116109
```
117110
118111
> [!IMPORTANT]
119112
>
120-
> Make sure the custom `Uri`s have no caching enabled. Otherwise, the results
121-
> may be inaccurate.
122-
123-
> [!IMPORTANT]
124-
>
125-
> On `web` platform, make sure the custom `Uri`s are not CORS blocked.
126-
> Otherwise, the results may be inaccurate.
113+
> - Make sure the endpoints have no caching enabled.
114+
> - On `web` platform, make sure the endpoints are not CORS blocked.
127115
128-
### 6. Add custom success criteria
116+
### Using custom success criteria
129117

130-
The `InternetConnection` class can be configured to check custom `Uri`s for
131-
internet connectivity using custom success criteria:
118+
You can define what counts as a successful response:
132119

133120
```dart
134121
final connection = InternetConnection.createInstance(
@@ -141,15 +128,14 @@ final connection = InternetConnection.createInstance(
141128
),
142129
InternetCheckOption(
143130
uri: Uri.parse('https://example2.com'),
144-
responseStatusFn: (response) {
145-
return response.statusCode >= 420 && response.statusCode < 1412;
146-
},
131+
responseStatusFn: (response) => response.statusCode == 420,
147132
),
148133
],
149134
);
135+
final isConnected = await connection.hasInternetAccess;
150136
```
151137

152-
### 7. Using a custom connectivity check method
138+
### Using a custom connectivity check method
153139

154140
For advanced use cases, you can completely customize how connectivity checks are performed by providing your own connectivity checker:
155141

@@ -183,7 +169,7 @@ This customization gives you full control over the connectivity detection proces
183169
- Add detailed logging or metrics for connectivity checks
184170
- Integrate with other network monitoring tools
185171

186-
### 8. Pause and Resume on App Lifecycle Changes
172+
### Pause and Resume on App Lifecycle Changes
187173

188174
For situation where you want to pause any network requests when the app goes
189175
into the background and resume them when the app comes back into the foreground
@@ -255,42 +241,42 @@ final connection = InternetConnection.createInstance(
255241
256242
## Built-in and Additional URIs
257243

258-
### Default `Uri`s
244+
### Default URIs
259245

260-
The `InternetConnection` class uses the following `Uri`s by default:
246+
The following endpoints are checked by default:
261247

262-
| URI | Description |
263-
| :--------------------------------------------- | :--------------------------------------------------------- |
264-
| `https://one.one.one.one` | Response time is less than `100ms`, CORS enabled, no-cache |
265-
| `https://icanhazip.com` | Response time is less than `100ms`, CORS enabled, no-cache |
266-
| `https://jsonplaceholder.typicode.com/todos/1` | Response time is less than `100ms`, CORS enabled, no-cache |
267-
| `https://pokeapi.co/api/v2/ability/?limit=1` | Response time is less than `100ms`, CORS enabled, no-cache |
248+
| URI | Description |
249+
| :------------------------------------------- | :--------------------------------------------------------- |
250+
| https://one.one.one.one | Response time is less than `100ms`, CORS enabled, no-cache |
251+
| https://icanhazip.com | Response time is less than `100ms`, CORS enabled, no-cache |
252+
| https://jsonplaceholder.typicode.com/todos/1 | Response time is less than `100ms`, CORS enabled, no-cache |
253+
| https://pokeapi.co/api/v2/ability/?limit=1 | Response time is less than `100ms`, CORS enabled, no-cache |
268254

269-
### Some Tested URIs
255+
### More Tested URIs
270256

271-
The following `Uri`s are tested and work well with the package:
257+
The following URIs are tested and work well with the package:
272258

273-
| URI | Description |
274-
| :------------------------------------------- | :--------------------------------------- |
275-
| `https://ipapi.co/ip` | CORS enabled, no-cache |
276-
| `https://api.adviceslip.com/advice` | CORS enabled, no-cache |
277-
| `https://api.bitbucket.org/2.0/repositories` | CORS enabled, no-cache |
278-
| `https://api.thecatapi.com/v1/images/search` | CORS enabled, no-cache |
279-
| `https://randomuser.me/api/?inc=gender` | CORS enabled, no-cache |
280-
| `https://dog.ceo/api/breed/husky/list` | CORS enabled, no-cache |
281-
| `https://lenta.ru` | Russia supported, CORS enabled, no-cache |
282-
| `https://www.gazeta.ru` | Russia supported, CORS enabled, no-cache |
259+
| URI | Description |
260+
| :----------------------------------------- | :--------------------------------------- |
261+
| https://ipapi.co/ip | CORS enabled, no-cache |
262+
| https://api.adviceslip.com/advice | CORS enabled, no-cache |
263+
| https://api.bitbucket.org/2.0/repositories | CORS enabled, no-cache |
264+
| https://api.thecatapi.com/v1/images/search | CORS enabled, no-cache |
265+
| https://randomuser.me/api/?inc=gender | CORS enabled, no-cache |
266+
| https://dog.ceo/api/breed/husky/list | CORS enabled, no-cache |
267+
| https://lenta.ru | Russia supported, CORS enabled, no-cache |
268+
| https://www.gazeta.ru | Russia supported, CORS enabled, no-cache |
283269

284270
## If you liked the package, then please give it a [Like 👍🏼][package] and [Star ⭐][repository]
285271

286272
## Credits
287273

288274
This package is a cloned and modified version of the
289-
[internet_connection_checker] package which is a cloned and modified version of
290-
the [data_connection_checker] package which is no longer maintained.
275+
[internet_connection_checker] package, which itself was based on
276+
[data_connection_checker] (now unmaintained).
291277

292-
The aim of this package is to support the `web` platform which is currently not
293-
supported by the [internet_connection_checker] package.
278+
The main goal of this package is to provide a more reliable and faster solution
279+
for checking internet connectivity in Flutter applications.
294280

295281
<!-- Badges URLs -->
296282

0 commit comments

Comments
 (0)