Skip to content

docs: improved over-all documentation #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
OutdatedGuy merged 3 commits into from
Sep 24, 2025
Merged

docs: improved over-all documentation #96

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
796d01f
docs: improved over-all documentation
OutdatedGuy May 8, 2025
d09be01
docs: made URI links clickable
OutdatedGuy May 8, 2025
bfecd0b
feat: add customizable connectivity check logic to features list
OutdatedGuy Sep 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
168 changes: 77 additions & 91 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,46 +3,47 @@
A Flutter package to check your internet connection with subsecond response
times, even on mobile networks!

[![pub package][package_svg]][package]
[![GitHub][license_svg]](LICENSE)
[![pub package][package_svg]][package] [![GitHub][license_svg]](LICENSE)

[![GitHub issues][issues_svg]][issues]
[![GitHub issues closed][issues_closed_svg]][issues_closed]

<hr />

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

## Features

- Check internet connectivity status
- Listen for internet connectivity changes
- ✅ Check internet connectivity status
- ✅ Listen to internet connectivity changes
- ✅ Customizable endpoints and success criteria
- ✅ Customizable connectivity check logic

## Supported Platforms

| Features | Android | iOS | macOS | Linux | Windows | Web |
| :----------------: | :-----: | :-: | :---: | :---: | :-----: | :-: |
| Check Connectivity | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Listen for Changes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Listen to Changes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |

## Permissions

### Android

Add the following permissions to your `AndroidManifest.xml` file:
Add the following permission to your `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
```

### macOS

Add the following permissions to your macOS `.entitlements` files:
Add the following to your macOS `.entitlements` files:

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

## Usage

### 1. Add dependency

Add the `internet_connection_checker_plus` package to your `pubspec.yaml` file:

```yaml
dependencies:
internet_connection_checker_plus: ^2.8.0
```
### Checking for internet connectivity (one-time)

### 2. Import the package

Import the `internet_connection_checker_plus` package into your Dart file:
The simplest way to check if you have internet access:

```dart
import 'package:internet_connection_checker_plus/internet_connection_checker_plus.dart';
```

### 3. Checking for internet connectivity

The simplest way to check for internet connectivity is to use the
`InternetConnection` class:

```dart
bool result = await InternetConnection().hasInternetAccess;
final bool isConnected = await InternetConnection().hasInternetAccess;
if (isConnected) {
print('Connected!');
} else {
print('No internet connection.');
}
```

### 4. Listening for internet connectivity changes
### Listening to internet connectivity changes

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

```dart
final listener = InternetConnection().onStatusChange.listen((InternetStatus status) {
switch (status) {
case InternetStatus.connected:
// The internet is now connected
break;
case InternetStatus.disconnected:
// The internet is now disconnected
break;
}
});
final subscription = InternetConnection().onStatusChange.listen(
(InternetStatus status) {
if (status == InternetStatus.connected) {
// Internet is connected
} else {
// Internet is disconnected
}
},
);
```

Don't forget to cancel the subscription when it is no longer needed.
This will prevent memory leaks and free up resources:

```dart
listener.cancel();
```
> [!NOTE]
>
> Don't forget to cancel the subscription when it is no longer needed. This will
> prevent memory leaks and free up resources:
>
> ```dart
> @override
> void dispose() {
> subscription.cancel();
> super.dispose();
> }
> ```

### 5. Add custom `Uri`s to check
### Using custom endpoints (URIs)

The `InternetConnection` class can be configured to check custom `Uri`s for
internet connectivity:
You can specify your own endpoints to check for connectivity:

```dart
final connection = InternetConnection.createInstance(
customCheckOptions: [
InternetCheckOption(uri: Uri.parse('https://example.com')),
],
);
final isConnected = await connection.hasInternetAccess;
```

> [!IMPORTANT]
>
> Make sure the custom `Uri`s have no caching enabled. Otherwise, the results
> may be inaccurate.

> [!IMPORTANT]
>
> On `web` platform, make sure the custom `Uri`s are not CORS blocked.
> Otherwise, the results may be inaccurate.
> - Make sure the endpoints have no caching enabled.
> - On `web` platform, make sure the endpoints are not CORS blocked.

### 6. Add custom success criteria
### Using custom success criteria

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

```dart
final connection = InternetConnection.createInstance(
Expand All @@ -141,15 +128,14 @@ final connection = InternetConnection.createInstance(
),
InternetCheckOption(
uri: Uri.parse('https://example2.com'),
responseStatusFn: (response) {
return response.statusCode >= 420 && response.statusCode < 1412;
},
responseStatusFn: (response) => response.statusCode == 420,
),
],
);
final isConnected = await connection.hasInternetAccess;
```

### 7. Using a custom connectivity check method
### Using a custom connectivity check method

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

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

### 8. Pause and Resume on App Lifecycle Changes
### Pause and Resume on App Lifecycle Changes

For situation where you want to pause any network requests when the app goes
into the background and resume them when the app comes back into the foreground
Expand Down Expand Up @@ -255,42 +241,42 @@ final connection = InternetConnection.createInstance(

## Built-in and Additional URIs

### Default `Uri`s
### Default URIs

The `InternetConnection` class uses the following `Uri`s by default:
The following endpoints are checked by default:

| URI | Description |
| :--------------------------------------------- | :--------------------------------------------------------- |
| `https://one.one.one.one` | Response time is less than `100ms`, CORS enabled, no-cache |
| `https://icanhazip.com` | Response time is less than `100ms`, CORS enabled, no-cache |
| `https://jsonplaceholder.typicode.com/todos/1` | Response time is less than `100ms`, CORS enabled, no-cache |
| `https://pokeapi.co/api/v2/ability/?limit=1` | Response time is less than `100ms`, CORS enabled, no-cache |
| URI | Description |
| :------------------------------------------- | :--------------------------------------------------------- |
| https://one.one.one.one | Response time is less than `100ms`, CORS enabled, no-cache |
| https://icanhazip.com | Response time is less than `100ms`, CORS enabled, no-cache |
| https://jsonplaceholder.typicode.com/todos/1 | Response time is less than `100ms`, CORS enabled, no-cache |
| https://pokeapi.co/api/v2/ability/?limit=1 | Response time is less than `100ms`, CORS enabled, no-cache |

### Some Tested URIs
### More Tested URIs

The following `Uri`s are tested and work well with the package:
The following URIs are tested and work well with the package:

| URI | Description |
| :------------------------------------------- | :--------------------------------------- |
| `https://ipapi.co/ip` | CORS enabled, no-cache |
| `https://api.adviceslip.com/advice` | CORS enabled, no-cache |
| `https://api.bitbucket.org/2.0/repositories` | CORS enabled, no-cache |
| `https://api.thecatapi.com/v1/images/search` | CORS enabled, no-cache |
| `https://randomuser.me/api/?inc=gender` | CORS enabled, no-cache |
| `https://dog.ceo/api/breed/husky/list` | CORS enabled, no-cache |
| `https://lenta.ru` | Russia supported, CORS enabled, no-cache |
| `https://www.gazeta.ru` | Russia supported, CORS enabled, no-cache |
| URI | Description |
| :----------------------------------------- | :--------------------------------------- |
| https://ipapi.co/ip | CORS enabled, no-cache |
| https://api.adviceslip.com/advice | CORS enabled, no-cache |
| https://api.bitbucket.org/2.0/repositories | CORS enabled, no-cache |
| https://api.thecatapi.com/v1/images/search | CORS enabled, no-cache |
| https://randomuser.me/api/?inc=gender | CORS enabled, no-cache |
| https://dog.ceo/api/breed/husky/list | CORS enabled, no-cache |
| https://lenta.ru | Russia supported, CORS enabled, no-cache |
| https://www.gazeta.ru | Russia supported, CORS enabled, no-cache |

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

## Credits

This package is a cloned and modified version of the
[internet_connection_checker] package which is a cloned and modified version of
the [data_connection_checker] package which is no longer maintained.
[internet_connection_checker] package, which itself was based on
[data_connection_checker] (now unmaintained).

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

<!-- Badges URLs -->

Expand Down