Skip to content
Newer
Older
100644 332 lines (270 sloc) 11.7 KB
4cbab7e Changed license to X11
arashpayan authored
1 /*
2 This file is part of Appirater.
3
9305827 Appirater now requires iOS 4
Arash Payan authored
4 Copyright (c) 2012, Arash Payan
4cbab7e Changed license to X11
arashpayan authored
5 All rights reserved.
6
7 Permission is hereby granted, free of charge, to any person
8 obtaining a copy of this software and associated documentation
9 files (the "Software"), to deal in the Software without
10 restriction, including without limitation the rights to use,
11 copy, modify, merge, publish, distribute, sublicense, and/or sell
12 copies of the Software, and to permit persons to whom the
13 Software is furnished to do so, subject to the following
14 conditions:
e119a75 First commit
arashpayan authored
15
4cbab7e Changed license to X11
arashpayan authored
16 The above copyright notice and this permission notice shall be
17 included in all copies or substantial portions of the Software.
e119a75 First commit
arashpayan authored
18
4cbab7e Changed license to X11
arashpayan authored
19 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
20 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
21 OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
22 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
23 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
24 WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
25 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
26 OTHER DEALINGS IN THE SOFTWARE.
e119a75 First commit
arashpayan authored
27 */
28 /*
29 * Appirater.h
30 * appirater
31 *
32 * Created by Arash Payan on 9/5/09.
33 * http://arashpayan.com
9305827 Appirater now requires iOS 4
Arash Payan authored
34 * Copyright 2012 Arash Payan. All rights reserved.
e119a75 First commit
arashpayan authored
35 */
36
37 #import <Foundation/Foundation.h>
e475e36 added a delegate protocol to let the app know when things happen: ale…
Robert Haining authored
38 #import "AppiraterDelegate.h"
5f82bec @ngreenstein Added optional support for iOS 6's StoreKit to allow rating without l…
ngreenstein authored
39 #import <StoreKit/StoreKit.h>
e119a75 First commit
arashpayan authored
40
3d1fc36 *Multitasking aware and can track when the app is brought into the fo…
Arash Payan authored
41 extern NSString *const kAppiraterFirstUseDate;
42 extern NSString *const kAppiraterUseCount;
43 extern NSString *const kAppiraterSignificantEventCount;
e119a75 First commit
arashpayan authored
44 extern NSString *const kAppiraterCurrentVersion;
45 extern NSString *const kAppiraterRatedCurrentVersion;
46 extern NSString *const kAppiraterDeclinedToRate;
9305827 Appirater now requires iOS 4
Arash Payan authored
47 extern NSString *const kAppiraterReminderRequestDate;
e119a75 First commit
arashpayan authored
48
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
49 /*!
644e655 *Improved Russian translation
Arash Payan authored
50 Your localized app's name.
51 */
c78354a @azone Update Appirater.h
azone authored
52 #define APPIRATER_LOCALIZED_APP_NAME [[[NSBundle mainBundle] localizedInfoDictionary] objectForKey:@"CFBundleDisplayName"]
644e655 *Improved Russian translation
Arash Payan authored
53
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
54 /*!
e119a75 First commit
arashpayan authored
55 Your app's name.
56 */
49f2b82 @IanHoar Fall back to bundle name if bundle display name is null
IanHoar authored
57 #define APPIRATER_APP_NAME APPIRATER_LOCALIZED_APP_NAME ?: [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleDisplayName"] ?: [[[NSBundle mainBundle] infoDictionary] objectForKey:@"CFBundleName"]
e119a75 First commit
arashpayan authored
58
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
59 /*!
e119a75 First commit
arashpayan authored
60 This is the message your users will see once they've passed the day+launches
61 threshold.
62 */
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
63 #define APPIRATER_LOCALIZED_MESSAGE NSLocalizedStringFromTableInBundle(@"If you enjoy using %@, would you mind taking a moment to rate it? It won't take more than a minute. Thanks for your support!", @"AppiraterLocalizable", [Appirater bundle], nil)
9305827 Appirater now requires iOS 4
Arash Payan authored
64 #define APPIRATER_MESSAGE [NSString stringWithFormat:APPIRATER_LOCALIZED_MESSAGE, APPIRATER_APP_NAME]
e119a75 First commit
arashpayan authored
65
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
66 /*!
e119a75 First commit
arashpayan authored
67 This is the title of the message alert that users will see.
68 */
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
69 #define APPIRATER_LOCALIZED_MESSAGE_TITLE NSLocalizedStringFromTableInBundle(@"Rate %@", @"AppiraterLocalizable", [Appirater bundle], nil)
9305827 Appirater now requires iOS 4
Arash Payan authored
70 #define APPIRATER_MESSAGE_TITLE [NSString stringWithFormat:APPIRATER_LOCALIZED_MESSAGE_TITLE, APPIRATER_APP_NAME]
e119a75 First commit
arashpayan authored
71
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
72 /*!
e119a75 First commit
arashpayan authored
73 The text of the button that rejects reviewing the app.
74 */
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
75 #define APPIRATER_CANCEL_BUTTON NSLocalizedStringFromTableInBundle(@"No, Thanks", @"AppiraterLocalizable", [Appirater bundle], nil)
e119a75 First commit
arashpayan authored
76
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
77 /*!
e119a75 First commit
arashpayan authored
78 Text of button that will send user to app review page.
79 */
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
80 #define APPIRATER_LOCALIZED_RATE_BUTTON NSLocalizedStringFromTableInBundle(@"Rate %@", @"AppiraterLocalizable", [Appirater bundle], nil)
9305827 Appirater now requires iOS 4
Arash Payan authored
81 #define APPIRATER_RATE_BUTTON [NSString stringWithFormat:APPIRATER_LOCALIZED_RATE_BUTTON, APPIRATER_APP_NAME]
e119a75 First commit
arashpayan authored
82
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
83 /*!
e119a75 First commit
arashpayan authored
84 Text for button to remind the user to review later.
85 */
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
86 #define APPIRATER_RATE_LATER NSLocalizedStringFromTableInBundle(@"Remind me later", @"AppiraterLocalizable", [Appirater bundle], nil)
e119a75 First commit
arashpayan authored
87
5f82bec @ngreenstein Added optional support for iOS 6's StoreKit to allow rating without l…
ngreenstein authored
88 @interface Appirater : NSObject <UIAlertViewDelegate, SKStoreProductViewControllerDelegate> {
e119a75 First commit
arashpayan authored
89
cc35e15 @meachware Revised to auto dismiss review alert upon will resign active notifica…
meachware authored
90 UIAlertView *ratingAlert;
e119a75 First commit
arashpayan authored
91 }
92
6fa0954 @hpique Convert to ARC
hpique authored
93 @property(nonatomic, strong) UIAlertView *ratingAlert;
a5e39db @arashpayan Fixes #138
authored
94 @property(nonatomic) BOOL openInAppStore;
01c914a @fernandonf Only use "weak" if it's supported by the compiler.
fernandonf authored
95 #if __has_feature(objc_arc_weak)
e475e36 added a delegate protocol to let the app know when things happen: ale…
Robert Haining authored
96 @property(nonatomic, weak) NSObject <AppiraterDelegate> *delegate;
01c914a @fernandonf Only use "weak" if it's supported by the compiler.
fernandonf authored
97 #else
afffeb6 @fernandonf It's unsafe_unretained, not unsafe_unreferenced.
fernandonf authored
98 @property(nonatomic, unsafe_unretained) NSObject <AppiraterDelegate> *delegate;
01c914a @fernandonf Only use "weak" if it's supported by the compiler.
fernandonf authored
99 #endif
cc35e15 @meachware Revised to auto dismiss review alert upon will resign active notifica…
meachware authored
100
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
101 /*!
3d1fc36 *Multitasking aware and can track when the app is brought into the fo…
Arash Payan authored
102 Tells Appirater that the app has launched, and on devices that do NOT
103 support multitasking, the 'uses' count will be incremented. You should
104 call this method at the end of your application delegate's
105 application:didFinishLaunchingWithOptions: method.
106
107 If the app has been used enough to be rated (and enough significant events),
108 you can suppress the rating alert
109 by passing NO for canPromptForRating. The rating alert will simply be postponed
110 until it is called again with YES for canPromptForRating. The rating alert
111 can also be triggered by appEnteredForeground: and userDidSignificantEvent:
112 (as long as you pass YES for canPromptForRating in those methods).
113 */
114 + (void)appLaunched:(BOOL)canPromptForRating;
115
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
116 /*!
3d1fc36 *Multitasking aware and can track when the app is brought into the fo…
Arash Payan authored
117 Tells Appirater that the app was brought to the foreground on multitasking
118 devices. You should call this method from the application delegate's
119 applicationWillEnterForeground: method.
120
121 If the app has been used enough to be rated (and enough significant events),
122 you can suppress the rating alert
123 by passing NO for canPromptForRating. The rating alert will simply be postponed
124 until it is called again with YES for canPromptForRating. The rating alert
125 can also be triggered by appLaunched: and userDidSignificantEvent:
126 (as long as you pass YES for canPromptForRating in those methods).
127 */
128 + (void)appEnteredForeground:(BOOL)canPromptForRating;
129
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
130 /*!
3d1fc36 *Multitasking aware and can track when the app is brought into the fo…
Arash Payan authored
131 Tells Appirater that the user performed a significant event. A significant
132 event is whatever you want it to be. If you're app is used to make VoIP
133 calls, then you might want to call this method whenever the user places
134 a call. If it's a game, you might want to call this whenever the user
135 beats a level boss.
136
137 If the user has performed enough significant events and used the app enough,
138 you can suppress the rating alert by passing NO for canPromptForRating. The
139 rating alert will simply be postponed until it is called again with YES for
140 canPromptForRating. The rating alert can also be triggered by appLaunched:
141 and appEnteredForeground: (as long as you pass YES for canPromptForRating
142 in those methods).
143 */
144 + (void)userDidSignificantEvent:(BOOL)canPromptForRating;
145
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
146 /*!
371ffa3 @phest more control to show prompt
phest authored
147 Tells Appirater to try and show the prompt (a rating alert). The prompt will be showed
881815a @amjaliks Explicite prompt won't be showed, if user has declined to rate the app.
amjaliks authored
148 if there is connection available, the user hasn't declined to rate
149 or hasn't rated current version.
b3f15ab @amjaliks Added call to show the prompt (the rating alert) explicitly.
amjaliks authored
150
151 You could call to show the prompt regardless Appirater settings,
152 e.g., in case of some special event in your app.
153 */
371ffa3 @phest more control to show prompt
phest authored
154 + (void)tryToShowPrompt;
155
156 /*!
157 Tells Appirater to show the prompt (a rating alert).
158 Similar to tryToShowPrompt, but without checks (the prompt is always displayed).
159 Passing false will hide the rate later button on the prompt.
160
161 The only case where you should call this is if your app has an
162 explicit "Rate this app" command somewhere. This is similar to rateApp,
163 but instead of jumping to the review directly, an intermediary prompt is displayed.
164 */
165 + (void)forceShowPrompt:(BOOL)displayRateLaterButton;
b3f15ab @amjaliks Added call to show the prompt (the rating alert) explicitly.
amjaliks authored
166
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
167 /*!
c640665 @mmorearty Refactor so there is a new rateApp method to explicitly rate the app.
mmorearty authored
168 Tells Appirater to open the App Store page where the user can specify a
169 rating for the app. Also records the fact that this has happened, so the
170 user won't be prompted again to rate the app.
171
172 The only case where you should call this directly is if your app has an
173 explicit "Rate this app" command somewhere. In all other cases, don't worry
174 about calling this -- instead, just call the other functions listed above,
175 and let Appirater handle the bookkeeping of deciding when to ask the user
176 whether to rate the app.
177 */
178 + (void)rateApp;
179
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
180 /*!
d7b529d @ngreenstein Added API method to close open modals.
ngreenstein authored
181 Tells Appirater to immediately close any open rating modals (e.g. StoreKit rating VCs).
182 */
183 + (void)closeModal;
184
25feefd @josejulio Exposes informative methods about the rating.
josejulio authored
185 /*!
186 Asks Appirater if the user has declined to rate;
187 */
188 - (BOOL)userHasDeclinedToRate;
189
190 /*!
191 Asks Appirater if the user has rated the current version.
fd3c1d9 @josejulio Update Appirater.h
josejulio authored
192 Note that this is not a guarantee that the user has actually rated the app in the
193 app store, but they've just clicked the rate button on the Appirater dialog.
25feefd @josejulio Exposes informative methods about the rating.
josejulio authored
194 */
195 - (BOOL)userHasRatedCurrentVersion;
196
e119a75 First commit
arashpayan authored
197 @end
f452be6 @hpique Mark appLaunched as deprecated
hpique authored
198
96dbd13 @hpique Dynamic configuration
hpique authored
199 @interface Appirater(Configuration)
200
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
201 /*!
96dbd13 @hpique Dynamic configuration
hpique authored
202 Set your Apple generated software id here.
203 */
204 + (void) setAppId:(NSString*)appId;
205
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
206 /*!
96dbd13 @hpique Dynamic configuration
hpique authored
207 Users will need to have the same version of your app installed for this many
208 days before they will be prompted to rate it.
209 */
210 + (void) setDaysUntilPrompt:(double)value;
211
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
212 /*!
96dbd13 @hpique Dynamic configuration
hpique authored
213 An example of a 'use' would be if the user launched the app. Bringing the app
214 into the foreground (on devices that support it) would also be considered
215 a 'use'. You tell Appirater about these events using the two methods:
216 [Appirater appLaunched:]
217 [Appirater appEnteredForeground:]
218
219 Users need to 'use' the same version of the app this many times before
220 before they will be prompted to rate it.
221 */
222 + (void) setUsesUntilPrompt:(NSInteger)value;
223
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
224 /*!
96dbd13 @hpique Dynamic configuration
hpique authored
225 A significant event can be anything you want to be in your app. In a
226 telephone app, a significant event might be placing or receiving a call.
227 In a game, it might be beating a level or a boss. This is just another
228 layer of filtering that can be used to make sure that only the most
229 loyal of your users are being prompted to rate you on the app store.
92e43c0 @brow fix usage error in comment
brow authored
230 If you leave this at a value of -1, then this won't be a criterion
96dbd13 @hpique Dynamic configuration
hpique authored
231 used for rating. To tell Appirater that the user has performed
232 a significant event, call the method:
233 [Appirater userDidSignificantEvent:];
234 */
235 + (void) setSignificantEventsUntilPrompt:(NSInteger)value;
236
237
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
238 /*!
96dbd13 @hpique Dynamic configuration
hpique authored
239 Once the rating alert is presented to the user, they might select
240 'Remind me later'. This value specifies how long (in days) Appirater
241 will wait before reminding them.
242 */
243 + (void) setTimeBeforeReminding:(double)value;
244
6cea4e3 @Elethom Add comment
Elethom authored
245 /*!
246 Set customized title for alert view.
247 */
34f2209 @Elethom Make alert customizable
Elethom authored
248 + (void) setCustomAlertTitle:(NSString *)title;
6cea4e3 @Elethom Add comment
Elethom authored
249
250 /*!
251 Set customized message for alert view.
252 */
34f2209 @Elethom Make alert customizable
Elethom authored
253 + (void) setCustomAlertMessage:(NSString *)message;
6cea4e3 @Elethom Add comment
Elethom authored
254
255 /*!
256 Set customized cancel button title for alert view.
257 */
34f2209 @Elethom Make alert customizable
Elethom authored
258 + (void) setCustomAlertCancelButtonTitle:(NSString *)cancelTitle;
6cea4e3 @Elethom Add comment
Elethom authored
259
260 /*!
261 Set customized rate button title for alert view.
262 */
34f2209 @Elethom Make alert customizable
Elethom authored
263 + (void) setCustomAlertRateButtonTitle:(NSString *)rateTitle;
6cea4e3 @Elethom Add comment
Elethom authored
264
265 /*!
266 Set customized rate later button title for alert view.
267 */
34f2209 @Elethom Make alert customizable
Elethom authored
268 + (void) setCustomAlertRateLaterButtonTitle:(NSString *)rateLaterTitle;
269
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
270 /*!
96dbd13 @hpique Dynamic configuration
hpique authored
271 'YES' will show the Appirater alert everytime. Useful for testing how your message
272 looks and making sure the link to your app's review page works.
273 */
274 + (void) setDebug:(BOOL)debug;
275
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
276 /*!
e475e36 added a delegate protocol to let the app know when things happen: ale…
Robert Haining authored
277 Set the delegate if you want to know when Appirater does something
278 */
279 + (void)setDelegate:(id<AppiraterDelegate>)delegate;
280
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
281 /*!
e158942 @ngreenstein Added config option for disabling animation (used in StoreKit views) …
ngreenstein authored
282 Set whether or not Appirater uses animation (currently respected when pushing modal StoreKit rating VCs).
283 */
284 + (void)setUsesAnimation:(BOOL)animation;
285
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
286 /*!
f2cce47 @arashpayan Fixes #194 (Typo in doc for setOpenInAppStore)
authored
287 If set to YES, Appirater will open App Store link (instead of SKStoreProductViewController on iOS 6). Default YES.
8669605 @amjaliks Added option to force Appirater always to open App Store (instead of …
amjaliks authored
288 */
289 + (void)setOpenInAppStore:(BOOL)openInAppStore;
290
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
291 /*!
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
292 If set to YES, the main bundle will always be used to load localized strings.
293 Set this to YES if you have provided your own custom localizations in AppiraterLocalizable.strings
294 in your main bundle. Default is NO.
295 */
296 + (void)setAlwaysUseMainBundle:(BOOL)useMainBundle;
297
96dbd13 @hpique Dynamic configuration
hpique authored
298 @end
299
300
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
301 /*!
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
302 Methods in this interface are public out of necessity, but may change without notice
303 */
304 @interface Appirater(Unsafe)
305
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
306 /*!
cc127a1 @eager Move localized strings to Appirater.bundle when using CocoaPods
eager authored
307 The bundle localized strings will be loaded from.
308 */
309 +(NSBundle *)bundle;
310
311 @end
312
f452be6 @hpique Mark appLaunched as deprecated
hpique authored
313 @interface Appirater(Deprecated)
314
a836536 @nirajignited Made the header Xcode 5 documentation-friendly
nirajignited authored
315 /*!
f452be6 @hpique Mark appLaunched as deprecated
hpique authored
316 DEPRECATED: While still functional, it's better to use
317 appLaunched:(BOOL)canPromptForRating instead.
318
319 Calls [Appirater appLaunched:YES]. See appLaunched: for details of functionality.
320 */
321 + (void)appLaunched __attribute__((deprecated));
322
371ffa3 @phest more control to show prompt
phest authored
323 /*!
324 DEPRECATED: While still functional, it's better to use
325 tryToShowPrompt instead.
326
327 Calls [Appirater tryToShowPrompt]. See tryToShowPrompt for details of functionality.
328 */
329 + (void)showPrompt __attribute__((deprecated));
330
f452be6 @hpique Mark appLaunched as deprecated
hpique authored
331 @end
Something went wrong with that request. Please try again.