Don’t get me wrong, the Firebase Cloud Messaging docs are great. It’s all very extensive and the code’s everywhere. That’s EXACTLY why I’m going to make this post.
Because I don’t understand a bloody bit of it mate. It takes me a full 4 hours just to understand one section of it.
By the way mate, if you’re into reading long lists of parameters, here’s the info of each one of that from the docs. I’m going to be telling you here about the important ones.
That’s why I’m going to tell you just how to construct these messages which are actually pretty neat. It ain’t even hard either.
Standard and Legacy Protocol
There are 2 different ways to send Cloud Messages. The Standard protocol is used for sending to app instances and topics, while the Legacy is used for specific devices and device groups.
The URL and headers they use differ, constructing their payload is pretty much done the same way.
Standard Protocol
URL and Http Headers
https://fcm.googleapis.com/v1/projects/myproject-b5ae1/messages:send HTTP/1.1
So you’d send your request to this URL and you’d want to include these headers.
Content-Type:application/json Authorization: Bearer <valid Oauth 2.0 token for the service account of the Firebase project>
You get the Authorization Bearer, you’ll need to acquire the access token, just follow the docs for this little bit. Sparing that, it’s simple innit?
Setting the Message Target
{
"message":{
...
}
}
So you start by opening up your message like this. Inside message, you’ll be defining a few parameters.
There are 2 ways to do set your target: using the token or topic attribute.
{
"message":{
"topic" : "foo-bar"
...
}
}
If you’re using token (to target all users of an app instance), you put the app instance token (acquired differently depending on what platform you’re on). For topic, simply put the name of the topic as shown.
"condition": "'dogs' in topics || 'cats' in topics"
You can also perform logic for topics if you want to include more than one. In which case, replace token with condition and work as per the example above.
Legacy Protocol
https://fcm.googleapis.com/fcm/send
Content-Type:application/json
Authorization:key=AIzaSyZ-1u...0GBYzPu7Udno5aA
{
"to": "aUniqueKey",
...
}
You send your request to the URL shown in the snippet with the headers shown in the snippet. The Authorization Key here is the one you’ll find in the Firebase Console Cloud Messaging Settings. (Not interchangeable with the Authorization Bearer).
Everything after this point applies to both the Standard and Legacy Protocol.
Notification and Data Payload
The payload is essentially the content of your message. Notification payload contains data shown in a notification displayed by the device when the message is received. Data payload contains data that can be received by the app and handled accordingly.
A message can have either or both.
Notification Payload
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
}
}
You have the body and the title tags that work across all platforms. I don’t think I need to explain them.
Data Payload
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
},
"data" : {
"somekey" : "somedata",
"someotherkey" : "somemoredata"
}
}
}
In the data field, you can specify custom key/pair values for your app to receive. The snippet above shows a Cloud Message with both a notification and data payload, however you can just as easily have a message with only a data payload.
Android-Specific Attributes
There’s attributes for all platforms, but since we are an Android-focused blog, we’ll work with that.
{
"message":{
"topic" : "foo-bar",
"notification" : {
"body" : "This is a Firebase Cloud Messaging Topic Message!",
"title" : "FCM Message"
}
"android": {
"priority": "high",
"notification": {
"click_action":"OPEN_ACTIVITY_1"
}
}
}
}
You define Android-specific attributes in a section of its own. Notification and Priority take priority.
Notification allows you to customize your notifications even more, and priority sets your notification priority which can be either “normal” or “high”.
Read More
Check out the other parts of my Firebase Cloud Messaging series:
1. Getting Started with Firebase Cloud Messaging on Android