Building a Firebase Cloud Messaging App – Part One

One of the demo apps I’ve been showing as I do talks around the world is a basic Firebase Cloud Messaging one — where I build an Android app that registers itself with a very simple app server (running at http://www.laurencemoroney.com/fcm/homepage.php)

When you go to this page you can then send a notification to all registered devices, or just pick one. I’ve had lots of requests for source code and advice in how to build one of these, so I figured I’ll blog it here.

The Architecture

There’s a lot of concepts at play here — using FCM, building an app server, building a client app and registering it etc. So let’s take a look at how this would work step by step. It’s also really worth reading this page: https://firebase.google.com/docs/cloud-messaging/server — in particular for getting the authorization key that you’ll need later.

First of all, your app needs to talk to FCM to get an Instance token. This token is used to identify the device and not the person using the device. Once it has gotten this from FCM, then FCM can, in future direct messages to this device using this identifier.

Step 1. Getting an Instance token from FCM

For building apps like this you should consider FCM to be a simple ‘black box’ API that you give commands to and it responds on your behalf. If you want to know what the instance IDs are for your users you need to store them yourself, and the simplest way to do this is with your own app server. So, step 2 would be to pass these details to your app server so it can store them for you!

Step 2. Sending Instance tokens to your app server

Once your app server has the instance tokens, it can then talk to FCM on your behalf — commanding it to send messages to devices, groups, topics etc. This is shown in step 3.

Step 3. App Server tells FCM to send messages to devices

That’s pretty much it for the architecture for a simple app/server that uses FCM. In the next section we’ll look at how to build a simple App server — using the code from the one at http://laurencemoroney.com/fcm/homepage.php.

Building the App Server

Important: This source code is for demonstration and learning purposes only. Under no circumstances should you use it in a production environment!

The simple app server used here has three main functions:

  1. Accept posts from the app with instance tokens and store them in a database
  2. Create a page with a list of all tokens, and forms that allow you to send a message to one or all registered devices
  3. Tell FCM to send the desired message to the desired device(s)

Let’s take a look at each of these in turn.

Storing the Instance Tokens

In this example I just created a simple MySQL database to store the token and the time it was registered with the app server. The SQL to create a table to store these is here:

And then in your PHP you need to accept a POST from the client, carrying the token:

This uses the ‘storeUser’ function from the ‘db_functions.php’ file that I created for modularity. Here’s the code:

Pretty straightforward stuff. Next up we’ll take a look at the page the lists all teh tokens, and allows you to send a message to one or all of the devices registered to these tokens.

Listing the registered devices

This is the heart of the UI of the app server’s web site. It’s a simple page that creates a form for each of the tokens that is saved in the database. It then generates a form for each of these, and another form that can be used to ‘send to all’. The core of this is in the javascript code. It receives a parameter from the form which is either ‘all’ (when you choose to send to all), or the id corresponding to the token id for a particular form. It then calls lm_send.php, passing it the message text and either ‘all’ or a specific token.

Here’s the code:

So, for example, when you run this page, you’ll see something like this:

Entering the message in the top form will pass ‘all’ to the Javascript function, where entering into one of the others will send the contents of the token (i.e. e_v8g…)

…and that’s it. So, let’s now take a look at lm_send.php which tells FCM to deliver the message for you…

Sending the message

Sending the message is then simply a case of calling the FCM endpoint for sending a message and passing it your command in it’s desired format. This is documented here: https://firebase.google.com/docs/cloud-messaging/send-message

For a single device, it’s pretty straightforward — just send to the regid that was passed into this function. When it’s ‘all’ you just query your db for each of them, and store them in an array.

As I used PHP it was easy to then just use curl to send the message!

And that’s it for this part of the tutorial. In part 2, I’ll talk about the other side of this — the Android app, and what I did to get the instance token, register it with this server, and then respond to incoming messages.

As always, any questions, hit me up on twitter: @lmoroney