📘

For Android Mobile Apps Only, Not For Websites

This guide is for developers implementing OneSignal in an Android mobile application for distribution on the Google Play App Store. This guide should not be used for Web Push.

A Google Service Account is a special type of account from Google that applications use to make authorized calls to a variety of APIs, including Firebase Cloud Messaging APIs. For more details, see Google's own documentation on Service Accounts. In order to send push notifications to Android devices, you will need a Service Account to generate a private key for OneSignal to utilize.

Requirements

• Android mobile app, Chrome app, or Chrome extension
• Firebase Account
• OneSignal Account

Setup

1. Create or Open your Firebase Project

Push Notifications require a Firebase Project. If you don't have one set up yet, login to your Firebase console, click Add project and follow directions to set up your project.

If you already have a FCM project, skip to Step 2.

2. Ensure Firebase Cloud Messaging API (V1) is Enabled

If you've just created a new project, this should already be enabled by default and you can skip this step. However, if you are using an existing Firebase project, especially an older one, ensure Cloud Messaging API (V1) is enabled.

In your project, click the Gear icon next to "Project Overview" in the top left of the left-hand menu and select Project settings. Select the Cloud Messaging tab.

If Firebase Cloud Messaging API (V1) is disabled, then click the kebab menu icon on the top right corner and open the link.

On the subsequent page, click Enable. You may need to wait a few minutes for the action to propagate to Firebase systems.

3. Generate a Private Key JSON file

Back in your Firebase Project Settings, go to the Service accounts tab.

Click Generate new private key at the bottom of the page.

You will see a warning window. Click Generate key.

Save the JSON file somewhere secure. You will need it shortly.

📘

Required Permissions

The following Service Account permissions are required for push notifications to work:

• cloudmessaging.messages.create
• firebase.projects.get

4. Configure Your OneSignal App's Android Platform Settings

In OneSignal, navigate to Settings > Platforms > Google Android (FCM) > Activate

Next to "Service Account JSON" select Choose file and upload the JSON file you downloaded from your Firebase project.

🚧

Migrating from Legacy FCM settings?

If migrating from Legacy FCM settings, you will need to select Firebase Cloud Messaging API (V1) from the dropdown menu before uploading the JSON file.

If you need help finding your project, use the Sender ID saved under your legacy credentials to find the right Firebase project.

Click Save and Continue.

Select the SDK you are using for your app development and click Save & Continue.

Finally, check that you used the same OneSignal App ID in your app's OneSignal initialization code, then run the app on your Android device. You can then check for subscribed users before clicking Done to complete this setup.

🚧

Checking for Subscribed Users

This is only for setting up FCM for the first time. If you are updating credentials or upgrading from to FCM v1, please ignore this step.

👍

Done!

You are now connected to FCM with this OneSignal App and can send push notifications to your Android app. 🥳

Return to Mobile Setup for next steps.

FAQ

Why do I see this error? _"This configuration is for a different Firebase Project. By proceeding, all current subscriptions will become invalid until the user returns to your app. You will not be able to message users that do not return to your app.

Learn more."_

This error means that the file you are uploading is from a project that has a different Sender ID than the project currently used in your Android configuration. Since the push token on each of your users' devices is tied to the legacy Sender ID, updating to the new JSON file for a different Firebase project would invalidate the push tokens.

If you cannot get a JSON file for the original Firebase Project, you will need to create a new Firebase project and follow the steps above to get a Service Account JSON file. You can then contact [email protected] with the OneSignal App ID(s) and we will assist you in updating the app.

Can I change my Sender ID instead of using FCM V1?

No, this is the same as uploading a JSON file for a different project. It would result in the same 1 hour wait after the user opens the app, this is why we do not allow this sender ID to change after 100 users. It is an unnecessary step and you should instead provide the JSON file here if you plan on using a different project.

Does switching from Legacy API to V1 require an update?

No. This is handled entirely from the OneSignal dashboard. If you already have the Android SDK in your app, no action is needed anywhere else.

When is the actual deadline?

July 2024 per Google's announcement here. However, it is not guaranteed that we will keep the ability to use the Legacy API until this deadline. We recommend making this change as soon as you can.

Why don't I have a Sender ID on OneSignal?

If you reveal your server key (Android Configuration settings for Legacy API) and it is a string that starts with 'AIz...' or it looks to only be ~40 characters long, this is a predecessor to the FCM legacy API, when it was Google Cloud Messaging. Ideally you should have created a Firebase project at some point since this change, if not you'll need to do so now. Unfortunately, this is being deprecated alongside the FCM Server Key and Sender ID, and you will still need to generate a JSON file for a Firebase project that has a service account.

How can I check to see which apps are still using the Legacy API?

If you would like a full list of apps that you have access to, you can use the View Apps endpoint to pull a full list of apps and all of the configurations for them. If you see "gcm_key" has a value, it needs to be updated. If you see "fcm_v1_service_account_json" has a value, it is done. If you don't see either, this app is not using Android.