Home

Awesome

Hyperconnectivity

Build Status Version Carthage compatible License Twitter

Hyperconnectivity is a modern replacement for Reachability written fully in Swift and using Apple's Combine framework. It offers the ability to detect reachability, Internet connectivity as well the presence of captive portals. It is an offshoot of the Connectivity project which offers similar features. To find out which one is right for you, take a look at the Connectivity vs Hyperconnectivity section below for a comparison.

Features

Quickstart

Getting started is as simple as subscribing to the provided publisher as follows:

cancellable = Hyperconnectivity.Publisher()
	.receive(on: DispatchQueue.main)
	.eraseToAnyPublisher()
	.sink(receiveCompletion: { [weak self] _ in
		self?.updateUIWhenComplete()
	}, receiveValue: { [weak self] connectivityResult in
		self?.updateUI(with: connectivityResult)
	})

For a full example, see the example UIViewController in the sample app.

Connectivity vs Hyperconnectivity

Hyperconnectivity is an offshoot of the Connectivity framework so why would you choose Hyperconnectivity over Connectivity?

TL;DR

With iOS 14 just around the corner, Hyperconnectivity drops the Objective-C interoperability and support for older versions of iOS provided by Connectivity in order to provide a cleaner, more elegant interface in Swift for those apps who need only support iOS 13 an above.

Connectivity was designed to provide a familiar API to users of Apple's Reachability which was written in Obj-C and whose designed was heavily influenced by that language. With many recent advancements in the Swift language and introduction of the Network and Combine frameworks in iOS 12 and 13 respectively it felt as though there was an opportunity to provide a 'Swiftier' and more reactive interface at the cost of sacrificing Obj-C compatibility and support for older versions of iOS.

Feature Comparison

The table below will be updated as future releases of Hyperconnectivity bring the framework towards feature parity with Connectivity.

<div align="center"> <img src="https://github.com/rwbutler/Hyperconnectivity/raw/main/docs/images/comparison-with-connectivity.png" alt="Comparison with Connectivity Table" width="80%"> </div>

Installation

Hyperconnectivity is compatible with Cocoapods, Carthage and Swift Package Manager. For installation instructions take a look at the relevant section below.

Cocoapods

CocoaPods is a dependency manager which integrates dependencies into your Xcode workspace. To install it using Ruby gems run:

gem install cocoapods

To install Hyperconnectivity using Cocoapods, simply add the following line to your Podfile:

pod "Hyperconnectivity"

Then run the command:

pod install

For more information see here.

Carthage

Carthage is a dependency manager which produces a binary for manual integration into your project. It can be installed via Homebrew using the commands:

brew update
brew install carthage

In order to integrate Hyperconnectivity into your project via Carthage, add the following line to your project's Cartfile:

github "rwbutler/Hyperconnectivity"

From the macOS Terminal run carthage update --platform iOS to build the framework then drag Hyperconnectivity.framework into your Xcode project.

For more information see here.

Swift Package Manager

Xcode 11 includes support for Swift Package Manager. In order to add Hyperconnectivity to your project in Xcode 11, from the File menu select Swift Packages and then select Add Package Dependency.

A dialogue will request the package repository URL which is:

https://github.com/rwbutler/hyperconnectivity

After verifying the URL, Xcode will prompt you to select whether to pull a specific branch, commit or versioned release into your project.

<div align="center"> <img src="https://github.com/rwbutler/Connectivity/raw/master/docs/images/package-options.png" alt="Xcode 11 Package Options" width="80%"> </div>

Proceed to the next step by where you will be asked to select the package product to integrate into a target. There will be a single package product named Hyperconnectivity which should be pre-selected. Ensure that your main app target is selected from the rightmost column of the dialog then click Finish to complete the integration.

<div align="center"> <img src="https://github.com/rwbutler/Connectivity/raw/master/docs/images/add-package.png" alt="Xcode 11 Add Package" width="80%"> </div>

How It Works

iOS adopts a protocol called Wireless Internet Service Provider roaming (WISPr 2.0) published by the Wireless Broadband Alliance. This protocol defines the Smart Client to Access Gateway interface describing how to authenticate users accessing public IEEE 802.11 (Wi-Fi) networks using the Universal Access Method in which a captive portal presents a login page to the user.

The user must then register or provide login credentials via a web browser in order to be granted access to the network using RADIUS or another protocol providing centralized Authentication, Authorization, and Accounting (AAA).

In order to detect a that it has connected to a Wi-Fi network with a captive portal, iOS contacts a number of endpoints hosted by Apple - an example being https://www.apple.com/library/test/success.html. Each endpoint hosts a small HTML page of the form:


<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
	<TITLE>Success</TITLE>
</HEAD>
<BODY>
	Success
</BODY>
</HTML>

If on downloading this small HTML page iOS finds that it contains the word Success as above then it knows that Internet connectivity is available. However, if a login page is presented by a captive portal then the word Success will not be present and iOS will realize that the network connection has been hijacked by a captive portal and will present a browser window allowing the user to login or register.

Apple hosts a number of these pages such that should one of these pages go down, a number of fallbacks can be checked to determine whether connectivity is present or whether our connection is blocked by the presence of a captive portal. Unfortunately iOS exposes no framework to developers which allows us to make use of the operating system’s awareness of captive portals.

Hyperconnectivity is an open-source framework which endeavours to replicate iOS’s means of detecting captive portals. When NWPathMonitor detects Wi-Fi or WWAN connectivity, Hyperconnectivity contacts a number of endpoints to determine whether true Internet connectivity is present or whether a captive portal is intercepting the connections. This approach can also be used to determine whether an iOS device is connected to a Wi-Fi router with no Internet access.

Hyperconnectivity provides a Combine Publisher for providing notifications of changing Internet connectivity state therefore getting up to speed with the framework should be straightforward for anyone with prior experience of working with Combine publishers.

By default, Hyperconnectivity contacts a number of endpoints already used by iOS but it is recommended that these are replaced by endpoints hosted by the developer by setting the connectivityURLs property of the Hyperconnectivity.Configuration object. Further customization is possible through setting the successThreshold property of this object which determines the percentage of endpoints contacted which must result in a successful check in order to conclude that connectivity is present. The default value specifies that 50% of URLs contacted must result in a successful connectivity check.

Usage

For an example of how to use Hyperconnectivity, see the sample app in the Example directory. The provided example UIViewController illustrates how the publisher can be used to update your UI.

FAQs

Does the release of Hyperconnectivity mean that Connectivity will no longer be supported going forwards?

No, both Connectivity and Hyperconnectivity will be supported in future with improvements in each framework being symbiotic leading to improvement in the other.

Known Issues

Caller responsible for retaining the AnyCancellable object

Please ensure that any implementation making use of this framework holds a strong reference to the AnyCancellable object returned when subscribing to the publisher. If this object is not retained then any Internet connectivity checks will be cancelled prematurely.

Simulator issues

Before reporting a bug please ensure that you have tested on a physical device as on simulator changes in network adapter state are not reported correctly by iOS frameworks particularly when transitioning from a disconnected -> connected state. This behaviour functions correctly on a physical device.

Author

Ross Butler

License

Hyperconnectivity is available under the MIT license. See the LICENSE file for more info.

Additional Software

Controls

AnimatedGradientView
AnimatedGradientView

Frameworks

CheatsConnectivityFeatureFlagsHyperconnectivitySkylarkTypographyKitUpdates
CheatsConnectivityFeatureFlagsHyperconnectivitySkylarkTypographyKitUpdates

Tools

Config ValidatorIPA UploaderPalette
Config ValidatorIPA UploaderPalette