AlamofireNetworkActivityIndicator

Controls the visibility of the network activity indicator on iOS using Alamofire.

Features

Automatic Management of Activity Indicator Visiblity
Delay Timers to Mitigate Flicker
Can Support NSURLSession Instances Not Managed by Alamofire
Comprehensive Test Coverage
Complete Documentation

Requirements

iOS 8.0+
Xcode 7.3+

Dependencies

Alamofire 3.3+

Communication

If you need help, use Stack Overflow. (Tag 'alamofire')
If you'd like to ask a general question, use Stack Overflow.
If you found a bug, open an issue.
If you have a feature request, open an issue.
If you want to contribute, submit a pull request.

Installation

CocoaPods

CocoaPods is a dependency manager for Cocoa projects. You can install it with the following command:

$ gem install cocoapods

CocoaPods 0.39.0+ is required.

To integrate AlamofireNetworkActivityIndicator into your Xcode project using CocoaPods, specify it in your Podfile:

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '8.0'
use_frameworks!

pod 'AlamofireNetworkActivityIndicator', '~> 1.0'

Then, run the following command:

$ pod install

Carthage

Carthage is a decentralized dependency manager that builds your dependencies and provides you with binary frameworks.

You can install Carthage with Homebrew using the following command:

$ brew update
$ brew install carthage

To integrate AlamofireNetworkActivityIndicator into your Xcode project using Carthage, specify it in your Cartfile:

github "Alamofire/AlamofireNetworkActivityIndicator" ~> 1.0

Usage

The NetworkActivityIndicatorManager manages the state of the network activity indicator. To begin using it, all that is required is to enable the sharedManager in application:didFinishLaunchingWithOptions: in your AppDelegate.

NetworkActivityIndicatorManager.sharedManager.isEnabled = true

By enabling the sharedManager for the system, the network activity indicator will show and hide automatically as Alamofire requests start and complete.

Notifications

The NetworkActivityIndicatorManager manages the currently active network request count by observing notifications emitted from Alamofire. By observing the task state changes, the sharedManager instance always knows how many requests are currently active and updates the visibility of the activity indicator accordingly.

It is possible to have the sharedManager observe NSURLSession instances not inside Alamofire. You will need to emit matching notifications from the NSURLSessionDelegate matching those found in Alamofire.

Delay Timers

In order to make the activity indicator experience for a user as pleasant as possible, there need to be start and stop delays added in to avoid flickering. There are two such delay timers built into the sharedManager.

Start Delay

The start delay is a time interval indicating the minimum duration of networking activity that should occur before the activity indicator is displayed. This helps avoid needlessly displaying the indicator for really fast network requests. The default value is 1.0 second. You can easily change the default value if needed.

NetworkActivityIndicatorManager.sharedManager.startDelay = 1.0

Completion Delay

The completion delay is a time interval indicating the duration of time that no networking activity should be observed before dismissing the activity indicator. This allows the activity indicator to be continuously displayed between multiple network requests. Without this delay, the activity indicator tends to flicker. The default value is 0.2 seconds. You can easily change the default value if needed.

NetworkActivityIndicatorManager.sharedManager.completionDelay = 0.2

FAQ

Why is this not in Alamofire?

In order to allow Alamofire to continue to be used in App Extensions, this logic could not be included in the Alamofire framework. In order to submit an App Extension to the App Store, it can only be linked against frameworks that specify they only use App Extension safe APIs. Since we want users to be able to use Alamofire in App Extensions, we MUST set the Require Only App Extension Safe APIs to true. Because of this, we cannot call non-safe App Extension APIs in the Alamofire framework. Controlling the activity indicator on iOS is done through non-safe App Extension APIs. Because of this, a separate library needed to be created.

But what about availability you say? Doesn't help in this case because availability checks still compile all the code. We could not use #if os(iOS) either because you cannot compile out logic specifically for iOS, but not for an iOS App Extension.

Credits

Alamofire is owned and maintained by the Alamofire Software Foundation. You can follow them on Twitter at @AlamofireSF for project updates and releases.

Donations

The ASF is looking to raise money to officially register as a federal non-profit organization. Registering will allow us members to gain some legal protections and also allow us to put donations to use, tax free. Donating to the ASF will enable us to:

Pay our legal fees to register as a federal non-profit organization
Pay our yearly legal fees to keep the non-profit in good status
Pay for our mail servers to help us stay on top of all questions and security issues
Potentially fund test servers to make it easier for us to test the edge cases
Potentially fund developers to work on one of our projects full-time

The community adoption of the ASF libraries has been amazing. We are greatly humbled by your enthusiam around the projects, and want to continue to do everything we can to move the needle forward. With your continued support, the ASF will be able to improve its reach and also provide better legal safety for the core members. If you use any of our libraries for work, see if your employers would be interested in donating. Our initial goal is to raise $1000 to get all our legal ducks in a row and kickstart this campaign. Any amount you can donate today to help us reach our goal would be greatly appreciated.

License

AlamofireNetworkActivityIndicator is released under the MIT license. See LICENSE for details.

joshpc/AlamofireNetworkActivityIndicator