PushNotifications.md

 

Push Notifications

The easiest way to support push notifications in your app.

Features

Feature	Description
Automatic Token Management	Skip manually managing push notification device tokens.
Notification Tracking	Track if your users are receiving your notifications even if your app is not runnning or open.
Permission Requests & Checking	Simple functions to request and check push notification permission settings.

 

Requirements

Requirement	Reason
Apple Developer Membership	Apple requires all iOS developers to have a membership so you can manage your push notification certificates.
A phyical iOS device	Although you can setup the Courier SDK without a device, a physical device is the only way to fully ensure push notification tokens and notification delivery is working correctly. Simulators are not reliable.
A Configured Provider	Courier needs to know who to route the push notifications to so your users can receive them.
Authentication	Needs Authentication to sync push notification device tokens to the current user and Courier.

 

Setup

1. Setup a Push Notification Provider

Select which push notification provider you would like Courier to route push notifications to. Choose APNS - Apple Push Notification Service if you are not sure which provider to use.

Provider	Token Syncing
(APNS) - Apple Push Notification Service	Automatic
(FCM) - Firebase Cloud Messaging	Manual
Expo	Manual
OneSignal	Manual
Pusher Beams	Manual

 

2. Enable the "Push Notifications" capability

Enable.push.notification.mov

1. Select your Xcode project file
2. Click your project Target
3. Click "Signing & Capabilities"
4. Click the small "+" to add a capability
5. Press Enter

 

3. Sync Push Notification Tokens

Automatic Token Syncing (APNS Only)

1. In your AppDelegate, add import Courier_iOS
2. Change your AppDelegate to extend the CourierDelegate
   • This automatically syncs APNS tokens to Courier
   • This adds simple functions to handle push notification delivery and clicks

import Courier_iOS

@main
class AppDelegate: CourierDelegate {
    
    ...

    override func pushNotificationDeliveredInForeground(message: [AnyHashable : Any]) -> UNNotificationPresentationOptions {
        
        print("\n=== 💌 Push Notification Delivered In Foreground ===\n")
        print(message)
        print("\n=================================================\n")
        
        // This is how you want to show your notification in the foreground
        // You can pass "[]" to not show the notification to the user or
        // handle this with your own custom styles
        return [.sound, .list, .banner, .badge]
        
    }
    
    override func pushNotificationClicked(message: [AnyHashable : Any]) {
        
        print("\n=== 👉 Push Notification Clicked ===\n")
        print(message)
        print("\n=================================\n")
        
        showMessageAlert(title: "Message Clicked", message: "\(message)")
        
    }

}

Manual Token Syncing

Useful if you do not want to use CourierDelegate or you would like to sync tokens from another provider into Courier.

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    ...

    // Manually Sync APNS tokens
    func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {

        Task {

            // Raw APNS token
            try await Courier.shared.setAPNSToken(deviceToken)
            let apnsToken = await Courier.shared.getToken(for: .apn)
            
        }

    }

    // Commonly used with Firebase Cloud Messaging and other providers
    func yourTokenFetchingFunction(token: String) {

        Task {

            // Sync with provider
            // Available providers: .apn, .firebaseFcm, .expo, .oneSignal, .pusherBeams
            try await Courier.shared.setToken(for: .firebaseFcm, token: token)
            let token = await Courier.shared.getToken(for: .firebaseFcm)

            // Sync with key
            // Any string as key is supported. Make sure you are using the proper key for your needs.
            try await Courier.shared.setToken(for: "firebase-fcm", token: token)
            let token = await Courier.shared.getToken(for: "firebase-fcm")
            
        }

    }

}

 

4. Add the Notification Service Extension (Optional, but recommended)

To make sure Courier can track when a notification is delivered to the device, you need to add a Notification Service Extension. Here is how to add one.

courier-ios-notification-service-setup.mov

1. Download and Unzip the Courier Notification Service Extension: CourierNotificationServiceTemplate.zip
2. Open the folder in terminal and run sh make_template.sh
   • This will create the Notification Service Extension on your mac to save you time
3. Open your iOS app in Xcode and go to File > New > Target
4. Select "Courier Service" and click "Next"
5. Give the Notification Service Extension a name (i.e. "CourierService").
6. Click Finish

Link the Courier SDK to your extension:

Swift Package Manager Setup

1. Click on your project file
2. Under Targets, click on your new Target
3. Under the General tab > Frameworks and Libraries, click the "+" icon
4. Select the Courier package from the list under Courier Package > Courier

Cocoapods Setup

1. Add the following snippet to the bottom of your Podfile

target 'CourierService' do
    pod 'Courier_iOS'
end

2. Run pod install

 

5. Send a Test Push Notification

1. Register for push notifications

import Courier_iOS

Task {
                    
    // Make sure your user is signed into Courier
    // This will take the tokens you are wanting to sync above, and save them to this user id
    // Put this where you normally manage your user's state
    await Courier.shared.signIn(
        userId: "example_user_id",
        accessToken: "...",
    )

    // Shows a popup where your user can allow or deny push notifications
    // You should put this in a place that makes sense for your app
    // You cannot ask the user for push notification permissions again
    // if they deny, you will have to get them to open their device settings to change this
    let status = try await Courier.requestNotificationPermission()

}

2. Send a test message

Provider	Link
(APNS) - Apple Push Notification Service	Testing Docs
(FCM) - Firebase Cloud Messaging	Testing Docs

---

👋 TokenManagement APIs can be found here