PushNotificationManager.h 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451
  1. //
  2. // PushNotificationManager.h
  3. // Pushwoosh SDK
  4. // (c) Pushwoosh 2014
  5. //
  6. #import <Foundation/Foundation.h>
  7. #import <UIKit/UIKit.h>
  8. #import <StoreKit/StoreKit.h>
  9. @class PushNotificationManager;
  10. @class CLLocation;
  11. typedef void (^PushwooshGetTagsHandler)(NSDictionary *tags);
  12. typedef void (^PushwooshErrorHandler)(NSError *error);
  13. /**
  14. `PushNotificationDelegate` protocol defines the methods that can be implemented in the delegate of the `PushNotificationManager` class' singleton object.
  15. These methods provide information about the key events for push notification manager such as registering with APS services, receiving push notifications or working with the received notification.
  16. These methods implementation allows to react on these events properly.
  17. */
  18. @protocol PushNotificationDelegate
  19. @optional
  20. /**
  21. Tells the delegate that the application has registered with Apple Push Service (APS) successfully.
  22. @param token A token used for identifying the device with APS.
  23. */
  24. - (void)onDidRegisterForRemoteNotificationsWithDeviceToken:(NSString *)token;
  25. /**
  26. Sent to the delegate when Apple Push Service (APS) could not complete the registration process successfully.
  27. @param error An NSError object encapsulating the information about the reason of the registration failure. Within this method you can define application's behaviour in case of registration failure.
  28. */
  29. - (void)onDidFailToRegisterForRemoteNotificationsWithError:(NSError *)error;
  30. /**
  31. Tells the delegate that the push manager has received a remote notification.
  32. If this method is implemented `onPushAccepted:withNotification:` will not be called, internal message boxes will not be displayed.
  33. @param pushManager The push manager that received the remote notification.
  34. @param pushNotification A dictionary that contains information referring to the remote notification, potentially including a badge number for the application icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data.
  35. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
  36. @param onStart If the application was not active when the push notification was received, the application will be launched with this parameter equal to `YES`, otherwise the parameter will be `NO`.
  37. */
  38. - (void)onPushReceived:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification onStart:(BOOL)onStart;
  39. /**
  40. Tells the delegate that the user has pressed OK on the push notification.
  41. IMPORTANT: This method is used for backwards compatibility and is deprecated. Please use the `onPushAccepted:withNotification:onStart:` method instead
  42. @param pushManager The push manager that received the remote notification.
  43. @param pushNotification A dictionary that contains information referring to the remote notification, potentially including a badge number for the application icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data.
  44. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
  45. Push dictionary sample:
  46. {
  47. aps = {
  48. alert = "Some text.";
  49. sound = default;
  50. };
  51. p = 1pb;
  52. }
  53. */
  54. - (void)onPushAccepted:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification;
  55. /**
  56. Tells the delegate that the user has pressed OK on the push notification.
  57. @param pushManager The push manager that received the remote notification.
  58. @param pushNotification A dictionary that contains information about the remote notification, potentially including a badge number for the application icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data.
  59. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
  60. Push dictionary sample:
  61. {
  62. aps = {
  63. alert = "Some text.";
  64. sound = default;
  65. };
  66. p = 1pb;
  67. }
  68. @param onStart If the application was not active when the push notification was received, the application will be launched with this parameter equal to `YES`, otherwise the parameter will be `NO`.
  69. */
  70. - (void)onPushAccepted:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification onStart:(BOOL)onStart;
  71. /**
  72. Tells the delegate that the push manager has received tags from the server.
  73. @param tags Dictionary representation of received tags.
  74. Dictionary example:
  75. {
  76. Country = ru;
  77. Language = ru;
  78. }
  79. */
  80. - (void)onTagsReceived:(NSDictionary *)tags;
  81. /**
  82. Sent to the delegate when push manager could not complete the tags receiving process successfully.
  83. @param error An NSError object that encapsulates information why receiving tags did not succeed.
  84. */
  85. - (void)onTagsFailedToReceive:(NSError *)error;
  86. /**
  87. Tells the delegate that In-App with specified code has been closed
  88. @param code In-App code
  89. */
  90. - (void)onInAppClosed:(NSString *)code;
  91. /**
  92. Tells the delegate that In-App with specified code has been displayed
  93. @param code In-App code
  94. */
  95. - (void)onInAppDisplayed:(NSString *)code;
  96. @end
  97. /**
  98. `PWTags` class encapsulates the methods for creating tags parameters for sending them to the server.
  99. */
  100. @interface PWTags : NSObject
  101. /**
  102. Creates a dictionary for incrementing/decrementing a numeric tag on the server.
  103. Example:
  104. NSDictionary *tags = [NSDictionary dictionaryWithObjectsAndKeys:
  105. aliasField.text, @"Alias",
  106. [NSNumber numberWithInt:[favNumField.text intValue]], @"FavNumber",
  107. [PWTags incrementalTagWithInteger:5], @"price",
  108. nil];
  109. [[PushNotificationManager pushManager] setTags:tags];
  110. @param delta Difference that needs to be applied to the tag's counter.
  111. @return Dictionary, that needs to be sent as the value for the tag
  112. */
  113. + (NSDictionary *)incrementalTagWithInteger:(NSInteger)delta;
  114. @end
  115. /**
  116. `PushNotificationManager` class offers access to the singletone-instance of the push manager responsible for registering the device with the APS servers, receiving and processing push notifications.
  117. */
  118. @interface PushNotificationManager : NSObject {
  119. }
  120. /**
  121. Pushwoosh Application ID. Usually retrieved automatically from Info.plist parameter `Pushwoosh_APPID`
  122. */
  123. @property (nonatomic, copy, readonly) NSString *appCode;
  124. /**
  125. Application name. Usually retrieved automatically from Info.plist bundle name (CFBundleDisplayName). Could be used to override bundle name. In addition could be set in Info.plist as `Pushwoosh_APPNAME` parameter.
  126. */
  127. @property (nonatomic, copy, readonly) NSString *appName;
  128. /**
  129. `PushNotificationDelegate` protocol delegate that would receive the information about events for push notification manager such as registering with APS services, receiving push notifications or working with the received notification.
  130. Pushwoosh Runtime sets it to ApplicationDelegate by default
  131. */
  132. @property (nonatomic, weak) NSObject<PushNotificationDelegate> *delegate;
  133. /**
  134. Show push notifications alert when push notification is received while the app is running, default is `YES`
  135. */
  136. @property (nonatomic, assign) BOOL showPushnotificationAlert;
  137. /**
  138. Returns push notification payload if the app was started in response to push notification or null otherwise
  139. */
  140. @property (nonatomic, copy, readonly) NSDictionary *launchNotification;
  141. /**
  142. Initializes PushNotificationManager. Usually called by Pushwoosh Runtime internally.
  143. @param appcCode Pushwoosh App ID.
  144. @param appName Application name.
  145. */
  146. + (void)initializeWithAppCode:(NSString *)appCode appName:(NSString *)appName;
  147. /**
  148. Returns an object representing the current push manager.
  149. @return A singleton object that represents the push manager.
  150. */
  151. + (PushNotificationManager *)pushManager;
  152. /**
  153. Registers for push notifications. By default registeres for "UIRemoteNotificationTypeBadge | UIRemoteNotificationTypeSound | UIRemoteNotificationTypeAlert" flags.
  154. Automatically detects if you have "newsstand-content" in "UIBackgroundModes" and adds "UIRemoteNotificationTypeNewsstandContentAvailability" flag.
  155. */
  156. - (void)registerForPushNotifications;
  157. /**
  158. Unregisters from push notifications. You should call this method in rare circumstances only, such as when a new version of the app drops support for remote notifications. Users can temporarily prevent apps from receiving remote notifications through the Notifications section of the Settings app. Apps unregistered through this method can always re-register.
  159. */
  160. - (void)unregisterForPushNotifications;
  161. - (instancetype)initWithApplicationCode:(NSString *)appCode appName:(NSString *)appName;
  162. - (id)initWithApplicationCode:(NSString *)appCode navController:(UIViewController *)navController appName:(NSString *)appName __attribute__((deprecated));
  163. /**
  164. Sends geolocation to the server for GeoFencing push technology. Called internally, please use `startLocationTracking` and `stopLocationTracking` functions.
  165. @param location Location to be sent.
  166. */
  167. - (void)sendLocation:(CLLocation *)location;
  168. /**
  169. Start location tracking.
  170. */
  171. - (void)startLocationTracking;
  172. /**
  173. Stops location tracking
  174. */
  175. - (void)stopLocationTracking;
  176. /**
  177. Send tags to server. Tag names have to be created in the Pushwoosh Control Panel. Possible tag types: Integer, String, Incremental (integer only), List tags (array of values).
  178. Example:
  179. NSDictionary *tags = [NSDictionary dictionaryWithObjectsAndKeys:
  180. aliasField.text, @"Alias",
  181. [NSNumber numberWithInt:[favNumField.text intValue]], @"FavNumber",
  182. [PWTags incrementalTagWithInteger:5], @"price",
  183. [NSArray arrayWithObjects:@"Item1", @"Item2", @"Item3", nil], @"List",
  184. nil];
  185. [[PushNotificationManager pushManager] setTags:tags];
  186. @param tags Dictionary representation of tags to send.
  187. */
  188. - (void)setTags:(NSDictionary *)tags;
  189. /**
  190. Send tags to server with completion block. If setTags succeeds competion is called with nil argument. If setTags fails completion is called with error.
  191. */
  192. - (void)setTags:(NSDictionary *)tags withCompletion:(void (^)(NSError *error))completion;
  193. /**
  194. Get tags from the server. Calls delegate method `onTagsReceived:` or `onTagsFailedToReceive:` depending on the results.
  195. */
  196. - (void)loadTags;
  197. /**
  198. Get tags from server. Calls delegate method if exists and handler (block).
  199. @param successHandler The block is executed on the successful completion of the request. This block has no return value and takes one argument: the dictionary representation of the recieved tags.
  200. Example of the dictionary representation of the received tags:
  201. {
  202. Country = ru;
  203. Language = ru;
  204. }
  205. @param errorHandler The block is executed on the unsuccessful completion of the request. This block has no return value and takes one argument: the error that occurred during the request.
  206. */
  207. - (void)loadTags:(PushwooshGetTagsHandler)successHandler error:(PushwooshErrorHandler)errorHandler;
  208. /**
  209. Informs the Pushwoosh about the app being launched. Usually called internally by SDK Runtime.
  210. */
  211. - (void)sendAppOpen;
  212. /**
  213. Sends current badge value to server. Called internally by SDK Runtime when `UIApplication` `setApplicationBadgeNumber:` is set. This function is used for "auto-incremeting" badges to work.
  214. This way Pushwoosh server can know what current badge value is set for the application.
  215. @param badge Current badge value.
  216. */
  217. - (void)sendBadges:(NSInteger)badge;
  218. /**
  219. Sends in-app purchases to Pushwoosh. Use in paymentQueue:updatedTransactions: payment queue method (see example).
  220. Example:
  221. - (void)paymentQueue:(SKPaymentQueue *)queue updatedTransactions:(NSArray *)transactions {
  222. [[PushNotificationManager pushManager] sendSKPaymentTransactions:transactions];
  223. }
  224. @param transactions Array of SKPaymentTransaction items as received in the payment queue.
  225. */
  226. - (void)sendSKPaymentTransactions:(NSArray *)transactions;
  227. /**
  228. Tracks individual in-app purchase. See recommended `sendSKPaymentTransactions:` method.
  229. @param productIdentifier purchased product ID
  230. @param price price for the product
  231. @param currencyCode currency of the price (ex: @"USD")
  232. @param date time of the purchase (ex: [NSDate now])
  233. */
  234. - (void)sendPurchase:(NSString *)productIdentifier withPrice:(NSDecimalNumber *)price currencyCode:(NSString *)currencyCode andDate:(NSDate *)date;
  235. /**
  236. Gets current push token.
  237. @return Current push token. May be nil if no push token is available yet.
  238. */
  239. - (NSString *)getPushToken;
  240. /**
  241. Gets HWID. Unique device identifier that used in all API calls with Pushwoosh.
  242. This is identifierForVendor for iOS >= 7.
  243. @return Unique device identifier.
  244. */
  245. - (NSString *)getHWID;
  246. - (void)handlePushRegistration:(NSData *)devToken;
  247. - (void)handlePushRegistrationString:(NSString *)deviceID;
  248. //internal
  249. - (void)handlePushRegistrationFailure:(NSError *)error;
  250. //if the push is received while the app is running. internal
  251. - (BOOL)handlePushReceived:(NSDictionary *)userInfo;
  252. /**
  253. Gets APN payload from push notifications dictionary.
  254. Example:
  255. - (void) onPushAccepted:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification onStart:(BOOL)onStart {
  256. NSDictionary * apnPayload = [[PushNotificationsManager pushManager] getApnPayload:pushNotification];
  257. NSLog(@"%@", apnPayload);
  258. }
  259. For Push dictionary sample:
  260. {
  261. aps = {
  262. alert = "Some text.";
  263. sound = default;
  264. };
  265. p = 1pb;
  266. }
  267. Result is:
  268. {
  269. alert = "Some text.";
  270. sound = default;
  271. };
  272. @param pushNotification Push notifications dictionary as received in `onPushAccepted: withNotification: onStart:`
  273. */
  274. - (NSDictionary *)getApnPayload:(NSDictionary *)pushNotification;
  275. /**
  276. Gets custom JSON string data from push notifications dictionary as specified in Pushwoosh Control Panel.
  277. Example:
  278. - (void) onPushAccepted:(PushNotificationManager *)pushManager withNotification:(NSDictionary *)pushNotification onStart:(BOOL)onStart {
  279. NSString * customData = [[PushNotificationsManager pushManager] getCustomPushData:pushNotification];
  280. NSLog(@"%@", customData);
  281. }
  282. @param pushNotification Push notifications dictionary as received in `onPushAccepted: withNotification: onStart:`
  283. */
  284. - (NSString *)getCustomPushData:(NSDictionary *)pushNotification;
  285. /**
  286. The same as getCustomPushData but returns NSDictionary rather than JSON string (converts JSON string into NSDictionary).
  287. */
  288. - (NSDictionary *)getCustomPushDataAsNSDict:(NSDictionary *)pushNotification;
  289. /**
  290. Returns dictionary with enabled remove notificaton types.
  291. Example enabled push:
  292. {
  293. enabled = 1;
  294. pushAlert = 1;
  295. pushBadge = 1;
  296. pushSound = 1;
  297. type = 7;
  298. }
  299. where "type" field is UIUserNotificationType
  300. Disabled push:
  301. {
  302. enabled = 1;
  303. pushAlert = 0;
  304. pushBadge = 0;
  305. pushSound = 0;
  306. type = 0;
  307. }
  308. Note: In the latter example "enabled" field means that device can receive push notification but could not display alerts (ex: silent push)
  309. */
  310. + (NSMutableDictionary *)getRemoteNotificationStatus;
  311. /**
  312. Clears the notifications from the notification center.
  313. */
  314. + (void)clearNotificationCenter;
  315. /**
  316. Set User indentifier. This could be Facebook ID, username or email, or any other user ID.
  317. This allows data and events to be matched across multiple user devices.
  318. */
  319. - (void)setUserId:(NSString *)userId;
  320. /**
  321. Move all events from oldUserId to newUserId if doMerge is true. If doMerge is false all events for oldUserId are removed.
  322. @param oldUserId source user
  323. @param newUserId destination user
  324. @param doMerge if false all events for oldUserId are removed, if true all events for oldUserId are moved to newUserId
  325. @param completeion callback
  326. */
  327. - (void)mergeUserId:(NSString *)oldUserId to:(NSString *)newUserId doMerge:(BOOL)doMerge completion:(void (^)(NSError *error))completion;
  328. /**
  329. Post events for In-App Messages. This can trigger In-App message display as specified in Pushwoosh Control Panel.
  330. Example:
  331. [[PushNotificationManager pushManager] setUserId:@"96da2f590cd7246bbde0051047b0d6f7"];
  332. [[PushNotificationManager pushManager] postEvent:@"buttonPressed" withAttributes:@{ @"buttonNumber" : @"4", @"buttonLabel" : @"Banner" } completion:nil];
  333. @param event name of the event
  334. @param attributes NSDictionary of event attributes
  335. @param completion function to call after posting event
  336. */
  337. - (void)postEvent:(NSString *)event withAttributes:(NSDictionary *)attributes completion:(void (^)(NSError *error))completion;
  338. /**
  339. See `postEvent:withAttributes:completion:`
  340. */
  341. - (void)postEvent:(NSString *)event withAttributes:(NSDictionary *)attributes;
  342. @end