Skip to main content
This guide walks you through adding OneSignal to your Android app using Android Studio. You’ll install our SDK, set up push and in-app messages, and send test messages to confirm everything is working. If this is your first time using OneSignal, follow the steps in order. If you’re experienced, feel free to jump to the sections you need.
Using an AI coding assistant? For AI-driven installation, use this prompt:

Step 0. Configure FCM in OneSignal (required to deliver push)

You can install and initialize the OneSignal Android SDK without completing this step. However, push notifications will not deliver until Firebase Cloud Messaging (FCM) credentials are configured in your OneSignal app.
If your company already has a OneSignal account, ask to be invited as an admin role to configure the app. Otherwise, sign up for a free account to get started.
These steps connect your OneSignal app to Firebase Cloud Messaging (FCM). You only need to do this once per app.
  1. Log in to https://onesignal.com and create or select your App.
  2. Navigate to Settings > Push & In-App.
  3. Select Google Android (FCM) and Continue through the setup wizard.
  4. Upload your FCM Service Account JSON.
  5. Continue through the setup wizard to get your App ID. This will be used to initialize the SDK.
For full setup instructions, see our Mobile push setup guide.

Setup contract & requirements

This section summarizes the tools, versions, and assumptions used throughout the guide.
  • SDK version: 5.6.1+ (latest: check releases)
  • AI setup instructions: https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md
  • SDK repo: https://github.com/OneSignal/OneSignal-Android-SDK
  • Android Studio: Meerkat | 2024.3.1+
  • Android API: 23+ minimum (Android 6.0+), 31+ recommended (Android 12+)
  • Device/emulator: Android 7.0+ with Google Play Services installed
  • Required dependency: com.onesignal:OneSignal:[5.6.1, 5.99.99]
  • Application class: Required for proper SDK initialization
  • App ID format: 36-character UUID (example: 12345678-1234-1234-1234-123456789012). Find it at Dashboard > Settings > Keys & IDs.
  • Initialize: OneSignal.initWithContext(this, "YOUR_APP_ID")
  • Battery optimization: May affect background notifications
  • Recommended: Assign External ID via OneSignal.login("user_id") to unify users across devices

Android setup steps

By the end of the steps below, you will have:
  • The OneSignal SDK installed and initialized in your Android app
  • Push notification permissions prompting correctly on a real device
  • A test push and in-app message successfully delivered
If you skipped Step 0 (Configuring FCM in OneSignal), you can still complete the Android Studio setup below. Complete Step 0 before you test or send push notifications.

Step 1. Add the OneSignal SDK

  1. In Android Studio, open your build.gradle.kts (Module: app) or build.gradle (Module: app) file
  2. Add OneSignal to your dependencies section:

Example shows adding OneSignal to your App's build.gradle.kts file.

  1. Sync Gradle: Click Sync Now in the banner that appears or go to File > Sync Project with Gradle Files
Verify that the gradle sync completes successfully without dependency conflicts.

Step 2. Create and configure Application class

It’s best practice to initialize OneSignal in the onCreate method of your Application class to ensure proper SDK setup across all entry points. Create an Application class if you don’t already have one:
  1. File > New > Kotlin Class/File (or Java Class)
  2. Name: ApplicationClass (or your preferred name)

Example shows creating a new Kotlin class named ApplicationClass.

Add the following OneSignal code to the Application class. Replace YOUR_APP_ID with your actual OneSignal App ID from the Dashboard > Settings > Keys & IDs.

Example ApplicationClass.kt file.

Initializing in an Activity (like MainActivity) is not recommended because it may not be called on app cold-starts from deep links or notifications. Always initialize OneSignal in your Application class for reliability.
Register the Application class:
  1. Open your app’s AndroidManifest.xml
  2. In your <application> tag add android:name=".ApplicationClass" (replace .ApplicationClass with your actual class name if set it to something different).
AndroidManifest.xml
Check your <application> tag for tools:node="replace". That marker drops library-merged components, including OneSignal’s PermissionsActivity. The notification permission flow then crashes with ActivityNotFoundException. Remove tools:node="replace". If you only need to override one attribute, use tools:replace="android:theme" (or the attribute you are changing).

AndroidManifest.xml with the .ApplicationClass name.

Verify that the app builds and runs without errors.
Replace the default bell icon with a small icon named ic_stat_onesignal_default. Use a monochrome silhouette on a transparent background, or Android will render a white square.
  1. Generate densities with Android Asset Studio.
  2. Place ic_stat_onesignal_default in each density folder: res/drawable-mdpi/ (24×24) through res/drawable-xxxhdpi/ (96×96).
See Notification icons for large icons, accent color, and Android 17 launcher-icon behavior.

Step 4. Test the integration

Verify Subscription creation:
  1. Launch app on a device or emulator with Google Play Services.
  2. Check Dashboard > Audience > Subscriptions. Status shows Never Subscribed.
  3. Accept the permission prompt when it appears.
  4. Refresh the dashboard. Status changes to Subscribed.

Android push permission prompt

Dashboard showing Subscription with 'Never Subscribed' status

After allowing push permissions, refresh the dashboard to see the Subscription status update to 'Subscribed'

A mobile Subscription is created when the user first opens your app on a device, or if they uninstall and reinstall on the same device. After they accept the permission prompt, the dashboard status should show Subscribed.

Create test user and segment

  1. Next to the Subscription, select Options > Add as test user and enter a name.
  2. Go to Audience > Segments > New Segment.
  3. Name: Test Users, add filter Test Users > Create Segment.

Add a test user

Create a 'Test Users' segment with the Test Users filter

You can now send test messages to this device and to the Test Users segment.

Send test push via API

  1. Navigate to Settings > Keys & IDs.
  2. In the provided code, replace YOUR_APP_API_KEY and YOUR_APP_ID in the code below with your actual keys. This code uses the Test Users segment we created earlier.

Images will appear small in the collapsed notification view. Expand the notification to see the full image.

Delivery stats showing confirmed receipt (unavailable on free plans)

Confirm the test device received a notification with your custom icon (if configured) and the large image when expanded. On paid plans, Dashboard > Delivery > Sent Messages can show Confirmed receipt.
  • No notification received? See Mobile push not shown.
  • No custom icon? Verify the icon name is ic_stat_onesignal_default and in the correct drawable folders.
  • Having issues? Copy-paste the api request and a log from start to finish of app launch into a .txt file. Then share both with support@onesignal.com.

Test in-app messages

  1. Close app for 30+ seconds
  2. Dashboard > Messages > In-App > New In-App > select Welcome template
  3. Audience: Test Users segment
  4. Trigger: On app open
  5. Schedule: Every time trigger conditions are satisfied
  6. Click Make Message Live
  7. Open app

Targeting the 'Test Users' segment with an in-app message

Example customization of in-app Welcome message

In-app message scheduling options

Welcome in-app message shown on devices

The test device should show the Welcome in-app message. See In-app messages setup for more details.
Not seeing the message?
  • Start a new session
  • Still in the Test Users segment?
    • If you reinstalled or switched devices, re-add the device to Test Users and confirm it’s part of the Test Users segment.
  • Having issues?
    • Follow Getting a Debug Log while reproducing the steps above. This will generate additional logging that you can share with support@onesignal.com and we will help investigate what’s going on.
You now have Subscriptions, Test Users, and a Segment. You sent push with an image via the Create message API and an in-app message. Continue below to identify users and add more features.
You have successfully set up the OneSignal SDK and learned important concepts like:Continue with this guide to identify users in your app and setup additional features.

Common Errors & Fixes

User management

Previously, we demonstrated how to create mobile Subscriptions. Now we’ll expand to identifying Users across all their Subscriptions (including push, email, and SMS) using the OneSignal SDK. Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend’s user identifier. This keeps messaging unified across channels and third-party systems.
OneSignal generates unique read-only IDs for Subscriptions (Subscription ID) and Users (OneSignal ID).Setting the External ID via our SDK is highly recommended to identify users across all their subscriptions, regardless of how they are created.Learn more about the login method in the SDK reference.

Add Tags & Custom Events

Tags and Custom Events both add data to users. Tags are key-value strings for user properties (like username, role, or status). Custom Events use JSON and usually represent actions (like new_purchase or abandoned_cart). Both can power Message Personalization and Journeys.
See Tags and Custom Events for more detail.

Add email and/or SMS subscriptions

You can reach users through email and SMS in addition to push. If the email address or phone number already exists in the OneSignal app, the SDK adds it to the existing user and does not create duplicates. Call login() first so the address attaches to the identified user.

A user profile with push, email, and SMS subscriptions unified by External ID

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.

To control when OneSignal collects user data, use the SDK’s consent gating methods. Call consentRequired before initWithContext.

Prompt for push permissions

Instead of calling requestPermission() immediately on app open, take a more strategic approach. Use an in-app message to explain the value 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

Use SDK listeners to react to user actions and state changes. Add these in your Application class after OneSignal.initWithContext().

Push notification events

User state changes

This example uses the push subscription observer. The user state observer and notification permission observer are in the Mobile SDK reference.

In-app message events

Additional in-app message methods are in the Mobile SDK reference.

Advanced setup and capabilities

Android-specific features

Universal features

For full SDK method documentation, see the Mobile SDK reference.

FAQ

Why can’t Android Studio resolve OneSignal?

The SDK dependency is missing or Gradle has not synced. Add com.onesignal:OneSignal:[5.6.1, 5.99.99] to your app module build.gradle and use File > Sync Project with Gradle Files.

Why is my Application class not found?

The class is not registered in the manifest. Add android:name=".ApplicationClass" (or your class name) to the <application> tag in AndroidManifest.xml.

Why does the emulator say Google Play Services is not available?

The emulator image does not include Play Services. Use a device with the Play Store, or an emulator system image that includes Google APIs.

Why does the notification show the default Android icon?

The small icon is missing or misnamed. Add ic_stat_onesignal_default to each res/drawable-* density folder. See Notification icons.

Why did my test device not receive a push?

FCM credentials are not configured, or the device is not subscribed. Complete Step 0 and confirm the Subscription status is Subscribed. Then see Mobile push not shown.

Why aren’t in-app messages showing?

In-app messages require a new session. Force-quit the app, or background it for at least 30 seconds, then reopen. Confirm the device is still in the Test Users segment. See Sessions and how in-app messages are displayed.

What causes Manifest merger failed?

Conflicting <application> android:name values or duplicate permissions. Search your merged manifest for a second Application class and keep a single android:name.

Why do battery optimizations block notifications?

Some OEMs restrict background work. Ask users to disable battery optimization for your app if notifications stop after the device sleeps.

How do I get more log output?

Set OneSignal.Debug.logLevel = LogLevel.VERBOSE (Kotlin) or OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE) (Java), reproduce the issue, and capture logcat. See Getting a debug log.
Need help?Chat with our Support team or email support@onesignal.comPlease include:
  • Details of the issue you’re experiencing and steps to reproduce if available
  • Your OneSignal App ID
  • The External ID or Subscription ID if applicable
  • The URL to the message you tested in the OneSignal Dashboard if applicable
  • Any relevant logs or error messages
We’re happy to help!