Firebase notifications

A Duct library that provides Integrant keys for managing notifications in Firebase Cloud Messaging.

Installation

Usage

Configuration

To use this library add the following key to your configuration:

:magnet.notifications/firebase

This key expects a configuration map with one mandatory key:

• :google-credentials: A map with five elements:
  • project-id
  • private-key-id
  • private-key
  • client-id
  • client-email

Key initialization returns a Firebase record that can be used to perform the Firebase operations described below.

Configuration example

   :magnet.notifications/firebase
   {:google-credentials {:project-id #duct/env ["G_CREDENTIALS_PROJECT_ID" Str]
                         :private-key-id #duct/env ["G_CREDENTIALS_PRIVATE_KEY_ID" Str]
                         :private-key #duct/env ["G_CREDENTIALS_PRIVATE_KEY" Str]
                         :client-id #duct/env ["G_CREDENTIALS_CLIENT_ID" Str]
                         :client-email #duct/env ["G_CREDENTIALS_CLIENT_EMAIL" Str]}}

Obtaining a Firebase record

If you are using the library as part of a Duct-based project, adding any of the previous configurations to your config.edn file will perform all the steps necessary to initialize the key and return a Firebase record for the associated configuration. In order to show a few interactive usages of the library, we will do all the steps manually in the REPL.

First we require the relevant namespaces:

user> (require '[integrant.core :as ig]
               '[magnet.notifications.core :as core])
nil
user>

Next we create the configuration var holding the Firebase integration configuration details:

user> (def config {:google-credentials {:project-id (System/getEnv "G_CREDENTIALS_PROJECT_ID")
                                        :private-key-id (System/getEnv "G_CREDENTIALS_PRIVATE_KEY_ID")
                                        :private-key (System/getEnv "G_CREDENTIALS_PRIVATE_KEY")
                                        :client-id (System/getEnv "G_CREDENTIALS_CLIENT_ID")
                                        :client-email (System/getEnv "G_CREDENTIALS_CLIENT_EMAIL")}})
#'user/config
user>

Now that we have all pieces in place, we can initialize the :magnet.notifications/firebase Integrant key to get a Firebase record. As we are doing all this from the REPL, we have to manually require magnet.notifications.firebase namespace, where the init-key multimethod for that key is defined (this is not needed when Duct takes care of initializing the key as part of the application start up):

user> (require '[magnet.notifications.firebase :as firebase])
nil
user>

And we finally initialize the key with the configuration defined above, to get our Firebase record:

user> (def fb-record (->
                       config
                       (->> (ig/init-key :magnet.notifications/firebase))))
#'user/fb-record
user> fb-record
#magnet.notifications.firebase.Firebase{:service-credentials #object[com.google.auth.oauth2.ServiceAccountCredentials
                                                              0x307d05cf
                                                              "ServiceAccountCredentials{...}"}
user>

Now that we have our Firebase record, we are ready to use the methods defined by the protocols defined in magnet.notifications.core namespace.

Usage

send-notification

• parameters:
  • A Firebase record.
  • logger: usually a reference to :duct/logger key. But you can use any Integrant key derived from :duct/logger (such as :duct.logger/timbre).
  • recipient: registration token to send a message to. It can be a single value or a vector of multiple tokens.
  • message: a map with the information that will be send as a notification. The values can be strings, numbers or simple keywords. They will be converted to strings due to a Firebase limitation. It will be send as the data key in the Firebase message object.
  • options: optional configuration parameters that will be send in the Firebase message object. See the docs for available keys.
• returning value:
  • :success? true if the notification was successfully sent to all the recipients. false if sending the notification failed for at least one recipient.
  • :errors list of errors that happened when sending the notification. It's one error for each recipient.
• Example:

user> (core/send-notification fb-record logger ["token1" "token2"] {:header "Hello"} {})
{:success? true}

user> (core/send-notification fb-record logger ["token1" "invalid-token"] {:header "Hello"} {})
{:success? false
 :errors [{:status 400, :recipient "invalid-token"}]}

License

Copyright (c) 2020 Magnet S Coop.

The source code for the library is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.