Push Notifications

👍

Enable 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: SDK 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) {
    let threadID = response.notification.request.content.threadIdentifier
    if threadID == "kustomer.app.chat" {
      Kustomer.pushProvider.userNotificationCenter(center, didReceive: response, withCompletionHandler: completionHandler)
    }
  }
  
func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
    let threadID = notification.request.content.threadIdentifier
    if threadID == "kustomer.app.chat" {
      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.

❗️

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

Pushes from Kustomer use the production APNs environment and will only display after your app downloads from TestFlight or the Apple App Store.

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

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"
          }
        }
      ]
    }
  }