Step 1. Requirements

• OneSignal Account
• Your OneSignal App Id, available in Settings > Keys & IDs.
• Android Studio
• An Android 4.0.3+ device or emulator with "Google Play Store (Services)" installed.
• A Google/Firebase Server API Key.
• Project using AndroidX.

Step 2. Add OneSignal SDK

2.1 Open your App build.gradle (Module: app) file, add the following to your dependencies section.

dependencies {
    implementation 'com.onesignal:OneSignal:[4.0.0, 4.99.99]'
}

👍

Sync Gradle

Make sure to press "Sync Now" on the banner that pops up after saving!

Step 3. Add Required Code

3.1 Add the following to the onCreate method in your Application class.

If you don't have an Application class follow our Create Application Class Guide.

Note: The ONESIGNAL_APP_ID can be found in the dashboard Settings > Keys & IDs

import com.onesignal.OneSignal;

public class ApplicationClass extends Application {
    private static final String ONESIGNAL_APP_ID = "########-####-####-####-############";
  
    @Override
    public void onCreate() {
        super.onCreate();
        
        // Enable verbose OneSignal logging to debug issues if needed.
        OneSignal.setLogLevel(OneSignal.LOG_LEVEL.VERBOSE, OneSignal.LOG_LEVEL.NONE);
        
        // OneSignal Initialization
        OneSignal.initWithContext(this);
        OneSignal.setAppId(ONESIGNAL_APP_ID);
      
        // promptForPushNotifications will show the native Android notification permission prompt.
        // We recommend removing the following code and instead using an In-App Message to prompt for notification permission (See step 7)
        OneSignal.promptForPushNotifications();
    }
}

import com.onesignal.OneSignal

const val ONESIGNAL_APP_ID = "########-####-####-####-############"
  
class MainApplication : Application() {
   override fun onCreate() {
      super.onCreate()
        
      // Logging set to help debug issues, remove before releasing your app.
      OneSignal.setLogLevel(OneSignal.LOG_LEVEL.VERBOSE, OneSignal.LOG_LEVEL.NONE)
      
      // OneSignal Initialization
      OneSignal.initWithContext(this)
      OneSignal.setAppId(ONESIGNAL_APP_ID)
   }
}

Step 4. Customize the default notification icons ( strongly recommended )

By default, notifications will be shown with a small bell icon in the notification shade. Follow the Customize Notification Icons guide to create your own small and large notification icons for your app.

Step 5. Run Your App and Send Yourself a Notification

Run your app on a physical device to make sure it builds correctly.

Your Android device should already be subscribed to push notifications. Check your OneSignal Dashboard Audience > All Users to see your Device Record.

Then head over to Messages > New Push to Send your first Push Notification from OneSignal.

📘

Troubleshooting

If running into issues, see our Android troubleshooting guide.

Try the example project on Github.

If stuck, contact support directly or email [email protected] for help.

For faster assistance, please provide:

• Your OneSignal App Id
• Details, logs, and/or screenshots of the issue.
• Steps to reproduce

Step 6. Set Custom User Properties

Recommended
After initialization, OneSignal will automatically collect common user data by default. Use the following methods to set your own custom userIds, emails, phone numbers, and other user-level properties.

Set External User Id

Required if using integrations.
Recommended for messaging across multiple channels (push, email, sms).

OneSignal creates channel-level device records under a unique Id called the player_id. A single user can have multiple player_id records based on how many devices, email addresses, and phone numbers they use to interact with your app.

If your app has its own login system to track users, call setExternalUserId at any time to link all channels to a single user. For more details, see External User Ids.

String externalUserId = "123456789"; // You will supply the external user id to the OneSignal SDK
OneSignal.setExternalUserId(externalUserId);

Set Email and Phone Number

Recommended if using Email and SMS messaging.
Use the provided SDK methods to capture email and phone number when provided. Follow the channel quickstart guides for setup:

• Email Quickstart
• SMS Quickstart

// Pass in email provided by customer
OneSignal.setEmail("[email protected]");

// Pass in phone number provided by customer
OneSignal.setSMSNumber("+11234567890");

Data Tags

Optional
All other event and user properties can be set using Data Tags. Setting this data is required for more complex segmentation and message personalization.

OneSignal.sendTag("key", "value");

Step 7. Implement a Soft-Prompt In-App Message

It is recommended that apps create an alert, modal view, or other interface that describes the types of information they want to send and gives people a clear way to opt in or out.

OneSignal provides an easy option for a "soft-prompt" using In-App Messages to meet this recommendation and have a better user experience. This also permits you to ask for permission again in the future, since the native permission prompt can no longer be shown in your app if the user clicks deny.

See our Push Opt-In Prompt Guide for details on implementing this.

👍

Setup Complete!

Visit Mobile Push Tutorials for next steps.