Overview

Android push notifications are essential for driving sustained user engagement and retention in your Android app. They empower you to deliver real-time updates, reminders, and personalized messages directly to your users, improving the overall user experience and stickiness of your app. OneSignal leverages Firebase Cloud Messaging (FCM) but is designed to provide even more flexibility and functionality as shown in this guide.

Requirements

• Android 7.0+ device or emulator with "Google Play Store (Services)" installed.
• Android Studio (setup instructions use Android Studio Meerkat).
• Configured OneSignal app and platform.

Configure your OneSignal app and platform

Required

Before enabling push notifications, make sure your app is set up with the platforms you support— Apple (APNS), Google (FCM), Huawei (HMS), and/or Amazon (ADM). Follow the steps below to configure your OneSignal account and platform settings.

If your team already has a OneSignal account, ask to be invited as an admin role so you can configure the app. Otherwise, sign up for a free account to get started.

Details on configuring your OneSignal app (click to expand)

You can configure multiple platforms (iOS, Android, Huawei, Amazon) within a single OneSignal app.

1. Create or select your app

• Select your app and go to Settings > Push & In-App to add platforms to an existing app.
• Or create a new app by clicking New App/Website.

2. Set up and activate a platform

• If creating an app, choose a recognizable app and organization name.
• Select a platform to activate.
• Click Next: Configure Your Platform.

3. Configure platform credentials

Follow the prompts based on your platforms:

• Android: Set up Firebase Credentials
• iOS: p8 Token (Recommended) or p12 Certificate
• Amazon: Generate API Key
• Huawei: Authorize OneSignal

Click Save & Continue after entering your credentials.

4. Choose target SDK

Select your app's target SDK and click Save & Continue.

5. Install SDK and save your App ID

You’ll be shown your OneSignal App ID — make sure to save it, as you’ll need it during SDK installation.

If needed, invite a teammate or developer by clicking Invite, then click Done.

Continue through the rest of our documentation to complete the integration.

Android Setup

1. Add SDK

In Android Studio, open your build.gradle.kts (Module: app) or build.gradle (Module: app) file and add OneSignal to your dependencies.

implementation("com.onesignal:OneSignal:[5.1.6, 5.1.99]")

implementation 'com.onesignal:OneSignal:[5.1.6, 5.1.99]'

A Gradle build defines the project and its tasks and dependencies. Here we are declaring the OneSignal SDK as an external dependency for the project. For more details, please view Gradle's documentation on Build Scripts.

Sync Gradle

Make sure to sync your changes. Press Sync Nowon the banner or select File > Sync Project with Gradle Files.

2. Initialize SDK

It is highly recommended to initialize OneSignal in the onCreate method in your Application class.

Details on creating an Application Class (click to expand)

Create a new class (example: ApplicationClass) and add the following code.

KotlinJava

import android.app.Application

class ApplicationClass : Application() {
   override fun onCreate() {
      super.onCreate()
      // TODO: Add OneSignal initialization here
   }
}

import android.app.Application;

public class ApplicationClass extends Application {
  
    @Override
    public void onCreate() {
      super.onCreate();
      // TODO: Add OneSignal initialization here
        
    }
}

Open your app's AndroidManifest.xml

In your <application> tag add android:name=".ApplicationClass" (replace .ApplicationClass with your actual class name if set it to something different).

XML

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools">
  
   <application
        android:name=".ApplicationClass"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        ...
    </application>
  
</manifest>

In your Application file, initialize OneSignal with the provided methods.

Replace YOUR_APP_ID with your OneSignal App ID found in your OneSignal dashboard Settings > Keys & IDs. If you don't have access to the OneSignal app, ask your Team Members to invite you.

import android.app.Application
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch

import com.onesignal.OneSignal
import com.onesignal.debug.LogLevel
  
class ApplicationClass : Application() {
   override fun onCreate() {
      super.onCreate()
        
      // Enable verbose logging for debugging (remove in production)
      OneSignal.Debug.logLevel = LogLevel.VERBOSE
      // Initialize with your OneSignal App ID
      OneSignal.initWithContext(this, "YOUR_APP_ID")
      // Use this method to prompt for push notifications.
      // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
      CoroutineScope(Dispatchers.IO).launch {
         OneSignal.Notifications.requestPermission(true)
      }
   }
}

import android.app.Application;

import com.onesignal.Continue;
import com.onesignal.OneSignal;
import com.onesignal.debug.LogLevel;

public class ApplicationClass extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Enable verbose logging for debugging (remove in production)
        OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);
        // Initialize with your OneSignal App ID
        OneSignal.initWithContext(this, "YOUR_APP_ID");
        // Use this method to prompt for push notifications.
        // We recommend removing this method after testing and instead use In-App Messages to prompt for notification permission.
        OneSignal.getNotifications().requestPermission(false, Continue.none());

    }
}

📘

Using an Activity instead of the recommended Application setup?

OneSignal requires an Android Context to track when your app enters the foreground. Since an Activity is a type of Context, you can initialize the SDK in an Activity like MainActivity. However, this is not recommended.

Initializing OneSignal only in MainActivity may cause issues in edge cases—such as when the app is cold-started and opens directly into a different Activity. In such cases, MainActivity.onCreate() won't be called, and the SDK won't be properly initialized.

✅ Best practice: Initialize OneSignal in your Application class to ensure it’s set up no matter how your app is launched.

3. Customize default icons

Set up your notification icons to match your app's branding. If you skip this step, OneSignal will display a default bell icon.

Testing

This guide will help you verify that your OneSignal SDK integration is functioning correctly. You'll test push notifications, subscription management, and in-app messaging.

Check mobile subscriptions

1. Launch your app on a test device.
2. You should immediately see the native push permission prompt because of the requestPermission method added in the initialization step above.
3. IMPORTANT: Before responding to the prompt, check your OneSignal dashboard:
   • Navigate to Audience > Subscriptions.
   • You should see a new entry with status "Never Subscribed".

4. Return to the app and tap "Allow" on the permission prompt.
5. Refresh your OneSignal dashboard Subscription's page.
6. The subscription's status should now show "Subscribed".

Setup test subscriptions

Test subscriptions are helpful for testing a push notification before sending a message.

Next to the subscription, click Options (three dots button) and select Add to Test Subscriptions.

Name your subscription so you know its your device and can find it in the Test Subscriptions page.

Create a test users segment

To test push and in-app messages faster, navigate to Audience > Segments > New Segment.

Name the segment Test Users (the name is important because it will be used later) and add the Test Users filter. Click Create Segment when finished.

Send test push via API

Test sending a push notification via our API.

In your OneSignal dashboard, navigate to Settings > Keys & IDs. Copy the following code into your terminal, replacing YOUR_APP_API_KEY and YOUR_APP_ID with the correct IDs found in Keys & IDs.

curl -X \
POST --url 'https://api.onesignal.com/notifications' \
 --header 'content-type: application/json; charset=utf-8' \
 --header 'authorization: Key YOUR_APP_API_KEY' \
 --data \
 '{
  "app_id": "YOUR_APP_ID",
  "target_channel": "push",
  "name": "Testing basic setup",
  "headings": {
  	"en": "👋"
  },
  "contents": {
    "en": "Hello world!"
  },
  "included_segments": [
    "Test Users"
  ],
  "ios_attachments": {
    "onesignal_logo": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
  },
  "big_picture": "https://avatars.githubusercontent.com/u/11823027?s=200&v=4"
}'

Check images and confirmed delivery

If all setup steps were completed successfully, the test devices should receive a notification with an image included:

After the message is received, in your OneSignal dashboard, go to Delivery > Sent Messages and click on the message to see the message report.

You should see the confirmed stat, meaning the device received the push.

If on our Professional plan or higher, you can scroll down to the Audience Activity section to see the confirmed delivery for individual devices:

Send an in-app message

In-app messages are a great way to communicate information at specific points while users are in your app.

1. Close or background your app on the device.
2. In your OneSignal dashboard, navigate to Messages > In-App > New In-App.
3. Find and select the Welcome message.
4. Set your Audience as the Test Users segment we used previously.

5. Add any quick customizations you want.

6. Verify the Trigger is set to On app open.
7. Under Schedule > How often do you want to show this message? select Every time trigger conditions are satisfied.
8. Click Make Message Live so it is available to your Test Users each time they open the app.

8. After the in-app message is live, open your app. You should see it display:

If you did not see the in-app message:

Make sure you started a new session.

In step 1, we mentioned you need to close or background your app on the device. This is because users must meet the in-app audience criteria before a new session starts. In OneSignal, a new session starts when the user opens your app after it has been in the background or closed for at least 30 seconds. For more details, see our guide on how in-app messages are displayed.

Put the app into the background or close it. Wait 30 seconds, then open the app again. It should appear.

Make sure you are still in the Test Users segment.

If you uninstalled the app and re-installed it or testing on a different device, make sure to set the new subscription as a test subscription. Then try again. See Subscriptions for more details.

📘

Still having issues?

Follow Getting a Debug Log while reproducing the steps above. This will generate additional logging that you can share with [email protected] and we will help investigate what's going on.

👍

Testing complete!

You have successfully setup the OneSignal SDK and learned important concepts like:

• Gathering Subscriptions, setting Test subscriptions, and creating Segments.
• Sending Push with images and Confirmed Delivery using Segments and our Create message API.
• Sending In-app messages.

Continue with this guide to identify users in your app and setup additional features.

User identification

Previously we demonstrated the concept of Subscriptions by creating a mobile subscription. Now we will take a look at how to identify Users across all their subscriptions including how to create email and sms subscriptions via the SDK.

Assign External ID

Assign users an External ID to reference them using your backend's identifier. The External ID should be readily available in your app and map to other 3rd party systems you may be using to identify users. This is especially important for Integrations.

Set the External ID with our SDK's login method each time they are identified by your app.

📘

Subscription ID, OneSignal ID, & External ID

OneSignal generates unique read-only IDs for subscriptions (Subscription ID) and users (OneSignal ID).

As users download your app on different devices, subscribe to your website, and/or provide you email addresses and phone numbers outside of your app, new subscriptions will be created.

Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.

Add data tags

Data Tags (or just "tags") are used to set user properties and track events. They enable Message Personalization and more unique Segmentation allowing for more advanced use cases.

Set tags with our SDK addTag(s) methods and see our Tags guide for more details.

In this example, the app has added the user's current in-game level as a tag called current_level set to a value of 6:

We can create a segment of users that have a level of between 5 and 10, and use that to send targeted and personalized messages:

Add email and/or SMS subscriptions

Earlier we saw how our SDK creates mobile Subscriptions to send push and in-app messages. You can also reach users through emails and SMS channels by creating the appropriate subscriptions.

When users provide consent to receive additional communication types, use our SDK addEmail method and addSms method to create these subscriptions.

Best practices for multi-channel communication

• Obtain explicit consent before adding email or SMS subscriptions.
• Explain the benefits of each communication channel to users.
• Provide channel preferences so users can select which channels they prefer.

After adding subscriptions under and External ID, you can view all channels associated with each user in the OneSignal dashboard Audience > Users > Find their External ID or using the View user API.

Privacy

If you want to prevent OneSignal from collecting user data until user consent is provided, you can implement the setConsentRequired() method. When you or the user is ready to send our servers data, call the setConsentGiven() method.

See our Privacy & security docs for more details including Data Collected by the OneSignal SDK and Handling Personal Data.

Prompt for push permissions

While we showed the requestPermission method earlier in the setup code, we recommend a more strategic approach to asking for push permissions.

Instead of prompting immediately on app open, use in-app messages to explain the benefits of push notifications before requesting permission.

For best practices and implementation details, see our Prompt for push permissions guide.

Listen to push, user, and in-app events

The SDK provides several event listeners for you to hook into. See our SDK reference guide for more details.

Handling push clicks and foreground events

Track when users interact with push notifications using the addClickListener method. This is helpful for Deep Linking.

Control notification behavior when your app is in the foreground using the addForegroundLifecycleListener method with preventDefault to conditionally decide to display it or not.

If you want to customize the notification before it is displayed to the user, see the Mobile Service Extensions docs for details.

Listening to user state changes

Track when the External ID is set with the addObserver() method for user state . This is a good place to collect the OneSignal ID and/or Subscription ID if needed.

Track the user's specific interaction with the push permission prompt with the addPermissionObserver() method.

Track when the push subscription status changes with the addObserver() method for push.

Listen and handle in-app message events

Track when and how the user interacts with in-app messages with the addClickListener() method for in-app. This is a good place for Deep Linking with in-app messages or doing something custom when specific elements are clicked.

If you are interested in tracking the in-app message lifecycle from before it is displayed to after it is dismissed, use the addLifecycleListener() method.

Advanced

Review the Mobile push setup doc to make sure you are setting up all the features. Common examples:

• Migrating to OneSignal from another service – If you are moving to OneSignal or need to use multiple push SDKs in your app.
• Location tracking – Setup and ask permission to track user location points for segmentation.
• Deep Linking – Direct users to specific app content when interacting with notifications.
• Integrations – Setup Mixpanel, Amplitude, HubSpot, Segment, and more!
• Mobile Service Extensions – Customizing the notification before it is displayed.
• Action buttons – Add custom actions to your notifications instead of just opening the app.
• Multi-language messaging - How to send messages in different languages.
• Identity Verification – Prevent bad actors from impersonating your users.
• Custom Outcomes – Track user actions from notifications, such as purchases.
• Live Activities – Another messaging channel to update iOS users in real time.