Armchair: A simple yet powerful App Review Manager for iOS and OSX in Swift

Armchair is a simple yet powerful App Review Manager for iOS and OSX written in Swift. It is based on UAAppReviewManager and Appirater but completely rewritten for apps that want to benefit from the power of this new language.

Why Armchair?

The average end-user will only write a review if something is wrong with your App. This leads to an unfairly negative skew in the ratings, when the majority of satisfied customers don’t leave reviews and only the dissatisfied ones do. In order to counter-balance the negatives, Armchair prompts the user to write a review, but only after the developer knows they are satisfied. For example, you may only show the popup if the user has been using it for more than a week, and has done at least 5 significant events (the core functionality of your App). The rules are fully customizable for your App and easy to setup.

Here are just a few of the things that make Armchair better than the other rating frameworks and repos:

While the tests to prove it seem to be missing, Apple claims that Swift is a lot faster than Objective-C. Enjoy the benefits of using a framework built entirely in Swift, and work with a familiar syntax without having to deal with bridging headers or other Objective-C shenanigans.

Both iOS and OS X Support

Many developers publish apps for both iOS and OS X. Out of the box, Armchair supports iOS and OS X apps that are sold through the respective App Stores. The API is the same for both with the exception of a handful of iOS specific functions, described in Usage.

Fully Configurable at Runtime

Armchair is fully configurable, even at runtime. This means that the prompt you display can be dynamic, based on the end-user's score or status. The rules that govern how and when it should be shown can all be set the same way, allowing you to have the most control over the presentation and timing of your review prompt.

Default Localizations for Dozens of Languages

If you choose to use the default Armchair strings for your app, you will get the added benefit of localization in over 32 languages. Otherwise, customization is easy, and overriding the localization strings is a piece of cake, simply by including your own strings files and letting Armchair know.

Prevent Rating Prompts on Different Devices

If your users have the same app, same version installed on two different devices, you really shouldn't pop up the same rating prompt on each one. Armchair allows you to optionally keep your user's usage stats in the NSUbiquitousKeyValueStore, or any other store you want to keep track of syncing yourself to prevent dual prompts.

Uses UIApplication/NSApplication Lifecycle Notifications

Armchair listens for ApplicationDidLaunch and ApplicationWillEnterForeground notifications. This allows you to worry about your app, and not about tracking in your application delegate functions, so there are fewer lines of code for you to write.

Easy to Setup

It takes only 1 line of code to get started. Armchair is very powerful when digging under the hood, but also very simple to setup for standard configurations.

iTunes Affiliate Codes

If you are an iTunes Affiliate, you can easily setup Armchair to use your code and campaign. Full disclosure: If you aren't an iTunes Affiliate, the default code used in the app is the author's. It is better to have somebody's code rather than nobody's, so please leave it at the default setting if you aren't going to set one yourself. Think of it as a small token of appreciation for creating and open-sourcing Armchair.

Ready For Primetime

Armchair is clean code, well documented and well organized. It is easy to understand the logic flow and the purpose of each function. It doesn't mix logic up randomly between Class functions and Instance functions. Its API is clean and predictable.

<a name="the-golden-rule"> The Golden Rule </a>

Don't be a dick.

Seriously. It is easy to piss off your customers by not really considering how the prompting popup interrupts their flow. This was widely discussed in early 2014 by many well-known tech bloggers and caused a big hooplah in the community.

We think that having an app review prompt is fine, but only when presented at the right time, and only when you don't ask too frequently. The criteria for the smart display of a prompt varies for each app, but consider adding one at the end of a positive user workflow, rather than the beginning.

Tweak the variables so that you don't annoy your customers, and you will enjoy the maximum benefit from your app review prompting.

Screenshots

iOS Example Shots Mac Example Shots

Requirements

Xcode 6.1+
iOS 8.0+, Mac OS X 10.10+

Installation

Embedded frameworks require a minimum deployment target of iOS 8 or OS X Mavericks (10.9).

Armchair is no longer supported on iOS 7 due to the lack of support for frameworks. Without frameworks, running Travis-CI against iOS 7 would require a second duplicated test target. The separate test suite would need to import all the Swift files and the tests would need to be duplicated and re-written. This split would be too difficult to maintain to ensure the highest possible quality of the Armchair ecosystem.

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 build Armchair.

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

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

pod 'Armchair', '>= 0.3'

#Add the following in order to automatically set debug flags for armchair in debug builds
post_install do |installer|
      installer.pods_project.targets.each do |target|
          if target.name == 'Armchair'
              target.build_configurations.each do |config|
                  if config.name == 'Debug'
                      config.build_settings['OTHER_SWIFT_FLAGS'] = '-DDebug'
                      else
                      config.build_settings['OTHER_SWIFT_FLAGS'] = ''
                  end
              end
          end
      end
  end

Then, run the following command:

$ pod install

Carthage

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

Once you install Carthage, you can integrate Armchair into your Xcode project by specifying it in your Cartfile:

github "UrbanApps/Armchair"

Run carthage update to build the framework and drag the built Armchair.framework into your Xcode project.

Usage

Simple 1-line Setup

Armchair includes sensible defaults as well as reads data from your localized, or unlocalized info.plist to set itself up. While everything is configurable, the only required item to configure is your App Store ID. This call is the same for iOS and Mac apps, and should be made as part of your App Delegate's initialize() function

Armchair.appID("12345678")

That's it to get started. Setting Armchair up with this line uses some sensible default criterion (detailed below) and will present a rating prompt whenever they are met.

Custom Configuration

Optionally, if you are using significant events in your app to track when the user does something of significance, add this line to any place where this event happens, such as a levelDidFinish function, or userDidUploadPhoto function.

Armchair.userDidSignificantEvent(true)

In order for this to mean anything to Armchair, you also have to set the threshold for significant events. Typically, this, and all other logic configuration settings, should be made as part of your App Delegate's initialize() function so it can get the notifications on app launch.

Armchair.significantEventsUntilPrompt(5)

As mentioned above, the appID is the only required item to configure. It is used to generate the URL that will link to the page. Most often, this is configured to the App that is currently running, but there may be an instance where you want to set it to another app, such as in an App that reviews other Apps.

// GETTER
Armchair.appID() -> String
// SETTER
Armchair.appID(appID: String)

Display Strings

The appName is used in several places on the review prompt popup. It can be configured here to customize your message without losing any of the default localizations. By default, Armchair will read the value from your localized, or unlocalized info.plist, but you can set it specifically if you want.

// GETTER
Armchair.appName() -> String
// SETTER
Armchair.appName(appName: String)

The reviewTitle is the title to use on the review prompt popup. It's default value is a localized "Rate <appName>", but you can set it to anything you want.

// GETTER
Armchair.reviewTitle() -> String
// SETTER
Armchair.reviewTitle(reviewTitle: String)

The reviewMessage is the message to use on the review prompt popup. It's default value is a localized "If you enjoy using <appName>, would you mind taking a moment to rate it? It won't take mor

Armchair

Install / Use

README