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    Support

Android SDK Setup

OneSignal Android SDK Setup Guide. Also for Amazon apps using Android Studio.

For Developers

Android Studio is the most common way to build Android projects. The following instructions are also applicable if you're using Android Studio to build your Amazon app (see more). If you're still using Eclipse instead of Android studio, follow the guide here instead.

Before proceeding, follow the steps to Generating a Google Server API Key.

1. Gradle Setup

1.1 Open your build.gradle (Module: app) file and add the following to your dependencies.

dependencies {
    compile 'com.onesignal:OneSignal:3.+@aar'
    
    // Required for OneSignal, even if you have added FCM.
    compile 'com.google.android.gms:play-services-gcm:+'
    
    // Required for geotagging
    compile "com.google.android.gms:play-services-location:+"
    
    // play-services-analytics is only needed when using 8.1.0 or older. 
    // compile 'com.google.android.gms:play-services-analytics:+'
}

1.2 In the same build.gradle file, 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"]
    }
 }


2. Add Required Code

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

import com.onesignal.OneSignal;

public class YourAppClass extends Application {
   @Override
   public void onCreate() {
      super.onCreate();
      OneSignal.startInit(this).init();
     
      // Call syncHashedEmail anywhere in your app if you have the user's email.
      // This improves the effectiveness of OneSignal's "best-time" notification scheduling feature.
      // OneSignal.syncHashedEmail(userEmail);
   }
}

Don't have a class that extends Application in your project?
Follow this tutorial to create one.

3. Create a default notification icon

3.1 Starting with Android Lollipop 5.0 a small notification icon is required for the icon to be visible in the status bar. Follow the Customize Notification Icons instructions to create a small notification icon.

4. Add Optional Notification Handlers

NotificationOpenedHandler - This will be called when a notification is tapped on.
See our setNotificationOpenedHandler documentation to add one.

NotificationReceivedHandler - This will be called when a notification is received while your app is running.
See our setNotificationReceivedHandler documentation to add one.

NotificationExtenderService - This can be setup to receive silent notifications when your app is not running or to override how notifications are shown in the notification shade. See the Background Data and Notification Overriding section to set this up.

Next Steps

Android - Setup is done! All AndroidManifest.xml entries are added by our SDK for you. Make sure you are testing push notifications on a device or emulator that has Google Play services installed and updated on it.

Troubleshooting

If run into any issues please see our Android troubleshooting guide, or our general Troubleshooting section.

Additional Documentation

To see all available methods for Android, see our Android Native SDK Reference.






Setup SDK (Eclipse)

Eclipse is an uncommon way to build Android projects.
These instructions are not for Amazon projects built in Eclipse.

Deprecated!

Google no longer support building apps with Eclipse. Their last update to Eclipse was August 2015.
Please follow Google's Android Studio migration guide.

Generate Credentials

Follow the steps to Generating a Google Server API Key.

1. Project setup

'Google Play services' & 'Android Support Library'

OneSignal requires Google Play services (google-play-services_lib) and Android Support Library v4 (android-support-v4.jar). android-support-v13.jar can be used instead if your project already requires it.

1.1. Download the latest OneSignal Android SDK.

1.2. Run the Android SDK Manager and install or update "Android Support Library" and "Google Play services" from the Extras section.

"SDK Path:" is shown on this window, replace <android-sdk> with your path in the steps below.

1.3. Import <android-sdk>\extras\google\google_play_services\libproject\google-play-services_lib project into your workspace. Go to File>Import and then go to Android>Existing Android Code into Workspace.

1.4. Right click on your project and go to Properties. On the left Select Android and then press the "Add..." button in Library section. Pick the google-play-services_lib.

1.5. Next place onesignalsdk.jar and <android-sdk>\extras\android\support\v4\android-support-v4.jar into your project's libs

1.6. Right click on your project to go Properties and select "Java Build Path" on the left. Next click on the "Order and Export" tab and make sure "Android Dependencies" is checked.

2. AndroidManifest.xml

2.1. Add the following permissions to AndroidManifest.xml.

<permission android:name="${manifestApplicationId}.permission.C2D_MESSAGE"
            android:protectionLevel="signature" />
<uses-permission android:name="${manifestApplicationId}.permission.C2D_MESSAGE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="com.google.android.c2dm.permission.RECEIVE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.VIBRATE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />

<!-- START: ShortcutBadger -->
<!-- Samsung -->
<uses-permission android:name="com.sec.android.provider.badge.permission.READ"/>
<uses-permission android:name="com.sec.android.provider.badge.permission.WRITE"/>

<!-- HTC -->
<uses-permission android:name="com.htc.launcher.permission.READ_SETTINGS"/>
<uses-permission android:name="com.htc.launcher.permission.UPDATE_SHORTCUT"/>

<!-- Sony -->
<uses-permission android:name="com.sonyericsson.home.permission.BROADCAST_BADGE"/>
<uses-permission android:name="com.sonymobile.home.permission.PROVIDER_INSERT_BADGE"/>

<!-- Apex -->
<uses-permission android:name="com.anddoes.launcher.permission.UPDATE_COUNT"/>

<!-- Solid -->
<uses-permission android:name="com.majeur.launcher.permission.UPDATE_BADGE"/>

<!-- Huawei -->
<uses-permission android:name="com.huawei.android.launcher.permission.CHANGE_BADGE" />
<uses-permission android:name="com.huawei.android.launcher.permission.READ_SETTINGS" />
<uses-permission android:name="com.huawei.android.launcher.permission.WRITE_SETTINGS" />

<!-- ZUK -->
<uses-permission android:name="android.permission.READ_APP_BADGE"/>

<!-- OPPO -->
<uses-permission android:name="com.oppo.launcher.permission.READ_SETTINGS"/>
<uses-permission android:name="com.oppo.launcher.permission.WRITE_SETTINGS"/>

<!-- End: ShortcutBadger -->

2.2. In your application tag add the following.

<application ...>
  <meta-data android:name="com.google.android.gms.version"
             android:value="@integer/google_play_services_version" />
  <meta-data android:name="onesignal_app_id"
             android:value="${onesignal_app_id}" />

  <receiver android:name="com.onesignal.GcmBroadcastReceiver"
            android:permission="com.google.android.c2dm.permission.SEND" >
    <intent-filter>
      <action android:name="com.google.android.c2dm.intent.RECEIVE" />
      <category android:name="${manifestApplicationId}" />
    </intent-filter>
  </receiver>
  <receiver android:name="com.onesignal.NotificationOpenedReceiver" />
  <service android:name="com.onesignal.GcmIntentService" />
  <service android:name="com.onesignal.SyncService" android:stopWithTask="false" />
  <activity android:name="com.onesignal.PermissionsActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar" />
  
  <service android:name="com.onesignal.NotificationRestoreService" />
  <receiver android:name="com.onesignal.BootUpReceiver">
    <intent-filter>
      <action android:name="android.intent.action.BOOT_COMPLETED" />
      <action android:name="android.intent.action.QUICKBOOT_POWERON" />
    </intent-filter>
  </receiver>
  <receiver android:name="com.onesignal.UpgradeReceiver" >
    <intent-filter>
      <action android:name="android.intent.action.MY_PACKAGE_REPLACED" />
    </intent-filter>
  </receiver>
</application>

2.3 Replace all 3 of instances ${manifestApplicationId} with your package name in AndroidManifest.xml.
2.4 Replace ${onesignal_app_id} with your OneSignal app id.

3. Add Required Code

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

import com.onesignal.OneSignal;

public class YourAppClass extends Application {
   @Override
   public void onCreate() {
      super.onCreate();
      OneSignal.startInit(this).init();
      
      // Sync hashed email if you have a login system or collect it.
      //   Will be used to reach the user at the most optimal time of day.
      // OneSignal.syncHashedEmail(userEmail);
   }
}

Don't have a class that extends Application in your project?
Follow this tutorial to create one.

4. Add Optional Notification Handlers

NotificationOpenedHandler - This will be called when a notification is tapped on.
See our setNotificationOpenedHandler documentation to add one.

NotificationReceivedHandler - This will be called when a notification is received while your app is running.
See our setNotificationReceivedHandler documentation to add one.

NotificationExtenderService - This can be setup to receive silent notifications when your app is not running or to override how notifications are shown in the notification shade. See the Background Data and Notification Overriding section to set this up.

Proguard

If you have proguard enabled on your project you must add the following lines to your proguard config file. (Default name is proguard-project.txt).

-dontwarn com.onesignal.**

-keep class com.google.android.gms.common.api.GoogleApiClient {
    void connect();
    void disconnect();
}

-keep public interface android.app.OnActivityPausedListener {*;}
-keep class com.onesignal.ActivityLifecycleListenerCompat** {*;}

-keep class com.onesignal.shortcutbadger.impl.AdwHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.ApexHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.AsusHomeLauncher { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.DefaultBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.HuaweiHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.LGHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.NewHtcHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.NovaHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.OPPOHomeBader { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.SamsungHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.SonyHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.XiaomiHomeBadger { <init>(...); }
-keep class com.onesignal.shortcutbadger.impl.ZukHomeBadger { <init>(...); }

Next Steps

Troubleshooting

If run into any issues please see our Android troubleshooting guide, or our general Troubleshooting section.

Additional Documentation

Android SDK Setup

OneSignal Android SDK Setup Guide. Also for Amazon apps using Android Studio.

For Developers