rwbutler/Hyperconnectivity

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
• Connectivity vs Hyperconnectivity
• Installation
  • Cocoapods
  • Carthage
  • Swift Package Manager
• How It Works
• Usage
• FAQs
• Known Issues
• Author
• License
• Additional Software
  • Frameworks
  • Tools

Features

• Determines whether Internet connectivity is available and provides notification of changes.
• Support for Combine Publishers.
• Detects Captive Portals when the device joins a network.
• Detects when connected to a hotspot or router without Internet access.

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.

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.

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.

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 - Powerful gradient animations made simple for iOS.

AnimatedGradientView

Frameworks

• Cheats - Retro cheat codes for modern iOS apps.
• Connectivity - Improves on Reachability for determining Internet connectivity in your iOS application.
• FeatureFlags - Allows developers to configure feature flags, run multiple A/B or MVT tests using a bundled / remotely-hosted JSON configuration file.
• FlexibleRowHeightGridLayout - A UICollectionView grid layout designed to support Dynamic Type by allowing the height of each row to size to fit content.
• Hyperconnectivity - Modern replacement for Apple's Reachability written in Swift and made elegant using Combine. An offshoot of the Connectivity framework.
• Skylark - Fully Swift BDD testing framework for writing Cucumber scenarios using Gherkin syntax.
• TailorSwift - A collection of useful Swift Core Library / Foundation framework extensions.
• TypographyKit - Consistent & accessible visual styling on iOS with Dynamic Type support.
• Updates - Automatically detects app updates and gently prompts users to update.

Cheats	Connectivity	FeatureFlags	Hyperconnectivity	Skylark	TypographyKit	Updates

Tools

• Clear DerivedData - Utility to quickly clear your DerivedData directory simply by typing cdd from the Terminal.
• Config Validator - Config Validator validates & uploads your configuration files and cache clears your CDN as part of your CI process.
• IPA Uploader - Uploads your apps to TestFlight & App Store.
• Palette - Makes your TypographyKit color palette available in Xcode Interface Builder.

Config Validator	IPA Uploader	Palette