Android SDK setup

This guide walks you through adding OneSignal to your Android app using Android Studio. You’ll install our SDK, setup 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:

Integrate the OneSignal Android SDK into this codebase.

Follow the instructions at:
https://raw.githubusercontent.com/OneSignal/sdk-ai-prompts/main/docs/android/ai-prompt.md

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.

Steps to configure your OneSignal app.

These steps connect your OneSignal app to Firebase Cloud Messaging (FCM). You only need to do this once per app.

Login to https://onesignal.com and create or select your App.
Navigate to Settings > Push & In-App.
Select Google Android (FCM) and Continue through the setup wizard.
Input your Firebase Server Key or Service Account details.
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.2.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.9.99]
Application class: Required for proper SDK initialization
App ID format: 36-character UUID (example: 12345678-1234-1234-1234-123456789012) — find at OneSignal 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

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

implementation("com.onesignal:OneSignal:[5.6.1, 5.9.99]")

implementation 'com.onesignal:OneSignal:[5.6.1, 5.9.99]'

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

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:

File > New > Kotlin Class/File (or Java Class)
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.

// FILE: ApplicationClass.kt
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml

package com.your.package.name // Replace with your actual package name

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 to debug issues (remove in production)
        OneSignal.Debug.logLevel = LogLevel.VERBOSE

        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initWithContext(this, "YOUR_APP_ID")

        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        CoroutineScope(Dispatchers.IO).launch {
            OneSignal.Notifications.requestPermission(false)
        }
    }
}

// FILE: ApplicationClass.java
// PURPOSE: Initialize OneSignal when your app launches
// REQUIREMENT: Must be registered in AndroidManifest.xml

package com.your.package.name; // Replace with your actual package name

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 to debug issues (remove in production)
        OneSignal.getDebug().setLogLevel(LogLevel.VERBOSE);
        
        // Replace with your 36-character App ID from Dashboard > Settings > Keys & IDs
        OneSignal.initWithContext(this, "YOUR_APP_ID");
        
        // Prompt user for push notification permission
        // In production, consider using an in-app message instead for better opt-in rates
        OneSignal.getNotifications().requestPermission(false, Continue.none());
    }
}

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:

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).

AndroidManifest.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>

Verify that the app builds and runs without errors.

Step 3. Configure default notification icons (recommended)

Customize notification icons to match your app’s branding. This step is optional but recommended for a professional appearance.

Step 4. Test the integration

Verify Subscription creation:

Launch app on device or emulator with Google Play Services
Check Dashboard > Audience > Subscriptions — status shows “Never Subscribed”
Accept the permission prompt when it appears
Refresh dashboard — status changes to “Subscribed”

Example of the iOS and Android push permission prompts. — Example of the iOS and Android push permission prompts

You have successfully created a mobile Subscription. Mobile subscriptions are created when users first open your app on a device or if they uninstall and reinstall your app on the same device.

Create test user and segment

Click ⋮ next to the Subscription > Add to Test Users > name it
Go to Audience > Segments > New Segment
Name: Test Users, add filter Test Users > Create Segment

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

You have successfully created a segment of test users.We can now test sending messages to this individual device and groups of test users.

Send test push via API

Navigate to Settings > Keys & IDs.
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.

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

Images in push notifications appear small in the collapsed notification view. Expand the notification to see the full image. — 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). — Delivery stats showing confirmed receipt (unavailable on free plans)

Verify the test device received a notification with:

Your custom icon (if configured)
Large image when expanded
Dashboard > Delivery > Sent Messages shows “Confirmed” status (unavailable on free plans).

No notification received? See Mobile push not shown.
No custom icon? Verify the icon name is onesignal_small_icon_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

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

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

Example customization of in-app Welcome message. — Example customization of in-app Welcome message

In-app message scheduling options. — In-app message scheduling options

Welcome in-app message shown on devices. — Welcome in-app message shown on devices

Verify the test device received an in-app message. See the In-app messages setup guide for more details.

Not seeing the message?

Start a new session
- You must close or background the app for at least 30 seconds before reopening. This ensures a new session is started.
- For more, see how in-app messages are displayed.
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 have successfully set up the OneSignal SDK and learned important concepts like:

Gathering Subscriptions, setting Test Users, and creating Segments.
Sending Push with images 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.

Common Errors & Fixes

Error / Symptom	Cause	Fix
`Cannot resolve symbol 'OneSignal'`	SDK dependency not added or gradle not synced	Add dependency to build.gradle and sync project
`Application class not found`	Application class not registered in manifest	Add `android:name=".ApplicationClass"` to `<application>` tag
`Google Play Services not available`	Emulator/device missing Play Services	Use device with Play Store or emulator with Google APIs
Push received but default Android icon	Custom icon not configured or wrong name	Create notification icon asset named `onesignal_small_icon_default`
No push notifications received	FCM not configured in OneSignal	Complete Step 0: Configure FCM credentials in OneSignal dashboard
In-app messages not showing	Session not started or network issues	Close app 30+ seconds, reopen, check internet connection
`Manifest merger failed`	Conflicting manifest attributes	Check for duplicate application names or permissions conflicts
Battery optimization blocking notifications	Device power management	Guide users to disable battery optimization for your app
Can’t diagnose issue	Not enough log info	Add verbose logging and check logcat output for errors

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.

Assign External ID (recommended)

Use an External ID to identify users consistently across devices, email addresses, and phone numbers using your backend’s user identifier. This ensures your messaging stays unified across channels and 3rd party systems. See our Mobile SDK reference for more details and Java code examples.

Kotlin

// Call when user logs in or is identified, safe to call multiple times
// Typically used in a login completion handler, or on app launch if already authenticated
fun onUserAuthenticated(userId: String) {
    OneSignal.login(userId)
}

// If you want to remove the External ID from the Subscription, setting it to an anonymous user
fun onUserLoggedOut() {
    OneSignal.logout()
}

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 guide.

Add Tags & Custom Events

Tags and Custom Events are both ways to add data to your users. Tags are key-value strings and are generally associated with user properties (like username, role, or status) while Custom Events have a JSON format and are usually associated with actions (like new_purchase, abandoned_cart, and associated properties). Both can be used to power advanced Message Personalization and Journeys. See our Mobile SDK reference for more details and Java code examples.

Kotlin

// Add a tag when the user's name is set
OneSignal.User.addTag("username", "john_doe")

// Create a custom event when user abandoned a cart
val properties = mapOf(
    "product_id" to "123456",
    "product_name" to "Product Name",
    "product_price" to 100,
    "product_quantity" to 1
)
OneSignal.User.trackEvent("abandoned_cart", properties)

More details on how to use Tags and Custom Events in the Tags and Custom Events guides.

Add email and/or SMS subscriptions

You can reach users through email and SMS channels in addition to push notifications. If the email address and/or phone number already exist in the OneSignal app, the SDK will add it to the existing user — it will not create duplicates. See our Mobile SDK reference for more details and Java code examples.

Kotlin

// Add email subscription
// Call when user provides their email (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addEmail("user@example.com")

// Add SMS subscription
// Use E.164 format: + country code + number
// Call when user provides their phone number (e.g., account creation, settings update) after calling OneSignal.login("user_id")
OneSignal.User.addSms("+15551234567")

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. See our Mobile SDK reference for more details and Java code examples.

Kotlin

// In ApplicationClass onCreate(), BEFORE OneSignal.initWithContext()
// Use this if your app requires GDPR or other privacy consent before data collection
OneSignal.consentRequired = true

// Later, after user grants consent (e.g., taps "I Agree" on your consent screen)
OneSignal.consentGiven = true

See our Privacy & security docs for more on:

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

Kotlin

// Add click listener to handle when users tap notifications
val clickListener = object : INotificationClickListener {
  override fun onClick(event: INotificationClickEvent) {
    Log.d("OneSignal", "Notification clicked: ${event.notification.title}")
  }
}
OneSignal.Notifications.addClickListener(clickListener)

User state changes

Example shows how to use push subscription observer. Other user state events like the user state observer and notification permission observer are available in the Mobile SDK Reference.

Kotlin

// Add subscription observer to track push subscription changes
class MyObserver : IPushSubscriptionObserver {
  init {
    OneSignal.User.pushSubscription.addObserver(this)
  }

  override fun onPushSubscriptionChange(state: PushSubscriptionChangedState) {
    if (state.current.optedIn) {
      println("User is now opted-in with push token: ${state.current.token}")
    }
  }
}

In-app message events

Additional in-app message methods are available in the Mobile SDK Reference.

Kotlin

// Add click listener for in-app message interactions
val clickListener = object : IInAppMessageClickListener {
  override fun onClick(event: IInAppMessageClickEvent) {
    print(event.result.actionId)
  }
}
OneSignal.InAppMessages.addClickListener(clickListener)

Advanced setup & capabilities

Android-specific features

Notification Channels — Organize notifications into categories (Android 8.0+)
Service Extensions — Advanced notification customization
Huawei/HMS Support — Alternative to Google Play Services

Universal features

Deep Linking — Navigate users to specific screens from notifications
Action Buttons — Add interactive buttons to notifications
Identity Verification — Secure user identification
Location Tracking — Location-based targeting
Integrations — Connect with analytics and data platforms
Multi-language Messaging — Localized notifications

For full SDK method documentation, visit the Mobile SDK Reference.

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!

Developer Documentation

Mobile SDKs

Web SDKs

Live Activities

Desktop & Watch Setup

Legacy SDK reference

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

Setup contract & requirements

Android setup steps

Step 1. Add the OneSignal SDK

Step 2. Create and configure Application class

Step 3. Configure default notification icons (recommended)

Step 4. Test the integration

Create test user and segment

Send test push via API

Test in-app messages

Common Errors & Fixes

User management

Assign External ID (recommended)

Add Tags & Custom Events

Add email and/or SMS subscriptions

Prompt for push permissions

Listen to push, user, and in-app events

Push notification events

User state changes

In-app message events

Advanced setup & capabilities

Android-specific features

Universal features

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

​Setup contract & requirements

​Android setup steps

​Step 1. Add the OneSignal SDK

​Step 2. Create and configure Application class

​Step 3. Configure default notification icons (recommended)

​Step 4. Test the integration

​Create test user and segment

​Send test push via API

​Test in-app messages

​Common Errors & Fixes

​User management

​Assign External ID (recommended)

​Add Tags & Custom Events

​Add email and/or SMS subscriptions

​Privacy & user consent

​Prompt for push permissions

​Listen to push, user, and in-app events

​Push notification events

​User state changes

​In-app message events

​Advanced setup & capabilities

​Android-specific features

​Universal features

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

Setup contract & requirements

Android setup steps

Step 1. Add the OneSignal SDK

Step 2. Create and configure Application class

Step 3. Configure default notification icons (recommended)

Step 4. Test the integration

Create test user and segment

Send test push via API

Test in-app messages

Common Errors & Fixes

User management

Assign External ID (recommended)

Add Tags & Custom Events

Add email and/or SMS subscriptions

Privacy & user consent

Prompt for push permissions

Listen to push, user, and in-app events

Push notification events

User state changes

In-app message events

Advanced setup & capabilities

Android-specific features

Universal features