nicklockwood / irate

[DEPRECATED]

---

WARNING: THIS PROJECT IS DEPRECATED

It will not receive any future updates or bug fixes. If you are using it, please migrate to another solution.

---

Purpose

iRate is a library to help you promote your iPhone and Mac App Store apps by prompting users to rate the app after using it for a few days. This approach is one of the best ways to get positive app reviews by targeting only regular users (who presumably like the app or they wouldn't keep using it!).

Supported OS & SDK Versions

• Supported build target - iOS 10.3 / Mac OS 10.12 (Xcode 8.3)
• Earliest supported deployment target - iOS 8.0 / Mac OS 10.11
• Earliest compatible deployment target - iOS 7.0 / Mac OS 10.9

NOTE: 'Supported' means that the library has been tested with this version. 'Compatible' means that the library should work on this OS version (i.e. it doesn't rely on any unavailable SDK features) but is no longer being tested for compatibility and may require tweaking or bug fixes to run correctly.

ARC Compatibility

As of version 1.7, iRate requires ARC. If you wish to use iRate in a non-ARC project, just add the -fobjc-arc compiler flag to the iRate.m class. To do this, go to the Build Phases tab in your target settings, open the Compile Sources group, double-click iRate.m in the list and type -fobjc-arc into the popover.

If you wish to convert your whole project to ARC, comment out the #error line in iRate.m, then run the Edit > Refactor > Convert to Objective-C ARC... tool in Xcode and make sure all files that you wish to use ARC for (including iRate.m) are checked.

Thread Safety

iRate uses threading internally to avoid blocking the UI, but none of the iRate external interfaces are thread safe and you should not call any methods or set any properties on iRate except from the main thread.

Installation

To install iRate into your app, drag the iRate.h, .m and .bundle files into your project. You can omit the .bundle if you are not interested in localised text.

iRate typically requires no configuration at all and will simply run automatically, using the application's bundle ID to look the app ID up on the App Store.

Note: If you have apps with matching bundle IDs on both the Mac and iOS app stores (even if they use different capitalisation), the lookup mechanism won't work, so you'll need to manually set the appStoreID property, which is a numeric ID that can be found in iTunes Connect after you set up an app. Also, if you are creating a sandboxed Mac app and your app does not request the network access permission then you will need to set the appStoreID because it cannot be retrieved from the iTunes service.

If you do wish to customise iRate, the best time to do this is in your AppDelegate's -[application:didFinishLaunchingWithOptions:] method. Applying the configuration any later may not work, as the prompt may already have been shown by that point:

#import "iRate.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    //configure iRate
    [iRate sharedInstance].daysUntilPrompt = 5;
    [iRate sharedInstance].usesUntilPrompt = 15;
    
    return YES;
}

Configuration

To configure iRate, there are a number of properties of the iRate class that can alter the behaviour and appearance of iRate. These should be mostly self- explanatory, but they are documented below:

@property (nonatomic, assign) NSUInteger appStoreID;

This should match the iTunes app ID of your application, which you can get from iTunes connect after setting up your app. This value is not normally necessary and is generally only required if you have the aforementioned conflict between bundle IDs for your Mac and iOS apps, or in the case of Sandboxed Mac apps, if your app does not have network permission because it won't be able to fetch the appStoreID automatically using iTunes services.

@property (nonatomic, assign) NSUInteger appStoreGenreID;

This is the type of app, used to determine the default text for the rating dialog. This is set automatically by calling an iTunes service, so you shouldn't need to set it manually for most purposes. If you do wish to override this value, setting it to the iRateAppStoreGameGenreID constant will cause iRate to use the "game" version of the rating dialog, and setting it to any other value will use the "app" version of the rating dialog.

@property (nonatomic, copy) NSString *appStoreCountry;

This is the two-letter country code used to specify which iTunes store to check. It is set automatically from the device locale preferences, so shouldn't need to be changed in most cases. You can override this to point to the US store, or another specific store if you prefer, which may be a good idea if your app is only available in certain countries.

@property (nonatomic, copy) NSString *applicationName;

This is the name of the app displayed in the iRate alert. It is set automatically from the application's info.plist, but you may wish to override it with a shorter or longer version.

@property (nonatomic, copy) NSString *applicationBundleID;

This is the application bundle ID, used to retrieve the appStoreID and appStoreGenreID from iTunes. This is set automatically from the app's info.plist, so you shouldn't need to change it except for testing purposes.

@property (nonatomic, assign) float daysUntilPrompt;

This is the number of days the user must have had the app installed before they are prompted to rate it. The time is measured from the first time the app is launched. This is a floating point value, so it can be used to specify a fractional number of days (e.g. 0.5). The default value is 10 days.

@property (nonatomic, assign) NSUInteger usesUntilPrompt;

This is the minimum number of times the user must launch the app before they are prompted to rate it. This avoids the scenario where a user runs the app once, doesn't look at it for weeks and then launches it again, only to be immediately prompted to rate it. The minimum use count ensures that only frequent users are prompted. The prompt will appear only after the specified number of days AND uses has been reached. This defaults to 10 uses.

@property (nonatomic, assign) NSUInteger eventsUntilPrompt;

For some apps, launches are not a good metric for usage. For example the app might be a daemon that runs constantly, or a game where the user can't write an informed review until they've reached a particular level. In this case you can manually log significant events and have the prompt appear after a predetermined number of these events. Like the usesUntilPrompt setting, the prompt will appear only after the specified number of days AND events, however once the day threshold is reached, the prompt will appear if EITHER the event threshold OR uses threshold is reached. This defaults to 10 events.

@property (nonatomic, assign) float usesPerWeekForPrompt;

If you are less concerned with the total number of times the app is used, but would prefer to use the frequency of times the app is used, you can use the usesPerWeekForPrompt property to set a minimum threshold for the number of times the user must launch the app per week (on average) for the prompt to be shown. Note that this is the average since the app was installed, so if the user goes for a long period without running the app, it may throw off the average. The default value is zero.

@property (nonatomic, assign) float remindPeriod;

How long the app should wait before reminding a user to rate after they select the "remind me later" option (measured in days). A value of zero means the app will remind the user next launch. Note that this value supersedes the other criteria, so the app won't prompt for a rating during the reminder period, even if a new version is released in the meantime. This defaults to 1 day.

@property (nonatomic, copy) NSString *messageTitle;

The title displayed for the rating prompt. If you don't want to display a title then set this to @"";

@property (nonatomic, copy) NSString *message;

The rating prompt message. This should be polite and courteous, but not too wordy. If you don't want to display a message then set this to @"";

@property (nonatomic, copy) NSString *updateMessage;

This is a message to be used for users who have previously rated the app, encouraging them to re-rate. This allows you to customise the message for these users. If you do not supply a custom message for this case, the standard message will be used.

@property (nonatomic, copy) NSString *cancelButtonLabel;

The button label for the button to dismiss the rating prompt without rating the app.

@property (nonatomic, copy) NSString *rateButtonLabel;

The button label for the button the user presses if they do want to rate the app.

@property (nonatomic, copy) NSString *remindButtonLabel;

The button label for the button the user presses if they don't want to rate the app immediately, but do want to be reminded about it in future. Set this to @"" if you don't want to display the remind me button - e.g. if you don't have space on screen.

@property (nonatomic, assign) BOOL useAllAvailableLanguages;

By default, iRate will use all available languages in the iRate.bundle, even if used in an app that does not support localisation. If you would prefer to restrict iRate to only use the same set of languages that your application already supports, set this property to NO. (Defaults to YES).

@property (nonatomic, assign) BOOL promptForNewVersionIfUserRated;

Because iTunes ratings are version-specific, you ideally want users to rate each new version of your app. Users who really love your app may be willing to update their review for new releases. Set promptForNewVersionIfUserRated to YES, and iRate will prompt the user again each time they install an update until they decline to rate the app. If they decline, they will not be asked again.

@property (nonatomic, assign) BOOL onlyPromptIfLatestVersion;

Set this to NO to enabled the rating prompt to be displayed even if the user is not running the latest version of the app. This defaults to YES because that way users won't leave bad reviews due to bugs that you've already fixed, etc.

@property (nonatomic, assign) BOOL onlyPromptIfMainWindowIsAvailable;

This setting is applicable to Mac OS only. By default, on Mac OS the iRate alert is displayed as sheet on the main window. Some applications do not have a main window, so this approach doesn't work. For such applications, set this property to NO to allow the iRate alert to be displayed as a regular modal window.

@property (nonatomic, assign) BOOL promptAtLaunch;

Set this to NO to disable the rating prompt appearing automatically when the application launches or returns from the background. The rating criteria will continue to be tracked, but the prompt will not be displayed automatically while this setting is in effect. You can use this option if you wish to manually control display of the rating prompt.

@property (nonatomic, assign) BOOL verboseLogging;

This option will cause iRate to send detailed logs to the console about the prompt decision process. If your app is not correctly prompting for a rating when you would expect it to, this will help you figure out why. Verbose logging is enabled by default on debug builds, and disabled on release and deployment builds.

@property (nonatomic, assign) BOOL previewMode;

If set to YES, iRate will always display the rating prompt on launch, regardless of how long the app has been in use or whether it's the latest version (unless you have explicitly disabled the promptAtLaunch option). Use this to proofread your message and check your configuration is correct during testing, but disable it for the final release (defaults to NO).

@property (nonatomic, assign) BOOL useUIAlertControllerIfAvailable;

By default, iRate will use UIAlertView on iOS to display the rating prompt. UIAlertView was deprecated in iOS8 and replaced by UIAlertController. Unfortunately, unlike UIAlertView, presenting an alert with UIAlertController interferes with the ability of the app to display other controllers, and since iRate could theoretically display an alert at any point during the app's lifetime, it might clash with the app attempting to present another view controller. For this reason, use of UIAlertController is disabled by default. You should only set this property to YES if you are certain that it won't clash with your app logic (e.g, if you have disabled automatic rating prompts, or if your app doesn't use any modal view controllers).

@property (nonatomic, assign) BOOL useSKStoreReviewControllerIfAvailable;

By default, iRate will use the SKStoreReviewController to request reviews on iOS 10.3 and above. To disable this, set useSKStoreReviewControllerIfAvailable to NO.

Advanced properties

If the default iRate behaviour doesn't meet your requirements, you can implement your own by using the advanced properties, methods and delegate. The properties below let you access internal state and override it:

@property (nonatomic, strong) NSURL *ratingsURL;

The URL that the app will direct the user to so they can write a rating for the app. This is set to the correct value for the given platform automatically. On iOS 6 and below this takes users directly to the ratings page, but on iOS 7 and Mac OS it takes users to the main app page (if there is a way to directly link to the ratings page on those platforms, I've yet to find it). If you are implementing your own rating prompt, you should probably use the openRatingsPageInAppStore method instead, especially on Mac OS, as the process for opening the Mac app store is more complex than merely opening the URL.

@property (nonatomic, strong) NSDate *firstUsed;

The first date on which the user launched the current version of the app. This is used to calculate whether the daysUntilPrompt criterion has been met.

@property (nonatomic, strong) NSDate *lastReminded;

The date on which the user last requested to be reminded to rate the app later.

@property (nonatomic, assign) NSUInteger usesCount;

The number of times the current version of the app has been used (launched).

@property (nonatomic, assign) NSUInteger eventCount;

The number of significant application events that have been recorded since the current version was installed. This is incremented by the logEvent method, but can also be manipulated directly. Check out the Events Demo to see how this os used.

@property (nonatomic, readonly) float usesPerWeek;

The average number of times per week that the current version of the app has been used (launched).

@property (nonatomic, assign) BOOL declinedThisVersion;

This flag indicates whether the user has declined to rate the current version (YES) or not (NO). This is not currently used by the iRate prompting logic, but may be useful for implementing your own logic.

@property (nonatomic, assign) BOOL declinedAnyVersion;

This flag indicates whether the user has declined to rate any previous version of the app (YES) or not (NO). iRate will not prompt the user automatically if this is set to YES.

@property (nonatomic, assign) BOOL ratedThisVersion;

This flag indicates whether the user has already rated the current version (YES) or not (NO).

@property (nonatomic, readonly) BOOL ratedAnyVersion;

This (readonly) flag indicates whether the user has previously rated any version of the app (YES) or not (NO).

@property (nonatomic, assign) id<iRateDelegate> delegate;

An object you have supplied that implements the iRateDelegate protocol, documented below. Use this to detect and/or override iRate's default behaviour. This defaults to the App Delegate, so if you are using your App Delegate as your iRate delegate, you don't need to set this property.

Methods

Besides configuration, iRate has the following methods:

- (BOOL)shouldPromptForRating;

Returns YES if the prompt criteria have been met, and NO if they have not. You can use this to decide when to display a rating prompt if you have disabled the automatic display at app launch. Calling this method will not call the iRateShouldPromptForRating delegate method.

- (void)promptForRating;

This method will immediately trigger the rating prompt without checking that the app store is available, and without calling the iRateShouldPromptForRating delegate method. Note that this method depends on the appStoreID and applicationGenre properties, which are only retrieved after polling the iTunes server, so if you intend to call this method directly, you will need to set these properties yourself beforehand, or use the promptIfNetworkAvailable method instead.

- (void)promptIfNetworkAvailable;

This method will check if the app store is available, and if it is, it will display the rating prompt to the user. The iRateShouldPromptForRating delegate method will be called before the alert is shown, so you can intercept it. Note that if your app is sandboxed and does not have the network access permission, this method will ignore the network availability status, however in this case you will need to manually set the appStoreID or iRate cannot function.

- (void)promptIfAllCriteriaMet;

This method will check if all prompting criteria have been met, and if the app store is available, and if it is, it will display the rating prompt to the user. The iRateShouldPromptForRating delegate method will be called before the alert is shown, so you can intercept it.

- (void)openRatingsPageInAppStore;

This method skips the user alert and opens the application ratings page in the Mac or iPhone app store, depending on which platform iRate is running on. This method does not perform any checks to verify that the machine has network access or that the app store is available. It also does not call the -iRateShouldOpenAppStore delegate method. You should use this method to open the ratings page instead of the ratingsURL property, as the process for launching the app store is more complex than merely opening the URL in many cases. Note that this method depends on the appStoreID which is only retrieved after polling the iTunes server. If you call this method without first doing an update check, you will either need to set the appStoreID property yourself beforehand, or risk that the method may take some time to make a network call, or fail entirely. On success, this method will call the -iRateDidOpenAppStore delegate method. On Failure it will call the -iRateCouldNotConnectToAppStore: delegate method.

- (void)logEvent:(BOOL)deferPrompt;

This method can be called from anywhere in your app (after iRate has been configured) and increments the iRate significant event count. When the predefined number of events is reached, the rating prompt will be shown. The optional deferPrompt parameter is used to determine if the prompt will be shown immediately (NO) or if the app will wait until the next launch (YES).

- (void)remindLater;

This method resets the reminder period.

Delegate methods

The iRateDelegate protocol provides the following methods that can be used intercept iRate events and override the default behaviour. All methods are optional.

- (void)iRateCouldNotConnectToAppStore:(NSError *)error;

This method is called if iRate cannot connect to the App Store, usually because the network connection is down. This may also fire if your app does not have access to the network due to Sandbox permissions, in which case you will need to manually set the appStoreID so that iRate can still function.

- (void)iRateDidDetectAppUpdate;

This method is called if iRate detects that the application has been updated since the last time it was launched.

- (BOOL)iRateShouldPromptForRating;

This method is called immediately before the rating prompt is displayed to the user. You can use this method to implement custom prompt logic in addition to the standard rules. You can also use this method to block the standard prompt alert and display the rating prompt in a different way, or bypass it altogether.

- (void)iRateDidPromptForRating;

This method is called immediately before the rating prompt is displayed. This is useful if you use analytics to track what percentage of users see the prompt and then go to the app store. This can help you fine tune the circumstances around when/how you show the prompt.

- (void)iRateUserDidAttemptToRateApp;

This is called when the user pressed the rate button in the rating prompt. This is useful if you want to log user interaction with iRate. This method is only called if you are using the standard iRate alert view prompt and will not be called automatically if you provide a custom rating implementation or call the openRatingsPageInAppStore method directly.

- (void)iRateUserDidDeclineToRateApp;

This is called when the user declines to rate the app. This is useful if you want to log user interaction with iRate. This method is only called if you are using the standard iRate alert view prompt and will not be called automatically if you provide a custom rating implementation.

- (void)iRateUserDidRequestReminderToRateApp;

This is called when the user asks to be reminded to rate the app. This is useful if you want to log user interaction with iRate. This method is only called if you are using the standard iRate alert view prompt and will not be called automatically if you provide a custom rating implementation.

- (BOOL)iRateShouldOpenAppStore;

This method is called immediately before iRate attempts to open the app store. Return NO if you wish to implement your own ratings page display logic.

- (void)iRateDidOpenAppStore;

This method is called immediately after iRate opens the app store.

Localisation

The default strings for iRate are already localised for many languages. By default, iRate will use all the localisations in the iRate.bundle even in an app that is not localised, or which is only localised to a subset of the languages that iRate supports. The iRate strings keys are:

static NSString *const iRateMessageTitleKey = @"iRateMessageTitle";
static NSString *const iRateAppMessageKey = @"iRateAppMessage";
static NSString *const iRateGameMessageKey = @"iRateGameMessage";
static NSString *const iRateUpdateMessageKey = @"iRateUpdateMessage";
static NSString *const iRateCancelButtonKey = @"iRateCancelButton";
static NSString *const iRateRemindButtonKey = @"iRateRemindButton";
static NSString *const iRateRateButtonKey = @"iRateRateButton";

If you would prefer iRate to only use the localisations that are enabled in your application (so that if your app only supports English, French and Spanish, iRate will automatically be localised for those languages, but not for German, even though iRate includes a German language file), set the useAllAvailableLanguages option to NO.

It is not recommended that you modify the strings files in the iRate.bundle, as it will complicate updating to newer versions of iRate. The exception to this is if you would like to submit additional languages or improvements or corrections to the localisations in the iRate project on github (which are greatly appreciated).

If you want to add an additional language for iRate in your app without submitting them back to the github project, you can add these strings directly to the appropriate Localizable.strings file in your project folder. If you wish to replace some or all of the default iRate strings, the simplest option is to copy just those strings into your own Localizable.strings file and then modify them. iRate will automatically use strings in the main application bundle in preference to the ones in the iRate bundle so you can override any string in this way.

If you do not want to use any of the default localisations, you can omit the iRate.bundle altogether. Note that if you only want to support a subset of languages that iRate supports, it is not necessary to delete the other strings files from iRate.bundle - just set useAllAvailableLanguages to NO, and iRate will only use the languages that your app already supports.

The old method of overriding iRate's default strings by using individual setter methods (see below) is still supported, however the recommended approach is now to add those strings to your project's Localizable.strings file, which will be detected automatically by iRate.

+ (void)initialize
{
    //overriding the default iRate strings
    [iRate sharedInstance].messageTitle = NSLocalizedString(@"Rate MyApp", @"iRate message title");
    [iRate sharedInstance].message = NSLocalizedString(@"If you like MyApp, please take the time, etc", @"iRate message");
    [iRate sharedInstance].cancelButtonLabel = NSLocalizedString(@"No, Thanks", @"iRate decline button");
    [iRate sharedInstance].remindButtonLabel = NSLocalizedString(@"Remind Me Later", @"iRate remind button");
    [iRate sharedInstance].rateButtonLabel = NSLocalizedString(@"Rate It Now", @"iRate accept button");
}

Example Projects

When you build and run the basic Mac or iPhone example project for the first time, it will show an alert asking you to rate the app. This is because the previewMode option is set.

Disable the previewMode option and play with the other settings to see how the app behaves in practice.

Advanced Example

The advanced example demonstrates how you might implement a completely bespoke iRate interface using the iRateDelegate methods. Automatic prompting is disabled and instead the user can opt to rate the app by pressing the "Rate this app" button.

When pressed, the app first checks that the app store is available (it may not be if the computer has no Internet connection or apple.com is down), and then launches the Mac App Store.

The example is for Mac OS, but the same principle can be applied on iOS.

Release Notes

Version 1.12.2

• Marked as deprecated

Version 1.12.1

• Fixed problems compiling on older Xcode versions due to SKStoreReviewController

Version 1.12

• Added support for SKStoreReviewController on iOS 10.3+ (thanks @EpicDraws!)
• Added Catalan, Hungarian, Croatian and Bosnian localizations
• Fixed random crash due to misconfigured NSURLRequest

Version 1.11.7

• Updated for iOS 10 and Xcode 8
• Fixed checkForConnectivity crash
• Added Finnish language support
• Lowered Carthage deployment target to 8.0

Version 1.11.6

• Fixed compatibility with iOS 7

Version 1.11.5

• Now uses https URLs to avoid issues with App Transport Security
• Fixed Swift crashes due to nonstandard delegate implementation
• Added special case for Gibraltar
• Fixed warnings on latest Xcode
• Added Carthage support
• Added Taiwan Chinese (zh-TW) localization
• Better Italian localisation
• Exposed remindLater method

Version 1.11.4

• Added fix for possible Apple rejection issue to do with canOpenURL:
• Added fix for nil locale issue
• Added Macedonian translation

Version 1.11.3

• Added useUIAlertControllerIfAvailable option
• Disabled UIAlertController by default as it may interfere with in-app controller logic

Version 1.11.2

• Fixed critical bug in alert button handling on iOS 7 and earlier

Version 1.11.1

• Fixed deprecation warnings on Mac OS X 10.10 Yosemite
• Improved Urdu translation

Version 1.11

• Added promptIfCriteriaMet convenience method
• Added NSNotificationCenter notifications as alternative to delegate
• Now uses UIAlertController instead of UIAlertView if available
• Fixed compiler error when building with Xcode 6
• Fixed error in Thai translation
• Fixed potential crash on iOS 6
• Improved Farsi translation
• Now fully compatible with Swift
• Added Swift Demo example

Version 1.10.3

• Fixed another bug in the rating reset logic after upgrade
• Improved Turkish translation

Version 1.10.2

• Fixed bug where app would never prompt for rating after an upgrade if it had not already done so
• Improved italian localization

Version 1.10.1

• Fixed serious bug that prevents rating prompt appearing for any new apps
• Fixed issue where bad response from iTunes would be cached indefinitely

Version 1.10

• Now links directly to review page again on iOS 7.1 + (Apple has fixed support)
• No longer interrupts rating popups for the full daysUntilPrompt period after an app update
• Added promptForNewVersionIfUserRated option to re-prompt users who have previous rated (off by default)
• Added updateMessage property for use with promptForNewVersionIfUserRated option
• Fixed typo in French translation

Version 1.9.3

• No longer logs warning if app ID is not found, unless in verbose mode
• Minor translation fix for Vietnamese

Version 1.9.2

• Added Bengali, Farsi, Hindi, Punjabi, Thai and Vietnamese translations

Version 1.9.1

• Fixed problem with fetching app ID when device region is set to Europe

Version 1.9

• iRate will no longer ask users to rate the app again each version
• If the user selects "No, Thanks", they will now never be asked again
• Removed the promptAgainEachVersion option

Version 1.8.3

• Stricter warning compliance
• Now uses macros to avoid generating warnings when imported into apps with even stricter warning settings

Version 1.8.2

• Fixed issue where checkForConnectivityInBackground could be called on main thread, blocking user interaction

Version 1.8.1

• Added iRateDidOpenAppStore delegate method
• Language selection now works correctly if the user has an unsupported language
• Removed all support for StoreKit, as Apple have disabled the StoreKit rating panel
• Calling openRatingsPageInAppStore will now look up appStoreID automatically if not already known
• Improved error messaging when using iRate on the iOS Simulator
• Added Greek and Slovenian localizations

Version 1.8

• App store link works on iOS 7 (had to link to app home page instead of directly to reviews page for now - hopefully an alternative direct link can be found)
• Now uses NSJSONSerializer if available (iOS 4.x will still use the old parser)
• No longer requires StoreKit by default (see README for details)
• Fixed Czech and Austrian German locales for iOS 7
• Removed disableAlertViewResizing property (no longer needed)
• Improved Czech translation
• Improved French translation
• Urdu support
• Fixed bug in alertview resizing for iOS 6 and below
• Now complies with the -Wextra warning level

Version 1.7.5

• Improved Arabic translation
• Improved podspec file
• Removed .DS_Store file

Version 1.7.4

• Added Arabic translation
• Improved French translation
• Added delegate method for tracking when prompt gets shown

Version 1.7.3

• Added Slovak, Czech and Austrian translations
• Fixed some bugs in Cancel/Remind button disabling logic
• Added podspec file

Version 1.7.2

• Added dutch translation
• iRate now displays the StoreKit product view controller correctly even if a modally presented view controller has been displayed

Version 1.7.1

• Fixed deprecation warning when targeting iOS6 as the base target
• Added iRateDidPresentStoreKitModal and iRateDidDismissStoreKitModal delegate methods
• Added additional error logging if StoreKit fails to load product info
• Added Ukrainian translation

Version 1.7

• On iOS 6, iRate can now use the StoreKit APIs to display the product page directly within the app.
• iRate now requires the StoreKit framework on iOS
• iRate now requires ARC. To use iRate in a non-ARC project, follow the instructions in the README file.
• Dropped support for 32-bit Macs running Snow Leopard
• Added Swedish translation

Version 1.6.2

• Fixed broken ratings URL (Apple changed it)
• Added Danish translation

Version 1.6.1

• Fixed typo in Italian strings file

Version 1.6

• Added new localisation system (see README for details)
• Added usesPerWeekForPrompt setting
• Fixed deprecation warning in iOS 6
• Improved Spanish translation
• Improved German translation

Version 1.5.3

• Corrected minor spelling mistake in German translation

Version 1.5.2

• Restored App Store deep link on iOS6 (didn't work in beta, but now does)
• Added promptAgainForEachNewVersion option to enable/disable prompting each time the app is updated
• Added verboseLogging option to make it easier to diagnose why a new version isn't being correctly detected
• Renamed debug property to previewMode as this better describes its function
• Add Simplified Chinese localisation

Version 1.5.1

• Fixed crash on iOS 4.x and Mac OS 10.6.x when compiled using Xcode 4.4

Version 1.5

• Added support for iOS6. Currently it does not appear to be possible to take users directly to the ratings page on iOS6, but iRate will now at least open the app store on the app page without an error.
• Fixed bug in the app store country selection logic
• Changed appStoreGenre to appStoreGenreID, as this is not locale-specific

Version 1.4.9

• Added support for sandboxed Mac App Store apps with no network access
• Updated ARC Helper library

Version 1.4.8

• Added explicit 60-second timeout for connectivity check
• iRate will now no longer spawn multiple download threads if closed and re-opened whilst performing a check
• Added Portuguese translation

Version 1.4.7

• Fixed a bug where advanced properties set in the delegate methods might be subsequently overridden by iRate
• Added Events Demo example

Version 1.4.6

• Fixed odd glitch where shaking device would cause UIAlertview to slowly shrink
• Added disableAlertViewResizing option (see README for details)
• Added Resizing Disabled example project
• Added Korean translation

Version 1.4.5

• Improved German, Spanish, Japanese, Russian and Polish translations
• Added onlyPromptIfMainWindowIsAvailable option

Version 1.4.4

• Added Turkish localisation
• Improved German translation
• Fixed alert layout for long app names

Version 1.4.3

• It is now possible again to use debug to test the iRate message for apps that are not yet on the App Store.

Version 1.4.2

• Added Hebrew localisation
• Fixed issue with UIAlertView label resizing
• Fixed some compiler warnings

Version 1.4.1

• Added logic to prevent UIAlertView collapsing in landscape mode
• Added Russian, Polish and Traditional Chinese localisations
• Improved Japanese localisation
• Now handles nil cancel button text correctly

Version 1.4

• Included localisation for French, German, Italian, Spanish and Japanese
• iRate is now completely zero-config in most cases!
• It is no longer necessary to set the app store ID in most cases
• iRate default text now uses "playing" instead of "using" for games
• iRate delegate now defaults to App Delegate unless otherwise specified
• By default, iRate no longer prompts the user to rate the app unless they are running the latest version

Version 1.3.5

• Fixed bug introduced in 1.3.4 where remind button would not appear on iOS

Version 1.3.4

• Fixed compiler warning
• Added iRateDidDetectAppUpdate delegate method
• Added ARC Test example

Version 1.3.3

• Added missing ivar required for 32-bit Mac OS builds.

Version 1.3.2

• Added logic to prevent multiple prompts from being displayed if user fails to close one prompt before the next is due to be opened.
• Added workaround for change in UIApplicationWillEnterForegroundNotification implementation in iOS5

Version 1.3.1

• Added automatic support for ARC compile targets
• Now requires Apple LLVM 3.0 compiler target

Version 1.3

• Added additional delegate methods to facilitate logging
• Renamed disabled property to promptAtLaunch for clarity

Version 1.2.3

• iRate now uses CFBundleDisplayName for the application name (if available)
• Reorganised examples

Version 1.2.2

• Fixed misspelled delegate method
• Fixed bug in advanced Mac project where rating prompt was displayed automatically even if button was not pressed
• Removed unneeded project files

Version 1.2.1

• Exposed the shouldPromptForRating method to make it easier to control when rating prompt is displayed
• Increased MAC_APP_STORE_REFRESH_DELAY to 5 seconds to support older machines

Version 1.2

• Added delegate and additional accessor properties for custom behaviour
• Added advanced example project to demonstrate use of the delegate protocol

Version 1.1

• Now compatible with iOS 3.x
• Fixed incorrect iPhone review URL

Version 1.0

• Initial release.

irate's Issues

Resetting eventCount to re-display later. Not working

Hi, this is a great tool. Thanks.
I am using eventsUntilPrompt = 10 to display the dialog after 10 events, if they click to be reminded later I get the delegate call (void)iRateUserDidRequestReminderToRateApp and in here I reset the eventCount=0 and also lastReminded=nil;
This works fine, however when the eventCount reaches 10 again, I don't get another dialog message.
Is there something i've missed to make the dialog appear again?

Thanks

Continuous popping out

Hello.
I am facing some issues regarding the use of this library. After some time (I would say 5 days in my case), if a user click on the action that manually trigger the irate to pop out and says "no" to the rating, after this every time the application switched from background/foreground state, the irate will pop out. Which is really annoying for the user.

I must have missed some parameter, could you help me with this ?

Here's how I set up the irate in my case :
//in app delegate

• (void)initialize
  {
  [iRate sharedInstance].daysUntilPrompt = 5;
  [iRate sharedInstance].usesUntilPrompt = 15;
  [iRate sharedInstance].remindPeriod = 15;
  }

//my button callback

-(void)goToRate
{
[iRate sharedInstance].onlyPromptIfLatestVersion = NO;
[iRate sharedInstance].previewMode = YES;
[iRate sharedInstance].remindButtonLabel = @"";
[iRate sharedInstance].messageTitle = @"Love us!";
[iRate sharedInstance].message = @"test message.";
[[iRate sharedInstance] promptForRating];
}

misspelled word in german tranlation

"Bewerten %@" should be "Bewerte %@".
"Jetzt bewerten" is correct.

Documentation clarification

Outstanding library! I wanted to use it without making any modifications, but I was nervous that when I removed the [iRate sharedInstance].previewMode = YES, line iRate wouldn't get instantiated. Never knew about the very clever [NSObject load] method, and none of the sample projects had true zero configuration. So, a minor tweak to the documentation or the ZeroConfiguration project might make it easier for future users. Thanks again for this fantastic time-saving library.

French translation bad

Fixing it here coz it's UTF16 and I don't want to fork and ask pull request ;-)

"iRateMessageTitle" = "Notez %@";
"iRateAppMessage" = "Si vous aimez utiliser %@, n’oubliez pas de voter sur l’App Store. Cela ne prend qu’une minute. Merci d’avance pour votre soutien !";
"iRateGameMessage" = "Si vous aimez jouez à %@, n’oubliez pas de voter sur l’App Store. Cela ne prend qu’une minute. Merci d’avance pour votre soutien !";

Calling logEvent from somewhere other than the app delegate

How exactly would you call logEvent from somewhere other than the app delegate? Would you just import iRate.h into the view controller and then call it like so?

- (void) someMethod {
    [[iRate sharedInstance] logEvent:YES]; 
}

Keep asking after "No, Thanks"

Recently i got a bad review from some guy because, he says, the app keeps asking him to write a review even after he says "no, thanks".

Is it possible? I did change the app name in the appstore (keeping the same old bundle id), could that have caused a problem with iRate?

Also, can i reset (for testing) iRate's configuration, after i have tapped on "no thanks"?

I appreciate any help, thanks.

Update Stickers.plist on new version launch

Sorry Nick... wrong repository... I don't know how to delete it! :)

Can't get it to display

I'm having trouble testing this.
When debug = YES, it works fine, but when I just have this, I don't get the prompt after opening 4 or 5 times:

[iRate sharedInstance].appStoreID = 541893240;
[iRate sharedInstance].appStoreGenre = iRateAppStoreGenreGame;
[iRate sharedInstance].daysUntilPrompt = 0;
[iRate sharedInstance].usesUntilPrompt = 2;
[iRate sharedInstance].messageTitle = @"Rate us now";
[iRate sharedInstance].message = @"Rate and we'll give you 150 free stars!";
[iRate sharedInstance].disableAlertViewResizing = YES;
[iRate sharedInstance].onlyPromptIfLatestVersion = NO;

if ([[[UIDevice currentDevice] systemVersion] floatValue] >= 6.0) {
    [iRate sharedInstance].ratingsURL = [NSURL URLWithString:@"http://itunes.apple.com/us/app/twist-n-slide/id541893240?mt=8"];
}

Remove pbxuser

You shouldn't check in your nick.pbxuser file... better add it to .gitignore.

Missing ivar definition for property 'visibleAlert' breaks 32 bit build

XCode error:
/Users/username/Project/Folder/iRate.m:85:13: error: synthesized property 'visibleAlert' must either be named the same as a compatible ivar or must explicitly name an ivar [3]

For 32 bit builds, properties require an ivar for each property. These are automatically created for 64 bit builds, but must be manually added if compiling 32 bit as well. This error can be fixed by adding:

id visibleAlert;

on line 131 of iRate.h (using version 1.3.2 here).

Documentation Bug

Please change "Because iTunes ratings are version-specific, you ideally want users to rate each new version of your app." to read:

"Because iTunes ratings are version-specific, you ideally want to annoy the living shit out of your users every time they take the effort to update your app."

Documentation says OR, code says AND?

On line 303 of iRate.m:

else if (self.usesCount < usesUntilPrompt && self.eventCount < eventsUntilPrompt)

From the documentation:

Like the usesUntilPrompt setting, the prompt will appear only after the specified number of days AND events, however once the day threshold is reached, the prompt will appear if either the event threshold OR uses threshold is reached.

I'm under the impression that OR is correct. I have modified my copy to work with OR and it seems more consistent with my expectations.

iPad display issue

I made a universal app for iOS and I added the iRate library. When I launch the application in the iPhone simulator everything is fine but when I launch the application on the iPad simulator there are display issues of app store. This issue is also present on the iPad device? The visualization of prompt it's all right. Thanks.

fus

crashing on snow leopard

iRate is crashing on Snow Leopard (bad access)

iRate should not use SKStoreProductViewController on iOS 5 device

iRate will prompt users to rate with SKStoreProductViewController on ios5 devices. Since ios5 does not support it, the users will see an empty view instead.

The problem occurs on XCode 4.6 DP3, but not on XCode 4.5.2.
The difference is that [SKStoreProductViewController class] is evaluated to be "true" on XCode 4.6, and "false" on XCode 4.5.2.

Maybe it is a bug from XCode 4.6 DP3?

json form iTunesServiceURL failed

In the method - (void)checkForConnectivityInBackground the iTunesServiceURL->data is created.
In my case it looks correct "http://itunes.apple.com/lookup?country=DE&bundleId=de.berndrabe.iPrayTimes" but the json string created from it has no result.
The difference I have seen from your ZeroConfig sample project an my project is that the data object created from the url is much larger (3720 bytes versus 42 bytes) though the iTunesServiceURL contains no more objects.

app display name may be wrong

iRate uses the BundleName to display the apps name within an iOS UIAlertView (kCFBundleNameKey). Because the name can be localized and overwritten by plist entry, it is suggested to use the key @"CFBundleDisplayName" instead.

Is it possible to automatically rate the app to 5 stars ("fill in 5 stars automatically") when the user presses the "Rate it Now" button ? ...

...instead of them manually tapping the stars.

My app is a kids app and I feel that they wouldnt know what ratings are and can even wrongly rate the app even if they love it.

Any suggestions would be greatly appreciated. Thanks

Still deprecated and more

Just downloaded the latest version available on here today, 1.7, and I am receiving another deprecation notice (see pull req.):

dismissModalViewControllerAnimated:

First deprecated in iOS 6.0

Also, I am receiving this error, for a reason I'm unsure of:

Undefined symbols for architecture i386:
"OBJC_CLASS$_SKStoreProductViewController", referenced from:
objc-class-ref in iRate.o
"_SKStoreProductParameterITunesItemIdentifier", referenced from:
-[iRate openRatingsPageInAppStore] in iRate.o
ld: symbol(s) not found for architecture i386
clang: error: linker command failed with exit code 1 (use -v to see invocation)

Xcode 4.5.2 (4G2008a) under deployment target 5.0 and 6.0.

UIApplicationWillEnterForegroundNotification

Hey Nick,

Would it cause iRate any issues if I remove the support for the above notification ?

My iOS app is a music player which will naturally spend most of its time running in the background, only being brought to the foreground by the user when they wish to change the track or album etc. Therefore I don't think that using this notification to increment the use count really suits this scenario, and as such I would only like this to happen on app launch.

As far as I can I only need to remove the observer and the subsequent selector but before I do this I just wanted to make sure nothing else, that Iv'e missed, relies on this particular notification.

Mic

Bundle files appear as binary (and not plist text files)

Hi,

I'm not sure why, but it was a little tricky adding localizations here, because the localization files are set as binary files.

for example compare https://github.com/nicklockwood/iRate/blob/master/iRate/iRate.bundle/he.lproj/Localizable.strings to https://github.com/facebook/three20/blob/master/src/Three20.bundle/he.lproj/Localizable.strings

For some reason, github and my local xcode don't detect these files as plist files.

Keyboard Hidden

In landscape the keyboard is hidden in ipad . My application only support Landscape mode. this issues happens when user tries to put comment for the application

Feature: use store kit

Hi,

starting with iOS 6 the app store can be presented as a modal view.
Can you please add this feature, code is on stackoverflow:
http://stackoverflow.com/questions/12475568/appstore-as-modal-view-in-ios6

Thanks!

Compiling for non-ARC project

I saw the note about this project working with or without ARC, but when I try to compile in my project I get a few errors about "Expected a property attribute before strong" in iRate.h. I'm using the LLVM GCC4.2 compiler in case that's relevant.

Also, if I change the strong attribute to retain, then I get an error about "Apple Mach-O Linker"

Event count checking incorrect.

Current code is:

else if (self.usesCount < self.usesUntilPrompt && self.eventCount < self.eventsUntilPrompt)
{
  if (self.verboseLogging)
  {
    NSLog(@"iRate did not prompt for rating because the app has only been used %i times and only %i events have been logged", (int)self.usesCount, (int)self.eventCount);
  }
  return NO;
}

If usesCount >= usesUntilPrompt but we have 0 events (or < self.eventsUntilPrompt), the dialog will appear. It shouldn't.

For instance, I've used the app 100 times but never triggered the event. The rating dialog will appear.

It should be:

else if (self.usesCount < self.usesUntilPrompt || self.eventCount < self.eventsUntilPrompt)
{
  ... 
  return NO;
}

I'm surprised this hasn't been caught.

setting appStoreID, and/or applicationBundleID; error with ...does not match expected value of...

Using a different bundle identifier for our ad hoc distributions, so I thought that by setting the applicationBundleID, and/or appStoreID properties of the irate shared... to the real app's ... , along with previewMode = YES would work. But I get the

iRate found that the application bundle ID (com.domain.appID) does not match the bundle ID of the app found on iTunes (com.domain.appID) with the specified App Store ID (the app id as it exists in the store)

I've also constructed the url and set that on the irate shared instance and still error.

Also, earlier, iRate successfully gets the App Store details, per this debug line:

iRate is checking http://itunes.apple.com/US/lookup?id=actualCorrectID to retrieve the App Store details...

If I'm doing something wrong, please let me know what that would be. Otherwise, I can send more info if you want. Thanks.

App with iRate crashes under OS X 10.6.8

After integrated iRate into my Mac app, the app could no longer start on OS X 10.6.8 (the app works on 10.7.4 & 10.8.0).

I've dragged both .h & .m of iRate version 1.5 into my project. Then configured it in +[AppDelegate initialize]. Upon starting in OS X 10.6.8, the app crashes and following error is logged in Console.app:

Exception Type:  EXC_BREAKPOINT (SIGTRAP)
Exception Codes: 0x0000000000000002, 0x0000000000000000
Crashed Thread:  0  Dispatch queue: com.apple.main-thread

Dyld Error Message:
  Symbol not found: _objc_retainAutoreleasedReturnValue
  Referenced from: /Applications/Healthier.app/Contents/MacOS/Healthier
  Expected in: /usr/lib/libobjc.A.dylib

iRate detecting incorrect Country App. Store

If the regional settings are different from the App Store Country of the account configured. iRate doesn't prompt the user.

Device config.
iOS 5.1
iPod Touch 4th Gen
App. Store account country = Pakistan
Time Zone = Islamabad
Region Format = Australia

Language: en_AU (English)
Timezone: PKT

Data from logs:

2012-4-11 18:57:09 shouldPromptForRating:appStoreCountry=AU
2012-4-11 18:57:09 shouldPromptForRating:appStoreID=502431430

Building on Xcode < 4.5

Hi,
There is isssue with building code on Xcode < 4.5. There is error: use of undeclared identifier 'NSLineBreakByWordWrapping'.
It is caused by fact that __IPHONE_6_0 macro is not defined in this case (if it is not defined so it has zero value). So should be changed condition (which is true in Xcode < 4.5):

if __IPHONE_OS_VERSION_MIN_REQUIRED >= __IPHONE_6_0

                label.lineBreakMode = NSLineBreakByWordWrapping;

...

Regards
Adam

Opening iRate in particular views after certain time

I am new to using iRate in my app. I have few questions here

I have to setup iRate on particular views after certain time user view results. Is there any such type of options are there .

please inform

Reviews tab is not selected when displayed using Storekit

The details tab is selected instead. Reviews is selected when opened in the AppStore app.

Is this a limitation of the Storekit SDK or a bug?

No prompt is shown (except in debug mode)

If I initialize my app with:
[iRate sharedInstance].debug = YES;

The rating prompt shows fine.

But if I don't set the debug mode - then the prompt is never shown.

Logging results of user prompts

Thanks, great tool. Replaced my homebrew version with this... One feature suggestion. Can you add methods to the delegate that indicate what the user's action was, such as "said yes" and "said no", "said later", etc... This would be very useful for metrics, for example I can use Flurry to record the number of times prompts were shown, vs how many yes/no/later's I got to understand if people actually USE the rating helper, or if they always press no, in which case it might just be annoying.

Send users directly to "Reviews" tab

When a user clicks "Rate It Now" on the UIAlertView, it takes them to my app's page on the app store (through a SKStoreProductViewController), but to the main "Details" tab, not the "Reviews" tab. I know this link:

"itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/viewContentsUserReviews?type=Purple+Software&id=%u"

is supposed to do that, but for some reason it doesn't seem to be working for me. Has anyone else noticed this?

Thanks and a comment...

First, thanks for all your open source efforts. They are fantastic.

Second, I really like the name of iRate - as long as people like my apps, otherwise they will be irate... oh well...

Change Settings

Hi,
I am trying to change how often the rate me comes up. Right now the code says YES for preview mode, but when I change that to NO, it doesn't work. Then when I try to initialize:

• (void)initialize
  {
  //configure iRate
  [iRate sharedInstance].daysUntilPrompt = 5;
  [iRate sharedInstance].usesUntilPrompt = 15;
  }

I get an error saying use of undeclared 'iRate'. So what should I do? If you need any more info, just let me know. Thanks!

Doesn't work on iOS 6

Just to let you know, I've just teste this on iOS 6 and the link to app store doesn't work. It opens the app store but then says it cannot open it.

Landscape support

Any thoughts on adding this to iRate.m for landscape support with all buttons?

Found here: http://www.cocos2d-iphone.org/forum/topic/15690

Seems to work for me.

- (void)willPresentAlertView:(UIAlertView *)alertView {
    alertView.frame = CGRectMake(alertView.frame.origin.x, alertView.frame.origin.y - 35, alertView.frame.size.width, alertView.frame.size.height + 71);
    for (UIView *subview in [alertView subviews]) {
        if ([subview isKindOfClass:[UILabel class]]) {
            UILabel *label = (UILabel *)subview;
            if ([label.text isEqualToString:self.message]) {
                label.frame = CGRectMake(12, 45, 260, 81);
                label.alpha = 1.0f;
                label.lineBreakMode = UILineBreakModeWordWrap;
                label.numberOfLines = 0;
            }
        } else if ([subview isKindOfClass:[UIControl class]]) {
            UIControl *button = (UIControl *)subview;
            button.frame = CGRectMake(button.frame.origin.x, button.frame.origin.y + 71, button.frame.size.width, button.frame.size.height);
        }
    }
}

Cannot connect to iTunes Store (ios6)

Hi,

I was just trying to add iRate to one of my apps and I can't get it to open iTunes properly.

• I'm using the latest version of iRate (1.6.1)
• Devices have ios 6 installed
• I've checked that the detected app id is correct
• i've tried on ipad and iphone (the game is iphone only though)... same problem
• i've checked that the dev version i'm using has the same version number as the app store one

I've seen the thread here on github related to ios6, but it said it was fixed/closed.

The URL it tries to open seems correct, and itunes tried to load for a little while then says it can't connect.

Anything else I should check or try?

Thanks

iRateShouldShouldPromptForRating Delegate Method

Perhaps -iRateShouldShouldPromptForRating should be -iRateShouldPromptForRating?

Showing up only in english

I'm running an app in the "previewMode", and it's always showing me the iRate dialog in english, even though the iPhone is setup to use Portuguese.

I have another project with an older version of iRate that shows up in portuguese just fine.

What could be the cause of this? Could it be because the app isn't in the AppStore yet, so it has no App Store ID?

Thanks.

Additional options

A few options should be added.

• Option to only prompt the user for a rating just once, regardless of a new version or not. If people release frequent updates, it can get annoying to the user.
• Option to disable all rating prompts. That way a developer can add an option to his settings menu, to give the user control to stop being prompted for new ratings should new application versions be released.

Deprecation warning in iOS 6 project

In line 867 of iRate.m:
label.lineBreakMode = UILineBreakModeWordWrap;

Produces warning:
/iRate/iRate/iRate.m:867:43: 'UILineBreakModeWordWrap' is deprecated: first deprecated in iOS 6.0

Problem with iOS 4.2

Hi, thank you for great lib!

I had problem with running my app on iOS 4.2:
http://stackoverflow.com/questions/11892800/xcode-4-4-build-app-with-arc-for-ios-4-2/12022113#12022113

I discovered that this is because of iRate.

If I add flag -fno-objc-arc to irate.m, everything works good now. Building irate.m with arc not giving error and I lost many hours to regoznise, where was the problem. Maybe you should add some warning or so on?

remindPeriod represented in uses?

Hello,

I have a simple scenario for showing 'rate me' alert.

For the first time I need to present it after 5 launches of the app. This is achieved like this if I'm not mistaken:

[iRate sharedInstance].daysUntilPrompt = 0;
[iRate sharedInstance].usesUntilPrompt = 5;

If user wants to be reminded later, I need to present the alert after 10 uses. According to the docs remindPeriod is represented with days.

Is there a way to achieve the described behaviour?

Thank you

StoreKit opens zoomed in and can't get to the leave review button

I'm adding a storekit view to one of my apps and looked to see how iRate handles things, and there seems to be a bug with storekit on iPhone where it doesn't display everything on the screen. Specifically you cannot scroll down the modal view to get to the button to leave a review. It may be best leaving out storekit from iPhone?

Localisation

Nick,

txs for iRate. I have been paying around with it and it works great. I just can't seem to get the localisation to work. Could you give an example on how to add a language. Language and translation are not important to me but to mechanics of the coding is.

Regards,

Rutger

German Translations are not German!

I don't know where the Translations of iRate for German come from but they are anything but German.

Better Translations would be:
Wenn sie %@ genießen, würde es Ihnen etwas ausmachen, sich die Zeit zu nehmen, um es zu bewerten? Es dauert nicht länger als eine Minute. Vielen Dank für Ihre Unterstützung!

Wenn sie gerne %@ spielen, würde es Ihnen etwas ausmachen, sich die Zeit zu nehmen, um es zu bewerten? Es dauert nicht länger als eine Minute. Vielen Dank für Ihre Unterstützung!