Completion blocks for various calls (#17)

* add onSuccess and onFailure block params to functions that call Iterable API

* add additional overload for trackPushOpen

* update changelog

Author: dontgitit

CHANGELOG.md

@@ -4,7 +4,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 #### Added
-- nothing yet
+- completion handler blocks for all the Iterable APIs
 
 #### Removed
 - nothing yet

Iterable-iOS-SDK/IterableAPI.h

@@ -133,6 +133,25 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
  */
 - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform;
 
+/*!
+ @method
+ 
+ @abstract Register this device's token with Iterable with custom completion blocks
+ 
+ @param token                   The token representing this device/application pair, obtained from
+                                `application:didRegisterForRemoteNotificationsWithDeviceToken`
+                                after registering for remote notifications
+ @param appName                 The application name, as configured in Iterable during set up of the push integration
+ @param pushServicePlatform     The PushServicePlatform to use for this device; dictates whether to register this token in the sandbox or production environment
+ @param onSuccess               OnSuccessHandler to invoke if token registration is successful
+ @param onFailure               OnFailureHandler to invoke if token registration fails
+ 
+ @see PushServicePlatform
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
 /////////////////////////
 /// @name Tracking events
 /////////////////////////
@@ -154,7 +173,7 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
 /*!
  @method
  
- @abstract Tracks a purchase
+ @abstract Tracks a purchase with additional data
  
  @discussion Pass in the total purchase amount and an `NSArray` of `CommerceItem`s
  
@@ -169,7 +188,26 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
 /*!
  @method
  
- @abstract Tracks a pushOpen event.
+ @abstract Tracks a purchase with additional data and custom completion blocks
+ 
+ @discussion Pass in the total purchase amount and an `NSArray` of `CommerceItem`s
+ 
+ @param total       total purchase amount
+ @param items       list of purchased items
+ @param dataFields  an `NSDictionary` containing any additional information to save along with the event
+ @param onSuccess   OnSuccessHandler to invoke if the purchase is tracked successfully
+ @param onFailure   OnFailureHandler to invoke if tracking the purchase fails
+ 
+ @see CommerceItem
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)trackPurchase:(NSNumber *)total items:(NSArray<CommerceItem>*)items dataFields:(nullable NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
+/*!
+ @method
+ 
+ @abstract Tracks a pushOpen event with a push notification payload
  
  @discussion Pass in the `userInfo` from the push notification payload
  
@@ -180,7 +218,7 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
 /*!
  @method
  
- @abstract Tracks a pushOpen event.
+ @abstract Tracks a pushOpen event with a push notification and optional additional data
  
  @discussion Pass in the `userInfo` from the push notification payload
  
@@ -192,7 +230,24 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
 /*!
  @method
  
- @abstract Tracks a pushOpen event
+ @abstract Tracks a pushOpen event with a push notification, optional additional data, and custom completion blocks
+ 
+ @discussion Pass in the `userInfo` from the push notification payload
+ 
+ @param userInfo    the push notification payload
+ @param dataFields  an `NSDictionary` containing any additional information to save along with the event
+ @param onSuccess           OnSuccessHandler to invoke if the open is tracked successfully
+ @param onFailure           OnFailureHandler to invoke if tracking the open fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)trackPushOpen:(NSDictionary *)userInfo dataFields:(nullable NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
+/*!
+ @method
+ 
+ @abstract Tracks a pushOpen event for the specified campaign and template ids, whether the app was already running when the push was received, and optional additional data
  
  @discussion Pass in the the relevant campaign data
  
@@ -201,7 +256,26 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
  @param appAlreadyRunning   This will get merged into the dataFields. Whether the app is already running when the notification was received
  @param dataFields          An `NSDictionary` containing any additional information to save along with the event
  */
-- (void)trackPushOpen:(NSNumber *)campaignId templateId:(NSNumber *)templateId appAlreadyRunning:(BOOL)appAlreadyRunning dataFields:(NSDictionary *)dataFields;
+- (void)trackPushOpen:(NSNumber *)campaignId templateId:(NSNumber *)templateId appAlreadyRunning:(BOOL)appAlreadyRunning dataFields:(nullable NSDictionary *)dataFields;
+
+/*!
+ @method
+ 
+ @abstract Tracks a pushOpen event for the specified campaign and template ids, whether the app was already running when the push was received, and optional additional data, with custom completion blocks
+ 
+ @discussion Pass in the the relevant campaign data
+ 
+ @param campaignId          The campaignId of the the push notification that caused this open event
+ @param templateId          The templateId  of the the push notification that caused this open event
+ @param appAlreadyRunning   This will get merged into the dataFields. Whether the app is already running when the notification was received
+ @param dataFields          An `NSDictionary` containing any additional information to save along with the event
+ @param onSuccess           OnSuccessHandler to invoke if the open is tracked successfully
+ @param onFailure           OnFailureHandler to invoke if tracking the open fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)trackPushOpen:(NSNumber *)campaignId templateId:(NSNumber *)templateId appAlreadyRunning:(BOOL)appAlreadyRunning dataFields:(nullable NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
 
 /*!
  @method
@@ -217,7 +291,7 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
 /*!
  @method
  
- @abstract Tracks a custom event.
+ @abstract Tracks a custom event with optional additional fields
  
  @discussion Pass in the the custom event data.
  
@@ -226,6 +300,23 @@ typedef NS_ENUM(NSInteger, PushServicePlatform) {
  */
 - (void)track:(NSString *)eventName dataFields:(nullable NSDictionary *)dataFields;
 
+/*!
+ @method
+ 
+ @abstract Tracks a custom event with optional additional fields and custom completion blocks
+ 
+ @discussion Pass in the the custom event data.
+ 
+ @param eventName   Name of the event
+ @param dataFields  An `NSDictionary` containing any additional information to save along with the event
+ @param onSuccess   OnSuccessHandler to invoke if the track call succeeds
+ @param onFailure   OnFailureHandler to invoke if the track call fails
+ 
+ @see OnSuccessHandler
+ @see OnFailureHandler
+ */
+- (void)track:(NSString *)eventName dataFields:(nullable NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure;
+
 @end
 
 NS_ASSUME_NONNULL_END

Iterable-iOS-SDK/IterableAPI.m

@@ -301,6 +301,12 @@ + (IterableAPI *)sharedInstanceWithApiKey:(NSString *)apiKey andEmail:(NSString
 
 // documented in IterableAPI.h
 - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform
+{
+    [self registerToken:token appName:appName pushServicePlatform:pushServicePlatform onSuccess:[IterableAPI defaultOnSuccess:@"registerToken"] onFailure:[IterableAPI defaultOnFailure:@"registerToken"]];
+}
+
+// documented in IterableAPI.h
+- (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePlatform:(PushServicePlatform)pushServicePlatform onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
 {
     NSString *hexToken = [token hexadecimalString];
 
@@ -334,7 +340,7 @@ - (void)registerToken:(NSData *)token appName:(NSString *)appName pushServicePla
                                };
         LogDebug(@"sending registerToken request with args %@", args);
         NSURLRequest *request = [self createRequestForAction:@"users/registerDeviceToken" withArgs:args];
-        [self sendRequest:request onSuccess:[IterableAPI defaultOnSuccess:@"registerToken"] onFailure:[IterableAPI defaultOnFailure:@"registerToken"]];
+        [self sendRequest:request onSuccess:onSuccess onFailure:onFailure];
     }
 }
 
@@ -346,6 +352,12 @@ - (void)track:(NSString *)eventName
 
 // documented in IterableAPI.h
 - (void)track:(NSString *)eventName dataFields:(NSDictionary *)dataFields
+{
+    [self track:eventName dataFields:dataFields onSuccess:[IterableAPI defaultOnSuccess:@"track"] onFailure:[IterableAPI defaultOnFailure:@"track"]];
+}
+
+// documented in IterableAPI.h
+- (void)track:(NSString *)eventName dataFields:(NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
 {
     NSDictionary *args;
     if (dataFields) {
@@ -363,7 +375,7 @@ - (void)track:(NSString *)eventName dataFields:(NSDictionary *)dataFields
 
     }
     NSURLRequest *request = [self createRequestForAction:@"events/track" withArgs:args];
-    [self sendRequest:request onSuccess:[IterableAPI defaultOnSuccess:@"track"] onFailure:[IterableAPI defaultOnFailure:@"track"]];
+    [self sendRequest:request onSuccess:onSuccess onFailure:onFailure];
 }
 
 // documented in IterableAPI.h
@@ -374,21 +386,35 @@ - (void)trackPushOpen:(NSDictionary *)userInfo
 
 // documented in IterableAPI.h
 - (void)trackPushOpen:(NSDictionary *)userInfo dataFields:(NSDictionary *)dataFields
+{
+    [self trackPushOpen:userInfo dataFields:dataFields onSuccess:[IterableAPI defaultOnSuccess:@"trackPushOpen"] onFailure:[IterableAPI defaultOnFailure:@"trackPushOpen"]];
+}
+
+// documented in IterableAPI.h
+- (void)trackPushOpen:(NSDictionary *)userInfo dataFields:(NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
 {
     LogDebug(@"tracking push open");
 
     if (userInfo && userInfo[@"itbl"]) {
         NSDictionary *pushData = userInfo[@"itbl"];
         if ([pushData isKindOfClass:[NSDictionary class]] && pushData[@"campaignId"] && pushData[@"templateId"]) {
-            [self trackPushOpen:pushData[@"campaignId"] templateId:pushData[@"templateId"] appAlreadyRunning:false dataFields:dataFields];
+            [self trackPushOpen:pushData[@"campaignId"] templateId:pushData[@"templateId"] appAlreadyRunning:false dataFields:dataFields onSuccess:onSuccess onFailure:onFailure];
         } else {
-            LogError(@"error tracking push open");
+            if (onFailure) {
+                onFailure(@"Not tracking push open - payload is not an Iterable notification", [[NSData alloc] init]);
+            }
         }
     }
 }
 
 // documented in IterableAPI.h
 - (void)trackPushOpen:(NSNumber *)campaignId templateId:(NSNumber *)templateId appAlreadyRunning:(BOOL)appAlreadyRunning dataFields:(NSDictionary *)dataFields
+{
+    [self trackPushOpen:campaignId templateId:templateId appAlreadyRunning:appAlreadyRunning dataFields:dataFields onSuccess:[IterableAPI defaultOnSuccess:@"trackPushOpen"] onFailure:[IterableAPI defaultOnFailure:@"trackPushOpen"]];
+}
+
+// documented in IterableAPI.h
+- (void)trackPushOpen:(NSNumber *)campaignId templateId:(NSNumber *)templateId appAlreadyRunning:(BOOL)appAlreadyRunning dataFields:(NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
 {
     NSMutableDictionary *reqDataFields;
     if (dataFields) {
@@ -405,7 +431,8 @@ - (void)trackPushOpen:(NSNumber *)campaignId templateId:(NSNumber *)templateId a
                            @"dataFields": reqDataFields
                            };
     NSURLRequest *request = [self createRequestForAction:@"events/trackPushOpen" withArgs:args];
-    [self sendRequest:request onSuccess:[IterableAPI defaultOnSuccess:@"trackPushOpen"] onFailure:[IterableAPI defaultOnFailure:@"trackPushOpen"]];}
+    [self sendRequest:request onSuccess:onSuccess onFailure:onFailure];
+}
 
 // documented in IterableAPI.h
 - (void)trackPurchase:(NSNumber *)total items:(NSArray<CommerceItem> *)items
@@ -415,6 +442,12 @@ - (void)trackPurchase:(NSNumber *)total items:(NSArray<CommerceItem> *)items
 
 // documented in IterableAPI.h
 - (void)trackPurchase:(NSNumber *)total items:(NSArray<CommerceItem> *)items dataFields:(NSDictionary *)dataFields
+{
+    [self trackPurchase:total items:items dataFields:dataFields onSuccess:[IterableAPI defaultOnSuccess:@"trackPurchase"] onFailure:[IterableAPI defaultOnFailure:@"trackPurchase"]];
+}
+
+// documented in IterableAPI.h
+- (void)trackPurchase:(NSNumber *)total items:(NSArray<CommerceItem> *)items dataFields:(NSDictionary *)dataFields onSuccess:(OnSuccessHandler)onSuccess onFailure:(OnFailureHandler)onFailure
 {
     NSDictionary *args;
 
@@ -442,6 +475,6 @@ - (void)trackPurchase:(NSNumber *)total items:(NSArray<CommerceItem> *)items dat
                  };
     }
     NSURLRequest *request = [self createRequestForAction:@"commerce/trackPurchase" withArgs:args];
-    [self sendRequest:request onSuccess:[IterableAPI defaultOnSuccess:@"trackPurchase"] onFailure:[IterableAPI defaultOnFailure:@"trackPurchase"]];}
+    [self sendRequest:request onSuccess:onSuccess onFailure:onFailure];}
 
 @end