Push notifications

👍

Turn on push notifications first

Before you can configure push notifications, you'll need to turn on push notifications in Kustomer.

To learn more, see Push Keys and Certificates.

This guide shows you how to implement and test push notifications for your app after you turn on push notifications based on your Push keys and certificates in Kustomer.

We'll cover the following topics:

• How to configure Kustomer push notifications in your app delegate
• How to integrate Kustomer push notifications with your own app push notifications
• How to test push notifications with an APNs (Apple Push Notification service) file or a push simulator

Prerequisites

You'll need the following before you begin:

• Push notifications turned on in your Kustomer Chat Management: Install Chat settings.

Configure Kustomer push notifications

First, we'll add Kustomer methods to your app delegate to request push notification permissions from the user.

📘

You can customize your push notifications content to redact sensitive information. To make these changes, go to Apps > Chat and select the SDK tab.

Step 1. Add Kustomer methods to your app delegate

First, add the following two methods to your app delegate:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data){
  Kustomer.didRegisterForRemoteNotifications(deviceToken:deviceToken)
}

func application(_ application: UIApplication, didFailToRegisterForRemoteNotificationsWithError error: Error) {
  Kustomer.didFailToRegisterForRemoteNotifications(error: error)
}

Step 2. Request push permissions from the user

Next, request push notifications permissions from the user with the following method:

Kustomer.requestAuthorizationForPush()

Call Kustomer.requestAuthorizationForPush() when you want to prompt the user with "Allow notifications?"

If the user has already granted permission, this method will have no effect and can be called multiple times in the code.

You must call Kustomer.requestAuthorizationForPush() after you call Kustomer.configure(apiKey: "foo", options:options) to initialize the Chat SDK with options.

Integrate Kustomer push notifications (deprecated)

🚧

DEPRECATION WARNING

This implementation is deprecated. Please see Implement Kustomer SDK as secondary handler below for the preferred integration.

If you already use push notifications in your app, you can continue processing your own pushes through a UNUserNotificationCenterDelegate.

Set the unUserNotificationCenterDelegate to ensure that your delegate receives all non-Kustomer Chat pushes.

👍

Always automate your settings for UNUserNotificationCenter.current().delegate

When you use push notifications, always allow the UNUserNotificationCenter.current().delegate to be set automatically through the Kustomer Chat SDK.

The Kustomer Chat SDK will automatically set your UNUserNotificationCenter.current().delegate in either of the following scenarios:

• If push notifications are turned on when the app launches
• If push notifications are turned on while your app is running

If your app implements its own UNUserNotificationCenterDelegate, you can assign the delegate to Kustomer.unUserNotificationCenterDelegate.

let foo:UNUserNotificationCenterDelegate = //whatever you're currently using

Kustomer.unUserNotificationCenterDelegate = foo

Implement Kustomer SDK as secondary handler

If your app already has push notifications implemented or you wish to better integrate with other third-party frameworks that provide push services you should set your application as the notification center delegate and pass Kustomer push notifications to the Kustomer SDK.

In this case your application will be responsible for managing the UNUserNotificationCenter.current().delegate and this delegate will need to pass Kustomer push notifications to the Kustomer SDK. This delegate will need to be set before calling Kustomer.configure(apiKey: "foo", options:options).

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
 if response.notification.isFromKustomer() {
  Kustomer.pushProvider.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
 }
}
  
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
 if notification.isFromKustomer() {
  Kustomer.pushProvider.userNotificationCenter(center, willPresent: notification, withCompletionHandler: completionHandler)
 }
}

Note that Kustomer.pushProvider.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler) will attempt to open the Kustomer Chat Widget at the relevant conversation if the user is currently authenticated for that chat. For custom Notification implementations, notification.isFromKustomer()can be used to check if a notification is from Kustomer, and notification.kustomerShouldDisplay()can be used to determine if the notification should be displayed (1. that the notification has a Kustomer payload attached, 2. that the user attached to the notification is the logged in user, 3. that Kustomer option enableUI is not disabled and 4. that the session id is not the same as any currently open conversation).

❗️

WARNING - Potential Infinite Recursion

If you had previously implemented Kustomer push notifications by setting Kustomer.unUserNotificationCenterDelegate and you add this implementation, your application can enter an infinite loop when it receives a non-Kustomer push notification. To avoid this remove any code that sets Kustomer.unUserNotificationCenterDelegate and be sure to include the check for threadIdentifier as shown above.

Test Kustomer push notifications

You can test Kustomer push notifications with an APNs file or a push simulator.

Test with development mode

You can test Kustomer push notifications in a simulator before turning them on in production.

🚧

Turning this setting on will turn off push notifications sent to your production app from Kustomer.

To do so:

1. Set options.pushEnvironment in your KustomerOptions configuration to options.pushEnvironment = .development.
2. In Kustomer, go to Apps > Chat, select the Install Chat tab, and turn on the Test push notifications toggle for the brand you want to test.

When you are ready to turn on production push notifications from Kustomer, remember to remove the options.pushEnvironment option from your KustomerOptions configuration and turn off the Test push notifications toggle in Kustomer.

Test with an APNs file in Xcode

If you're using your own push notifications alongside Kustomer Chat push notifications, we recommend that you test your pushes on the iOS simulator available in Xcode.

To test with an APNs file in Xcode, drag your APNs file into the iOS simulator. An APNs file is the same as a normal push JSON payload file, but also includes a Simulator Target Bundle key with the bundle ID for your app.

We've provided an example of an APNs file that will send a push identical to a push sent from Kustomer:

{
  "Simulator Target Bundle": "YOUR BUNDLE ID HERE",
    "aps": {
      "alert": {
        "body": "Hello"
      },
      "thread-id": "kustomer.app.chat",
      "topic": "YOUR BUNDLE ID HERE",
      "badge": 0,
      "mutable-content":1
    },
    "data": {
      "name": "kustomer.app.chat.message.send",
      "data": {
        "type": "chat_message",
        "id": "12345",
        "attributes": {
          "body": "Hello",
          "truncated": false,
          "direction": "out",
          "createdAt": "2020-09-17T19:52:56.280Z"
        },
        "relationships": {
          "customer": {
            "data": {
              "type": "customer",
              "id": "123"
            }
          },
          "session": {
            "data": {
              "type": "chat_session",
              "id": "456"
            }
          },
          "sentBy": {
            "data": {
              "type": "user",
              "id": "789"
            }
          }
        }
      },
      "included": [
        {
          "id": "789",
          "type": "user",
          "attributes": {
            "displayName": "Agent 3",
            "avatarUrl": "https://domain.com/image.png"
          }
        }
      ]
    }
  }

Test with a push simulator

Use a push simulator to test pushes with a development, or sandbox, APNs environment.

A push simulator connects to the APNs service, sends data, and then APNs sends the push to your device.

If you want to use a push simulator like PushHero with a real device, you can set options.pushEnvironment in your KustomerOptions configuration to options.pushEnvironment = development and use the sample JSON payload below with the correct app bundle ID.

{
    "aps": {
      "alert": {
        "body": "Hello"
      },
      "thread-id": "kustomer.app.chat",
      "topic": "<YOUR APP BUNDLE ID HERE>",
      "badge": 0,
      "mutable-content":1
    },
    "data": {
      "name": "kustomer.app.chat.message.send",
      "data": {
        "type": "chat_message",
        "id": "12345",
        "attributes": {
          "body": "Hello",
          "truncated": false,
          "direction": "out",
          "createdAt": "2020-09-17T19:52:56.280Z"
        },
        "relationships": {
          "customer": {
            "data": {
              "type": "customer",
              "id": "123"
            }
          },
          "session": {
            "data": {
              "type": "chat_session",
              "id": "456"
            }
          },
          "sentBy": {
            "data": {
              "type": "user",
              "id": "789"
            }
          }
        }
      },
      "included": [
        {
          "id": "789",
          "type": "user",
          "attributes": {
            "displayName": "Agent 3",
            "avatarUrl": "https://domain.com/image.png"
          }
        }
      ]
    }
  }