📘

For Android mobile apps only - not for websites

This guide is for developers integrating OneSignal with an Android mobile app distributed via the Google Play Store.

• This guide should not be used for Web Push. See Web push setup.
• For Huawei apps distributed via the Huawei App Gallery, see Huawei: Authorizing OneSignal.

To send push notifications to Android devices that download your app via the Google Play Store, you must use Firebase Cloud Messaging (FCM). This guide walks you through generating the required JSON private key file and configuring it in OneSignal.

A Service Account is a secure way for OneSignal to send notifications on your behalf. For more technical details, see Google’s Service Account documentation.

Requirements

• An Android mobile app distributed via the Google Play Store.
• A Firebase Account (free).
• A OneSignal Account.

Setup

1. Create or open your Firebase Project

Go to the Firebase console.

• If you don't have a project yet, click Add project and follow the steps.
• If you already have a project, select it and move to the next steps.

2. Make sure Firebase Cloud Messaging (FCM) API v1 is enabled

1. In Firebase, click the gear icon next to Project Overview > Project settings.

2. Go to the Cloud Messaging tab.

If the Firebase Cloud Messaging API (V1) shows as disabled, click the 3-dot menu > Open in Cloud Console.

In the Cloud Console, click Enable (you may need to wait a few minutes for the action to propagate to Firebase systems).

3. Generate a Service Account JSON file

1. Return to Firebase Project Settings.
2. Go to the Service accounts tab.
3. At the bottom, click Generate new private key.

4. Confirm by clicking Generate key in the popup.

5. Save the .json file in a safe location. 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

These should be included by default for new Firebase projects. If you're using a custom Service Account with restricted permissions, you can add these specific permissions by assigning it the following roles:

• roles/firebasemessaging.admin (includes cloudmessaging.messages.create)
• roles/firebase.viewer (includes firebase.projects.get)

4. Configure your OneSignal app's Android platform settings

1. In your OneSignal dashboard, go to:
   Settings > Push & In-App > Push Platforms > Google Android (FCM)
   Click Activate.

2. Next to the Service Account JSON, click Choose file and upload your .json file.

🚧

Migrating from Legacy FCM?

Select Firebase Cloud Messaging API (V1) from the dropdown.

If unsure which Firebase project to use, match the Sender ID in the legacy settings with your Firebase Project Settings > Cloud Messaging > Sender ID.

3. Click Save and Continue.
4. Choose your SDK and click Save & Continue.

4. Make sure your app uses the correct OneSignal App ID in the code. Follow the Mobile SDK setup for more.

🚧

Check 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!

Your OneSignal app is now connected to Firebase Cloud Messaging (V1). Return to Mobile SDK setup to finish setting up the Mobile SDK or return to Mobile push setup for next steps.

FAQ

Error: “This configuration is for a different Firebase Project...”

This appears when your uploaded JSON file is from a different Firebase project than your current OneSignal config (i.e. a different Sender ID). Using a different Sender ID invalidates previous push tokens.

Fix: Use the JSON file from the original Firebase project, or create a new one and contact [email protected] with your App ID for help. You should try to find the original project because uploading a different Service Account will require all your Android users to open the app again to get push notifications under these new credentials.

Can I change my Sender ID?

No. Changing your Sender ID has the same effect as using a new Service Account JSON file—it invalidates current push tokens. Once you’ve passed 100 users, OneSignal locks the Sender ID to prevent accidental token invalidation.

You should try to find the original project because uploading a different Service Account will require all your Android users to open the app again to get push notifications under these new credentials. If you need to create a new Firebase project, contact [email protected] with the App ID so we can allow this update on your app.

Does switching from Legacy API to V1 require an update?

No. If your app already includes the OneSignal SDK, switching to V1 is handled in the OneSignal dashboard—no code changes or app updates are required.

When is the deadline for FCM v1?

Google began shutting down legacy FCM APIs in July 2024. You may not have been affected immediately. We recommend making this change as soon as you can. See Google's notice for details.

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

If your server key starts with AIz... or looks short (around 40 characters), you’re likely using an old Google Cloud Messaging (GCM) setup. You must now create a new Firebase project and use a Service Account JSON file to continue using push.

How can I check which of my apps still use the Legacy API?

For a full list of apps, use our View apps API. Look for:

• "gcm_key" → using Legacy, needs update
• "fcm_v1_service_account_json" → using V1, ✅
• Neither? App doesn’t use Android push.