Firebase Configuration

This page is out of date. Due to fundamentally unclear details about the way firebase credentialing actually, especially w/r APNS, you will have to contact [email protected] and request credential files.

(Everything below this line is informative but will not result in functional push notifications.)

What Is Firebase and Why do I need it?

Firebase is one of the push notification platforms for iOS and Android. Push notifications are sent from the data processing servers that you launch using the launch script in the cluster_management folder of the Beiwe Backend. You need to set up a Firebase account, generate and download credentials, and then upload them by logging in as a Site Admin user (usually the default_admin user) and clicking Manage Firebase Credentials at the top of the site.

This addition to Beiwe is necessary due to iOS and Android system design changes that have occurred since the Beiwe project's inception. Consistent background task operations have become less and less reliable, with no fully reliable option existing on either platform anymore. Push notifications allow us to gain some ground back, and specifically solving issues with survey notifications. It also lets you build more complex survey schedules.

Much of the Firebase website assumes you are a software developer. You will encounter several items in the process below related to programming languages and directions on what to do with the credentials when you download them. Ignore all of that. All you need to do is generate and download the credentials.

Setup Directions:

1. Create a firebase account at https://firebase.google.com/ Firebase is operated by Google and requires a Google account.

2. Create a Firebase project. There should be an obvious button on the Firebase main page to go to the console. From there you will be prompted to open or create a project.

   a. You do not need to enable Google Analytics, but it might be helpful in the future, especially if you are involved in the github issues.

3. Generate a private key for your account:

   a. In the Firebase console, click on the gear icon in the on the upper left and select Project Settings.

   b. Go to Service Accounts. (Reminder: ignore all the programming details and directions)

   c. You may be prompted to create a service account, if so follow the directions to do so.

   d. Click Generate New Private Key, then confirm by clicking Generate Key, it will download your new credential file.

   e. Make sure to save a backup copy of your key somewhere secure.

   f. Go to your Beiwe website, and log in as a site administrator user (usually default_admin) and upload this file under the section for the Firebase Notification Certificate.

4. Prepare to generate iOS and Android credential files. These are pushed to the Beiwe app when someone registers on your studies. They must be present and correct at the time of registration.

   a. In the Firebase console, click on the gear icon in the on the upper left and select Project Settings.

   b. Under General, scroll down until you see the 'Your apps' section.

   c. There are several buttons, among them one that says iOS, and one with that... little robot-Android-mascot-head thing.

5. Generate an iOS credential file:

   a. Click the (iOS) button.

   b. You will be navigated to a page with 3 fields to ender, but only one required field labelled "iOS bundle ID". Ignore the optional fields, enter harvard.lab.onnela.beiwe.ios for the bundle ID, and click Register App.

   c. It will take a few seconds, and then you will be able to download a file named GoogleService-info.plist, do so.

   d. Click the next button, and then do so again until you are past the Add Firebase SDK and Add Initialization Code sections.

   e. It will say that you are all set, and provide you with a link back to the console. Click it.

   f. On your Beiwe website as an admin user, upload the GoogleService-Info.plist under the IOS Firebase Notification Certificate section.

   g. Troubleshooting: when you upload the .plist file, if the Beiwe web interface gives you the error 'We are expecting a plist file with at least the following keys: "STORAGE_BUCKET", "API_KEY" and "DATABASE_URL"', open the .plist file in a text editor and check if the DATABASE_URL key is missing. If it's missing, go back to the Firebase console, go to "Realtime Database" in the left sidebar, create a database, deactivate the database (so you don't get billed for it), and then download the .plist file again- it should have the DATABASE_URL key this time.

6. Generate an Android credential file:

   a. When you return to project settings the interface will have changed slightly because you have now created an iOS app. Click the "Add app" button in the upper right of the "Your apps" section, and click the Android icon.

   b. This process is almost identical to the process for iOS, except the single optional field is labelled "Android package name". Enter org.beiwe.app and click Register App.

   c. Download the google-services.json file, and then upload this file as the Android Firebase services file on your beiwe server.

   d. Click through the rest of the app registration process until you are returned to the Project Settings page.

If anything's not working, read Celery troubleshooting.