Register push notification credentials

To notify users of events that take place on a client app, you should register notification credentials first. The following steps explain how to download your push notification credentials for APNs and register them to the Sendbird server via your dashboard.

To set up push notifications on a client app, have an app ID assigned to your client app. To obtain a signing certificate required to sign apps for installation on iOS devices, you should first create a certificate signing request (CSR) file through Keychain Access on your Mac.

1. Open Keychain Access from the Utilities folder, go to Keychain Access > Certificate Assistant, and then click Request a Certificate From a Certificate Authority.

To view the image in full screen, click on the

2. When the Certificate Information dialog box appears, enter the email address that you use in your Apple Developer account, and enter a common name for your private key. Don't enter CA email address, choose Saved to disk, and then click the Continue button.

To view the image in full screen, click on the

3. Specify the name of your CSR to save and choose the location to save the file on your local disk. Then your CSR file is created, which contains a public/private key pair.

1. Sign in to your account at the Apple Developer Member Center and choose Certificates, Identifiers & Profiles. In the Identifiers > App IDs, select the Push Notifications service, and then click the Configure button.

To view the image in full screen, click on the

2. When prompted by a pop-up window, choose which SSL certificate to create either Development or Production.

To view the image in full screen, click on the

3. In the Certificates, Identifiers & Profiles pane that appears after the selection, under Upload a Certificate Signing Request, upload the CSR file you created through the Choose File button. Then to complete the process, click the Continue button above. When the certificate is ready, choose Download to save it to your Mac.

To view the image in full screen, click on the

4. In order to install the downloaded certificate to the Keychain Access on your Mac, double-click it. You can find the certificate in the Keychain Access > login > Certificates.

The Sendbird server needs to use some of your confidential information in your .p12 file to communicate with and send notification requests to APNs on behalf of your server. A .p12 file is a set of certificates that you generated when building a client app for iOS.

Note: Now you can use a .p8 file to communicate with APNs and register it in the Sendbird Dashboard. See Step 3-2: Export a .p8 file and upload to Sendbird Dashboard for more information.

You can register your .p12 file to the Sendbird server through your dashboard or by using the Chat API's add an APNs push configuration action. The following steps show how to register a .p12 file in the Dashboard.

1. Open Keychain Access and go to login > Certificates. Find the push notification SSL certificate you just added, right-click the certificate, and then select Export "YOUR_PROJECT_NAME" from the context menu to get a .p12 file that contains the certificate.

To view the image in full screen, click on the

2. Type a name for the .p12 file and save it to your Mac. Do not provide an export password when prompted. Then sign in to your dashboard and upload the file under Settings > Chat > Push notifications.

To view the image in full screen, click on the

3. When a dialog opens up, select .p12 for Format. Then click the Choose file and select your .p12 certificate to upload. Once the file is uploaded, a password box appears. If needed, you can also set a password for the file.

To view the image in full screen, click on the

The Sendbird server needs to use some of your confidential information in your .p8 file to send notification requests to APNs on behalf of your server. A .p8 file is an authentication token that is generated when you build a client app for iOS.

You can register your .p8 file to the Sendbird server through the Sendbird Dashboard or by using the platform API’s add an APNs push configuration action. The following steps show how to register a .p8 file in the dashboard.

Note: To learn more about the authentication token with a .p8 extension, visit Apple Developer's Documentation on a token-based connection to APNs.

1. Log into your Apple Developer account and go to Certificates, Identifiers & Profiles > Keys. Then click Create a key.

To view the image in full screen, click on the

2. Once an authentication key is created, register the key with a key name of your choice and select a service you want to use. In this case, check Apple Push Notifications service (APNs) in the table. Then click Continue.

To view the image in full screen, click on the

3. Make sure the key name and service chosen are correct. Then click Register.

To view the image in full screen, click on the

4. Once the key is registered, you can download the key as a file with a .p8 extension. Download the file so that you can add it to the Sendbird Dashboard.

To view the image in full screen, click on the

Note: The file can be only downloaded once. Make sure to remember the directory where your file is downloaded.

5. Sign in to your Sendbird Dashboard and upload the file under Settings > Chat > Push notifications.

To view the image in full screen, click on the

6. When a dialog opens up, select .p8 for Format. Then click Choose file and select your .p8 key file to upload. Once the file is uploaded, select SSL certificate type between Production and Developer.

To view the image in full screen, click on the

To use remote push notifications in your app's xcode project, you need to enable the push notifications capability.

For more information, follow the steps in the Enable the Push Notifications Capability section of Apple's Registering Your App with APNs article.

When requested to send notifications to a specific client app on an iOS device, APNs requires the app instance's globally-unique and app-specific device token which has been issued by itself. Therefore, to send notification requests to APNs on behalf of your server, the Sendbird server needs every device token of your client app instances. If an app instance is successfully registered to APNs via the registerForRemoteNotifications method, a device token is passed to an app delegate object's application:didRegisterForRemoteNotificationsWithDeviceToken: method which is called by the app. Like the following sample code, you should register this token to the Sendbird server by passing it as an argument to a parameter in the registerDevicePushToken(_:unique:completionHandler:) method.

Note: A user can have up to 20 APNs device tokens. If a user already has 20 device tokens, the oldest token will be deleted before a new token is added. Only the 20 newest tokens will be maintained for users who already have more than 20.

// AppDelegate.swift
func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    // Register a device token to the Sendbird server.
    SendbirdChat.registerDevicePushToken(deviceToken, unique: false) { status, error in
        if error == nil {
            // A device token is successfully registered.
        }
        else {
            if status == PushTokenRegistrationStatus.pending {
                // A token registration is pending.
                // If this status is returned,
                // invoke the registerDevicePushToken:unique:completionHandler:
                // with [SendbirdChat getPendingPushToken] after connection.
            }
            else {
                // Handle registration failure.
            }
        }
    }
}

Note: If pending is returned through completionHandler, this means that your user is not being connected to the Sendbird server when registerDevicePushToken(_:unique:completionHandler:) is called. In this case, we recommend that you first get a pending device token by using the getPendingPushToken() method, and then register the token by invoking registerDevicePushToken(_:unique:completionHandler:) in a callback of connect(userId:completionHandler:) or connect(userId:authToken:completionHandler:) when your user has been connected to the server afterward.

SendbirdChat.connect(userId: USER_ID) { user, error in
    if let token = SendbirdChat.getPendingPushToken(), error == nil {
        SendbirdChat.registerDevicePushToken(token, unique: false) { status, error in

        }
    }
}

Make sure you call the following code in the appropriate place to receive permissions from your users.

let center = UNUserNotificationCenter.current()
center.delegate = self
center.requestAuthorization(options: [.sound, .alert, .badge]) { granted, error in
    DispatchQueue.main.async {
        UIApplication.shared.registerForRemoteNotifications()
    }
}

The Sendbird server sends notification requests to APNs with the following options.

The server also sends an additional JSON object with the sendbird key. For notification requests, APNs then delivers notifications to iOS devices. At the client side, you can parse the data payload and handle the result to implement user reactions within the application:didReceiveRemoteNotification:fetchCompletionHandler: method, which covers all notifications from the application states of inactive, foreground, and background.

func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void) {
    let alertMsg = (userInfo["aps"] as! NSDictionary)["alert"] as! NSDictionary
    let payload = userInfo["sendbird"] as! NSDictionary

    // Implement your custom codes to parse payload.
    if (application.applicationState == .inactive) {
        // Receive a notification while your app is inactive.
    } else {
        // Receive a notification while your app is
        // in either foreground or background.
    }

    completionHandler(UIBackgroundFetchResult.newData)
}

The following is a complete payload format of the sendbird object, which contains a set of provided key-value items. As for channel_unread_count, the attribute can be added into or removed from the payload in Settings > Chat > Push notifications on the Sendbird Dashboard.

{
    "category": "messaging:offline_notification",
    "type": string,                 // Message type can be MESG, FILE, or ADMM.
    "message": string,              // User input message.
    "custom_type": string,          // Custom message type.
    "message_id": long,             // Message ID.
    "created_at": long,             // The time that the message was created in a 13-digit Unix milliseconds format.
    "app_id": string,               // Application's unique ID.
    "unread_message_count": int,    // Total number of new messages unread by the user.
    "channel": {
        "channel_url": string,      // Group channel URL.
        "name": string,             // Group channel name.
        "custom_type": string,       // Custom Group channel type.
        "channel_unread_count": int // Total number of unread new messages from the specific channel.
    },
    "channel_type": string,         // The value of channel_type is set by the system.
                                    // messaging indicates a distinct group channel,
                                    // while group_messaging indicates a private group channel.
                                    // chat indicates all other cases.
    "sender": {
        "id": string,               // Sender's unique ID.
        "name": string,             // Sender's nickname.
        "profile_url": string,       // Sender's profile image URL.
        "require_auth_for_profile_image": false,
        "metadata": {}
    },
    "recipient": {
        "id": string,               // Recipient's unique ID.
        "name": string              // Recipient's nickname.
    },
    "files": [],                    // An array of data regarding the file message, such as filename.
    "translations": {},             // The items of locale:translation.
    "push_title": string,           // Title of a notification message that can be customized on the Sendbird Dashboard with or without variables.
    "push_alert": string,           // Body text of a notification message that can be customized on the Sendbird Dashboard with or without variables.
    "push_sound": string,           // The location of a sound file for notifications.
    "audience_type": string,        // The type of audiences for notifications.
    "mentioned_users": {
        "user_id": string,          // The ID of a mentioned user.
        "nickname": string,         // The nickname of a mentioned user.
        "profile_url": string,      // Mentioned user's profile image URL.
        "require_auth_for_profile_image": false
    },
}

After the above implementation is completed, determine whether push notification support for multi-device users is required for the client app. To set it up, go to Settings > Chat > Push notifications > Push notifications for multi-device users on our dashboard.

To view the image in full screen, click on the

The following table explains when a notification message is sent and whether it is displayed on the device depending on your notification support settings and the device' online status. Refer to the table to find out which notification support best suits the client app use cases.