OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Step-by-Step Android Native 3.x to 4.x Upgrade Guide

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.

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 '[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

3.3 To the match the new initialization

// OneSignal Initialization

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

:white-check-mark: 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.

Updated 9 months ago

Step-by-Step Android Native 3.x to 4.x Upgrade Guide

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.