Check out PLM's blog post about our development and use of firebase_cloud_messenger for more information about setting up and getting started.
firebase_cloud_messenger wraps Google's API to make sending push notifications to iOS, android, and web push notifications from your server easy.
NB: Google released the FCM HTTP v1 API in November 2017, giving legacy status to the older but still supported HTTP and XMPP apis. This gem only targets the [FCM HTTP v1 API], which Google recommends using for new projects, because it is the most up-to-date and secure.
Add this line to your application's Gemfile:
gem 'firebase_cloud_messenger'
And then execute:
$ bundle
Or install it yourself as:
$ gem install firebase_cloud_messenger
In order for google to authenticate requests to Firebase Cloud Messenger, you must either have your service account credentials file in a place that's accessible, or provide credentials as env vars.
$ export GOOGLE_APPLICATION_CREDENTIALS = "path/to/credentials/file.json"`
FirebaseCloudMessenger.credentials_path = "path/to/credentials/file.json"
$ export GOOGLE_PRIVATE_KEY = "-----BEGIN PRIVATE KEY-----..."
$ export GOOGLE_CLIENT_EMAIL = "firebase-admin-sdk...@iam.gserviceaccount.com"
Also set the project_id
, which is otherwise read from the json service account file:
FirebaseCloudMessenger.project_id = "1234567"
You can see how your message should be structured here firebase_cloud_messenger provides built-in data classes for each json object type in the FCM API specification, but you can also build up a hash message on your own, or use some combination of the two.
Send messages with built-in data objects, which can be built through a hash argument to the initializer or via writer methods:
android_notification = FirebaseCloudMessenger::Android::Notification.new(title: "title")
android_config = FirebaseCloudMessenger::Android::Config.new(notification: android_notification)
message = FirebaseCloudMessenger::Message.new(android: android_config, token: "a_device_token")
FirebaseCloudMessenger.send(message: message) # => { "name" => "name_from_fcm" }
# OR
android_notification = FirebaseCloudMessenger::Android::Notification.new
android_notification.title = "title"
android_config = FirebaseCloudMessenger::Android::Config.new
android_config.notification = android_notification
message = FirebaseCloudMessenger::Message.new
message.android = android_config
message.token = "a_device_token"
FirebaseCloudMessenger.send(message: message) # => { "name" => "name_from_fcm" }
or with just a hash:
message = {
android: {
notification: {
title: "title"
}
},
token: "a_device_token"
}
FirebaseCloudMessenger.send(message: message) # => { "name" => "name_from_fcm" }
or some combination of the two:
message = FirebaseCloudMessenger::Message.new(android: { notification: { title: "title" } }, token: "a_device_token" )
FirebaseCloudMessenger.send(message: message) # => { "name" => "name_from_fcm" }
If something goes wrong, ::send
will raise an instance of a subclass of FirebaseCloudMessenger::Error
with
helpful info on what went wrong:
message = FirebaseCloudMessenger::Message.new(android: { bad: "data" }, token: "a_device_token"})
begin
FirebaseCloudMessenger.send(message: message)
rescue FirebaseCloudMessenger::Error => e
e.class # => FirebaseCloudMessenger::BadRequest
e.short_message # => A message from fcm about what's wrong with the request
e.response_status # => 400
e.details # => An array of error details from fcm
end
Many errors can be caught before sending by validating a message before sending it.
Validate your message either by via the Firebase Cloud Messenger API:
message = FirebaseCloudMessenger::Message.new(android: { bad: "data" })
message.valid?(against_api: true) # => false
message.errors # => [<error_msg>]
or client-side, via json-schema:
message = FirebaseCloudMessenger::Message.new(android: { bad: "data" }, token: "a_device_token")
message.valid? # => false
message.errors # => ["The property '#/android' contains additional properties [\"bad\"] outside of the schema when none are allowed in schema..."]
Validate your hash message (returns only true or false):
message = {
android: { bad: "data" },
token: "a_device_token"
}
#api-side
FirebaseCloudMessenger.validate_message(message, against_api: true) # => false
#OR
#client-side
FirebaseCloudMessenger.validate_message(message) # => false
After checking out the repo, run bundle
to install dependencies. Then, run bundle exec rake test
to run the tests.