User Action Handler

The user action handler is usually called when the user taps a notification in Notification Center.

The implementation method and the execution trigger of this handler are different between iOS 10 or later, and iOS 8 and iOS 9. The sections blow explain the difference in detail. If your mobile app supports iOS 8 or iOS 9, and iOS 10 or later, you need to implement both methods.

For more information about the execution triggers and so on, see Combinations of Reception Methods.

If you do not use Notification Center, you can provide the push notification feature only with the reception handler without the user action handler. Suppose that you want to automatically propagate changes in KiiObjects on the server to the mobile app. You might be able to implement this process only by fully updating KiiObjects when the mobile app starts and sending silent notifications for subsequent changes.

Handler for iOS 10 or later

On iOS 10, the userNotificationCenter(_:didReceive:withCompletionHandler:) method processes tap actions in Notification Center.

This method is called when the user taps a message in Notification Center regardless of the presence of categories and a response to a notification action. Note that the handler for iOS 10 or later is called when the user just taps a notification message without notification actions.

See the sample code below with the handler:

Swift:

// For iOS 10
@available(iOS 10.0, *)
func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
  if (!(response.notification.request.trigger is UNPushNotificationTrigger)) {
    // The received notification is local.
    completionHandler();
    return
  }

  // Check the identifier of the action.
  let identifier = response.actionIdentifier
  print("Selected action: \(identifier)")

  let aps = userInfo["aps"] as? [AnyHashable: Any]
  if let category = aps?["category"] as? String?, category == "MESSAGE_CATEGORY" {
    if identifier == "ACCEPT_IDENTIFIER" {
      print("The user selected ACCEPT_IDENTIFIER.")
    } else if identifier == "DECLINE_IDENTIFIER" {
      print("The user selected DECLINE_IDENTIFIER.")
    }
  }

  // Check the payload of the push message.
  let userInfo = response.notification.request.content.userInfo;
  print("Payload: \(userInfo)")
  let message = KiiReceivedMessage(fromAPNS: userInfo)
  // Do something.

  completionHandler()
}

Objective-C:

// For iOS 10
- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(nonnull void (^)())completionHandler {
  if (![response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
    // The received notification is local.
    completionHandler();
    return;
  }

  // Check the identifier of the action.
  NSString *identifier = response.actionIdentifier;
  NSLog(@"Selected action: %@", response.actionIdentifier);

  NSDictionary *aps = userInfo[@"aps"];
  if ([aps[@"category"] isEqualToString:@"MESSAGE_CATEGORY"]) {
    if ([identifier isEqualToString:@"ACCEPT_IDENTIFIER"]) {
      NSLog(@"The user selected ACCEPT_IDENTIFIER.");
    } else if ([identifier isEqualToString:@"DECLINE_IDENTIFIER"]) {
      NSLog(@"The user selected DECLINE_IDENTIFIER.");
    }
  }

  // Check the payload of the push message.
  NSDictionary *userInfo = response.notification.request.content.userInfo;
  NSLog(@"Payload: %@", userInfo);
  KiiReceivedMessage *message = [KiiReceivedMessage messageFromAPNS:userInfo];
  // Do something.

  completionHandler();
}

This method is called when the push notification feature is initialized with the UNUserNotificationCenter class that supports iOS 10 or later. If the feature is initialized with the deprecated UIUserNotificationSettings class on iOS 10, the handler for iOS 8 and iOS 9 is called when it would be called on iOS 8 and iOS 9.

The sample code performs the following tasks:

1. Check if the notification is remote

   This method is called for remote and local notifications. The code confirms that the trigger property holds a UNPushNotificationTrigger instance that indicates the notification is remote.

2. Check the notification action

   The code checks the identifier of the action that the user selected by getting it in the identifier variable.

   For example, if you initialize the feature with the sample code shown in Initializing the actionable notification, the variable will hold a string such as ACCEPT_IDENTIFIER and DECLINE_IDENTIFIER according to the action selected by the user. If the action cannot be determined, the variable will hold a string of com.apple.UNNotificationDefaultActionIdentifier. This happens in cases including when the user taps the notification message.

3. Check the payload

   The code gets the payload of the push notification in the userInfo variable. As with the reception handler, you can get the payload content by passing this variable to the KiiReceivedMessage class of Kii Cloud.

   At the position of comment // Do something., reference the KiiReceivedMessage instance and perform processes based on the Kii Cloud features. For using the KiiReceivedMessage class, see Push to App Notification, Push to User Notification, and Direct Push Notification.

4. Complete the process

   The code calls the completionHandler block at the end of the process.

You need to modify the class declaration as described in one of the initialization examples because the userNotificationCenter(_:didReceive:withCompletionHandler:) method belongs to the UNUserNotificationCenterDelegate protocol. In addition, the delegate property of the UNUserNotificationCenter instance needs to be set as shown in the sample code in Initializing the actionable notification.

Displaying actions in the foreground

On iOS 10 or later, you can display a push notification in Notification Center and let the user select an action even if the mobile app is running in the foreground.

In order to display a notification when the mobile app is running in the foreground, implement the userNotificationCenter(_:willPresent:withCompletionHandler:) method. Otherwise, your notification will not be displayed. For customizing the method, refer to the API reference for iOS.

Handler for iOS 8 and iOS 9

On iOS 8 and iOS 9, the application(_:handleActionWithIdentifier:forRemoteNotification:withResponseInfo:completionHandler:) method processes events triggered when a notification is tapped in Notification Center.

Unlike iOS 10, this method processes only the events triggered when a category action is tapped.

See the sample code below with the handler:

Swift:

// For iOS 8/9
func application(_ application: UIApplication, handleActionWithIdentifier identifier: String?, forRemoteNotification userInfo: [AnyHashable: Any], completionHandler: @escaping () -> Void){
  print("Payload: \(userInfo)")
  print("Selected action: \(identifier)")

  // Check the identifier of the action.
  let aps = userInfo["aps"] as? [AnyHashable: Any]
  if let category = aps?["category"] as? String?, category == "MESSAGE_CATEGORY" {
      if identifier == "ACCEPT_IDENTIFIER" {
          print("User selected ACCEPT_IDENTIFIER")
      } else if identifier == "DECLINE_IDENTIFIER" {
          print("User selected DECLINE_IDENTIFIER")
      }
  }

  // Check the payload of the push message.
  let message = KiiReceivedMessage(fromAPNS: userInfo)
  // Do something.

  completionHandler()
}

Objective-C:

// For iOS 8/9
- (void)application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)userInfo completionHandler:(void(^)())completionHandler {
  NSLog(@"Payload: %@", userInfo);
  NSLog(@"Selected action: %@", identifier);

  // Check the identifier of the action.
  NSDictionary *aps = userInfo[@"aps"];
  if ([aps[@"category"] isEqualToString:@"MESSAGE_CATEGORY"]) {
    if ([identifier isEqualToString:@"ACCEPT_IDENTIFIER"]) {
      NSLog(@"The user selected ACCEPT_IDENTIFIER.");
    } else if ([identifier isEqualToString:@"DECLINE_IDENTIFIER"]) {
      NSLog(@"The user selected DECLINE_IDENTIFIER.");
    }
  }

  // Check the payload of the push message.
  KiiReceivedMessage *message = [KiiReceivedMessage messageFromAPNS:userInfo];
  // Do something.

  completionHandler();
}

The sample code performs the following tasks:

1. Check the notification action

   You can check the identifier of the action that the user selected by getting the identifier variable.

   For example, if you initialize the feature with the sample code shown in Initializing the actionable notification, the variable will hold a string such as ACCEPT_IDENTIFIER and DECLINE_IDENTIFIER according to the action selected by the user.

2. Check the payload

   You can check the payload of the push notification with the userInfo variable. As with the reception handler, you can get the payload content for the Kii Cloud push notification features by passing this variable to the KiiReceivedMessage class of Kii Cloud.

   At the position of comment // Do something., reference the KiiReceivedMessage instance and perform processes based on the Kii Cloud features. For using the KiiReceivedMessage class, see Push to App Notification, Push to User Notification, and Direct Push Notification.

3. Complete the process

   The code calls the completionHandler block at the end of the process.