Step 1 - Requirements

This guide assumes you already have set up the OneSignal-Android-SDK 3.x.x and are migrating your app to the 4.x Major version.

❗️

New - AndroidX Required

Most Android projects have already updated to AndroidX from the "Android Support Library" since it is now the default for new projects. This is a requirement to use the new OneSignal-Android-SDK 4.0.0 and newer.
If you haven't please follow Google's Migrating to AndroidX Guide before getting started.

❗️

New - Requires Java 1.8

In your app/build.gradle set your compileOptions *Compatibility properties to VERSION_1_8 as required by AndroidX.

Gradle

android {
   // Must also use 16 or greater for a min Android SDK level
   minSdkVersion 16

   compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
   }
}

Step 2 - Update app/build.gradle

2.1 In your app/build.gradle, under the dependencies section replace com.onesignal:OneSignal:[3.0.0, 4.99.99] with com.onesignal:OneSignal:[4.0.0, 4.99.99].

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

2.2 Remove onesignal_app_id and onesignal_google_project_number from your manifestPlaceholders section.

• Save your onesignal_app_id value, you will need it for the next step.

// If these are the only two entries you may remove this whole section
		manifestPlaceholders = [
          onesignal_app_id: 'YOUR_ONESIGNAL_APP_ID',
          onesignal_google_project_number: 'REMOTE'
      ]

2.3 For location-based notification support, add the following line to the app/build.gradle, in order for permissions to work correctly.

dependencies {
    implementation 'com.google.android.gms:play-services-location:[17.0.0, 17.99.99]'
}

Step 3 - Update initialization code

3.1 Open your Application class and find you onCreate method.
3.2 Replace the following

// OneSignal Initialization
 OneSignal.startInit(this)
     .inFocusDisplaying(OneSignal.OSInFocusDisplayOption.Notification)
     .unsubscribeWhenNotificationsAreDisabled(true)
     .init();

3.3 To the match the new initialization

// OneSignal Initialization
OneSignal.initWithContext(this);
OneSignal.setAppId("YOUR_ONESIGNAL_APP_ID_HERE");

3.4 Review your existing .inFocusDisplaying usage.

• This was most likely set to OneSignal.OSInFocusDisplayOption.Notification which means no changes are needed since this is the default in 4.x.
• If you didn't have inFocusDisplaying at all in your code or this was None the replacement for this is adding a NotificationWillShowInForegroundHandler.

3.5 Review your unsubscribeWhenNotificationsAreDisabled usage.

• This was most likely true which means you can safely remove unsubscribeWhenNotificationsAreDisabled(true), as this is the default.
• If this was false, you must now call OneSignal.unsubscribeWhenNotificationsAreDisabled(false)

3.6 Review your NotificationExtenderService service usage.

• If you weren't using a NotificationExtenderService then you don't need to change anything
• If you did implement NotificationExtenderService then you will need to remove the service implementation, also remember to remove it from your AndroidManifest.xml. Finally, to continue with the same functionally implement OSRemoteNotificationReceivedHandler instead.

Step 4 - Review Full List

✅ You've successfully set up the new SDK!
Please review the full 4.0 API Reference - Android Native for a full list of new features and other advanced features you may need to migrate as well.