firebase-cloud-messenger
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.
Installation
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 have your credentials file in a place that's accessible. You can tell firebase-cloud-messenger where it is in two ways:
FirebaseCloudMessenger.credentials_path = "path/to/credentials/file.json"
export GOOGLE_APPLICATION_CREDENTIALS = "path/to/credentials/file.json"
Usage
Sending a Message
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::AndroidConfig.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::AndroidConfig.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:
= {
android: {
notification: {
title: "title"
}
},
token: "a_device_token"
}
FirebaseCloudMessenger.send(message: ) # => { "name" => "name_from_fcm" }
or some combination of the two:
= FirebaseCloudMessenger::Message.new(android: { notification: { title: "title" }, token: "a_device_token" })
FirebaseCloudMessenger.send(message: ) # => { "name" => "name_from_fcm" }
Error Handling
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.message # => A message from fcm about what's wrong with the request
e.status # => 400
e.details # => An array of error details from fcm
end
Message Validation
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:
= FirebaseCloudMessenger.new(android: { bad: "data" })
.valid?(against_api: true) # => false
.errors # => [<error_msg>]
or client-side, via json-schema:
= FirebaseCloudMessenger.new(android: { bad: "data" }, token: "a_device_token")
.valid? # => false
.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):
= {
android: { bad: "data" },
token: "a_device_token"
}
#api-side
FirebaseCloudMessenger.(, against_api: true) # => false
#OR
#client-side
FirebaseCloudMessenger.() # => false
Development
After checking out the repo, run bundle
to install dependencies. Then, run rake test
to run the tests.