iOS & APN

Push Notifications for iOS

Using the APNs, your users apps can receive push notifications directly on their client app for new messages when offline. Stream supports both Certificate-based provider connection trust (.p12 certificate), as well as Token-based provider connection trust (JWT).

Setup APN Push Using Token Authentication

Token based authentication is the preferred way to setup push notifications. This method is easy to setup and provides strong security.

Step 1. Retrieve Your Team ID

Sign in to your Apple Developer Account and then navigate to Membership. Copy your Team ID and store it somewhere safe.

Step 2. Retrieve your Bundle ID

• From App Store Connect, navigate to My Apps
• Select the app you are using Stream Chat with
• Make sure the App Store tab is selected and navigate to App Information on the left bar

• In the Bundle ID dropdown, make sure the proper bundle id is selected. Copy the Bundle ID.

Step 3. Generate a Token

• From your Apple Developer Account overview, navigate to Certificates, Identifiers & Providers

• Make sure iOS, tvOS, watchOS is selected on the navigation pane on the left, and go to Keys > All

• Click on the + button to Add a new key

• In the Name field input a name for your key. In the Key Services section, select Apple Push Notifications service (APNs) and then click on Continue

• Review the information from the previous step and click on Confirm
• Copy your Key ID and store it somewhere safe
• Save the key on your hard drive

Step 4. Upload the Key Credentials to Stream Chat

Upload the TeamID, KeyID, Key and BundleID from the previous steps.

await client.updateAppSettings({
    apn_config: {
        auth_key: fs.readFileSync(
            './auth-key.p8',
            'utf-8',
        ),
        auth_type: 'token',
        key_id: 'key_id',
        bundle_id: 'com.apple.test',
        team_id: 'team_id',
        notification_template: `{"aps" :{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":"{{ unread_count }}","category":"NEW_MESSAGE"}}`
    },
});
                    

If your wish to use the APNs development endpoint instead of the production one, you must specify this when uploading the Key Credentials via the development parameter as shown below:

await client.updateAppSettings({
    apn_config: {
        auth_key: fs.readFileSync(
            './auth-key.p8',
            'utf-8',
        ),
        key_id: 'key_id',
        auth_type: 'token',
        development: true,
        bundle_id: 'com.apple.test',
        team_id: 'team_id',
        notification_template: `{"aps" :{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}`
    },
});
                    

Setup APN Push Using Certificate Authentication

If token based authentication is not an option, you can setup APN with Certificate Authentication. You will need to generate a valid .p12 certificate for your application and upload it to Stream Chat.

Step 1. Create a Certificate Signing Request (CSR)

• On your Mac, open Keychain Access
• Go to Keychain Access > Certificate Assistant > Request a Certificate from a Certificate Authority

• Fill out the information in the Certificate Information window as specified below and click Continue.

In the User Email Address field, enter the email address to identify with this certificate. In the Common Name field, enter your name. In the Request group, click the "Save to disk" option.

Finally, save the file on your hard drive in secure area.

Step 2. Create a Push Notification SSL Certificate

• Sign in to your Apple Developer Account and then navigate to Certificates, Identifiers & Providers

• Make sure iOS, tvOS, watchOS is selected on the navigation pane on the left, and go to Certificates > All

• Click on the + button to Add a new certificate

• In the Development section, select Apple Push Notification service SSL (Sandbox) and then click on Continue

• Select your app in the dropdown list and then click on Continue
• You will see instructions on how to generate a .certSigningRequest file. This was already covered in the previous section. Click on Continue
• Click on Choose File and then navigate to where you have saved the .certSigningRequest file from the previous section, then click on Continue
• Click on Download to save your certificate to your hard drive

Step 3. Export the Certificate in .p12 Format

• On your mac, navigate to where you have saved the .cer file from the previous section and double click on the file. This will add it to your macOS Keychain.
• Go to Keychain Access
• At the top left, select Keychains > Login
• Then, at the bottom left, select Category > Certificates

• Select the certificate you've created in the previous step. It should look like Apple Development IOS Push Services: YOUR_APP_NAME and expand it to see the private key(it should be named after the Name you provided when creating the Certificate Signing Request – the case of this example: John Smith)

• Right-click the private key and click on Export. In the File format section select Personal Information Exchange (.p12) and save the file on your hard drive

Step 4. Upload the Certificate to Stream Chat

await client.updateAppSettings({
    apn_config: {
        p12_cert: fs.readFileSync(
            './certificate.p12',
        ),
        auth_type: 'certificate',
        notification_template: `{"aps":{"alert":{"title":"{{ sender.name }}","subtitle":"New direct message from {{ sender.name }}","body":"{{ message.text }}"},"badge":{{ unread_count }},"category":"NEW_MESSAGE"}}`
    },
});