🚧

4.x Beta released

Currently, the OneSignal-Android-SDK 4.x is in beta. Please try it out and give us feedback via Github!
If you wish to setup the main line SDK, continue on this page

Step 1 - Requirements

• An Android Mobile App, this is not required for Web Push which supports Android devices automatically.
• A OneSignal Account - Your OneSignal App ID, available in Keys & IDs
• A Google/Firebase Server API Key
• An Android 4.0.3 or newer device or emulator with "Google Play services" installed.
• Android Studio

Step 2 - Add OneSignal Dependencies

2.1 Open your app/build.gradle (Module: app) file, add the following to the very top.

buildscript {
    repositories {
        maven { url 'https://plugins.gradle.org/m2/'}
    }
    dependencies {
        classpath 'gradle.plugin.com.onesignal:onesignal-gradle-plugin:[0.12.9, 0.99.99]'
    }
}
apply plugin: 'com.onesignal.androidsdk.onesignal-gradle-plugin'

repositories {
    maven { url 'https://maven.google.com' }
}

2.2 Add the following to your dependencies section.

dependencies {
    implementation 'com.onesignal:OneSignal:[3.15.4, 3.99.99]'
}

2.3 Add the following in your android > defaultConfig section.

• Update PUT_YOUR_ONESIGNAL_APP_ID_HERE` with your OneSignal App id

android {
   defaultConfig {
      manifestPlaceholders = [
          onesignal_app_id: 'PUT_YOUR_ONESIGNAL_APP_ID_HERE',
          // Project number pulled from dashboard, local value is ignored.
          onesignal_google_project_number: 'REMOTE'
      ]
    }
 }

👍

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

import com.onesignal.OneSignal;

public class YourAppClass extends Application {
   @Override
   public void 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.startInit(this)
        .inFocusDisplaying(OneSignal.OSInFocusDisplayOption.Notification)
        .unsubscribeWhenNotificationsAreDisabled(true)
        .init();
   }
}

import com.onesignal.OneSignal

class YourAppClass : 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.startInit(this)
         .inFocusDisplaying(OneSignal.OSInFocusDisplayOption.Notification)
         .unsubscribeWhenNotificationsAreDisabled(true)
         .init()
   }
}

Step 4 - Create a default notification icon

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

Step 5 - Run and test your app

If your project is using AndroidX you will need to make sure Jetifier is enabled to be compatible with OneSignal.
In your gradle.properties file, set the following two flags to true

android.useAndroidX=true
android.enableJetifier=true

Run your app on a device or the Android emulator to make sure your device is subscribed to notifications and can receive notifications sent from the OneSignal dashboard.

📘

Troubleshooting

If you run into any issues please see our Android troubleshooting guide

You can see a fully implemented example project on Github.

Step 6 - Customize what your app does when a notification is clicked or received (Optional)

Notification Handlers

NotificationOpenedHandler - This will be called when a notification is tapped on.

NotificationReceivedHandler - This will be called when a notification is received.

Notification Extender Service

Set up the NotificationExtenderService if you want to do one of the following:

• Receive data in the background with or without displaying a notification.
• Override specific notification settings depending on client side app logic such as custom accent color, vibration pattern, or other any other NotificationCompat options available.

Step 7 - Implement other OneSignal features

• Notification Delivery Settings - Learn about the many customizations and methods you can use to send notifications to your users in our Sending Push Messages guide.

• Automated Messages - Set up Automated Messages to automatically re-engage app users who have lapsed or abandoned their cart. Learn more in our Automated Messages guide.

• Segments and Tags - OneSignal supports simple and powerful tagging and segmentation to send messages to relevant users through our dashboard and API. Learn more in our Segments guide.

• In-App Messages - OneSignal supports In-App Messaging in order to display rich content to your users or to present permission prompts, surveys, promotions, announcements, and more. Learn more in our In-App Messaging Overview.

• E-Mail Support - OneSignal supports the delivery and automation of e-mail in addition to push notifications. Learn more in our Email Overview.

• Android SDK API - Explore other methods available in our Android SDK in Android Native SDK API Documentation.

• Remote API - Send notifications, import data, and export data using our simple and powerful API. Learn more in our OneSignal API overview..