Intro 👏

It's a swift lib that gives ability to send push notifications through Firebase Cloud Messaging.

Built for Vapor4 and depends on JWT Vapor lib.

💡 Vapor3 version is available in vapor3 branch and from 1.0.0 tag

💡 Stable Vapor4 ELF version is available in v2 branch and from 2.0.0 tag

If you have great ideas of how to improve this package write me (@iMike#3049) in Vapor's discord chat or just send pull request.

Hope it'll be useful for someone :)

Install through Swift Package Manager ❤️

Edit your Package.swift

//add this repo to dependencies
.package(url: "https://github.com/MihaelIsaev/FCM.git", from: "3.0.0-beta.1")
//and don't forget about targets
.product(name: "FCM", package: "FCM")

How it works ?

First of all you should configure FCM in configure.swift

import FCM

// Called before your application initializes.
func configure(_ app: Application) throws {
    /// case 1
    /// with service account json file
    /// put into your environment variables the following key:
    /// FCM_SERVICE_ACCOUNT_KEY_PATH=path/to/serviceAccountKey.json
    app.fcm.configuration = .envServiceAccountKey
    
    /// case 2
    /// with service account json string
    /// put into your environment variable the following key:
    /// FCM_SERVICE_ACCOUNT_KEY="{"prohect_id": "my_project123",...}"
    app.fcm.configuration = .envServiceAccountKey
    
    /// case 3
    /// put into your environment variables the following keys:
    /// FCM_EMAIL=...          // `client_email` in service.json
    /// FCM_PROJECT_ID=...     // `project_id` in service.json
    /// FCM_PRIVATE_KEY=...    // `private_key` in service.json
    app.fcm.configuration = .envServiceAccountKeyFields

    /// case 4
    /// put into your environment variables the following keys:
    /// FCM_EMAIL=...
    /// FCM_PROJECT_ID=...
    /// FCM_KEY_PATH=path/to/key.pem
    app.fcm.configuration = .envCredentials

    /// case 5
    /// manually
    app.fcm.configuration = .init(email: "...", projectId: "...", key: "...")
}

⚠️ TIP: serviceAccountKey.json you could get from Firebase Console

🔑 Just go to Settings -> Service Accounts tab and press Create Private Key button in e.g. NodeJS tab

OPTIONAL: Set default configurations, e.g. to enable notification sound

Add the following code to your configure.swift after app.fcm.configuration = ...

app.fcm.configuration?.apnsDefaultConfig = FCMApnsConfig(headers: [:], 
                                                         aps: FCMApnsApsObject(sound: "default"))

app.fcm.configuration?.androidDefaultConfig = FCMAndroidConfig(ttl: "86400s",
                                                               restricted_package_name: "com.example.myapp",
                                                               notification: FCMAndroidNotification(sound: "default"))
                                                
app.fcm.configuration?.webpushDefaultConfig = FCMWebpushConfig(headers: [:],
                                                               data: [:],
                                                               notification: [:])

Let's send first push notification! 🚀

Then you could send push notifications using token, topic or condition.

Here's an example route handler with push notification sending using token

import FCM

func routes(_ app: Application) async throws {
    app.get("testfcm") { req async throws -> String in
        let token = "<YOUR FIREBASE DEVICE TOKEN>" // get it from iOS/Android SDK
        let notification = FCMNotification(title: "Vapor is awesome!", body: "Swift one love! ❤️")
        let message = FCMMessage(token: token, notification: notification)
        let name = try await req.fcm.send(message, on: req.eventLoop)
        return "Just sent: \(name)"
    }
}

fcm.send returns message name like projects/example-3ab5c/messages/1531222329648135

FCMMessage struct is absolutely the same as Message struct in Firebase docs https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages So you could take a look on its source code to build proper message.

APNS to Firebase token conversion

You can throw away Firebase libs from dependencies of your iOS apps because you can send pure APNS tokens to your server and it will register it in Firebase by itself.

It is must have for developers who don't want to add Firebase libs into their apps, and especially for iOS projects who use Swift Package Manager cause Firebase doesn't have SPM support for its libs yet.

How to use

Preparation

1. Go to Firebase Console -> Project Settings -> Cloud Messaging tab
2. Copy Server Key from Project Credentials area

Next steps are optional

3. Put server key into environment variables as FCM_SERVER_KEY=<YOUR_SERVER_KEY> (or put it into serviceAccountKey.json file as server_key)
4. Put your app bundle identifier into environment variables as FCM_APP_BUNDLE_ID=<APP_BUNDLE_ID>

Tokens registration

/// The simplest way
/// .env here means that FCM_SERVER_KEY and FCM_APP_BUNDLE_ID will be used
let tokens = try await application.fcm.registerAPNS(.env, tokens: "token1", "token3", ..., "token100")
/// `tokens` is array of `APNSToFirebaseToken` structs
/// which contains:
/// registration_token - Firebase token
/// apns_token - APNS token
/// isRegistered - boolean value which indicates if registration was successful

/// instead of .env you could declare your own identifier
extension RegisterAPNSID {
   static var myApp: RegisterAPNSID { .init(appBundleId: "com.myapp") }
}

/// Advanced way
let tokens = try await application.fcm.registerAPNS(
    appBundleId: String, // iOS app bundle identifier
    serverKey: String?, // optional server key, if nil then env variable will be used
    sandbox: Bool, // optional sandbox key, false by default
    tokens: [String]
)
/// the same as in above example

💡 Please note that push token taken from Xcode while debugging is for sandbox, so either use .envSandbox or don't forget to set sandbox: true

Contributors

Thanks to these amazing people for their contributions:

• @ptoffy for enhancements in Swift 6 support #50
• @gennaro-safehill for Swift 6 and async/await support #48
• @paunik for adding image support in options #44
• @chinh-tran for retrieving subscribed topics #43
• @apemaia99 for supporting multiple configurations/clients #42
• @sroebert for removing unneeded setting of ignoreUncleanSSLShutdown #36
• @sroebert for marking all FCMAndroidConfig fields as optional #34
• @JCTec for Swift 5.2.1 support #33
• @Andrewangeta for reading service account from JSON string env variable #31
• @siemensikkema for batch messaging improvements #30
• @krezzoid for token issue decoding fix #27
• 💎 @grahamburgsma for fixing memory issues #26
• @geeksweep, @maximkrouk, @gustavoggs for README updates #22, #23, #37
• @emrahsifoglu for optional priority option #20
• @nerzh for enhancements in FCMAndroidNotification #16, #18
• @FredericRuaudel for multiple useful enhancements #13, #14, #15
• @grahamburgsma for GoogleError and FCMError #10
• @simonmitchell for capability for silent content-available push notifications #9
• @siemensikkema for updating to JWT v3 #3
• @pedantix for APNS enhancements #2