API Reference

[block:api-header] { "type": "basic", "title": "List of Methods" } [/block] [init](#init) [sendTag](#sendTag) [sendTags](#sendTags) [getTags](#getTags) [deleteTag](#deleteTag) [deleteTags](#deleteTags) [IdsAvailable](#IdsAvailable) [enableVibrate](#enableVibrate) [enableSound](#enableSound) [enableNotificationsWhenActive](#enableNotificationsWhenActive) [enableInAppAlertNotification](#enableInAppAlertNotification) [setSubscription](#setSubscription) [postNotification](#postNotification) [promptLocation](#promptLocation) [clearOneSignalNotifications](#clearOneSignalNotifications) [cancelNotification](#cancelNotification) [setLogLevel](#setLogLevel) [block:api-header] { "type": "basic", "title": "List of Handler Interfaces" } [/block] [NotificationOpenedHandler](#NotificationOpenedHandler) [IdsAvailableHandler](#IdsAvailableHandler) [GetTagsHandler](#GetTagsHandler) [block:html] { "html": "<br><br><br>" } [/block] [block:api-header] { "type": "basic", "title": "Methods" } [/block] [block:html] { "html": "<a name=\"init\">" } [/block] #### init Initializes OneSignal to register the device for push notifications. Should be call in the onCreate of your Application class. **Builder options** * `setAutoPromptLocation(boolean)` * `setNotificationOpenedHandler(NotificationOpenedHandler)` __Example__ [block:code] { "codes": [ { "code": "public class YourAppClass extends Application {\n @Override\n public void onCreate() {\n super.onCreate();\n OneSignal.startInit(this)\n .setAutoPromptLocation(true)\n .setNotificationOpenedHandler(new YourNotificationOpenedHandler())\n .init();\n }\n}", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"sendTag\">" } [/block] #### sendTag Tag a user based on an app event of your choosing so later you can create segments on [onesignal.com](https://onesignal.com) to target these users. Recommend using sendTags over sendTag if you need to set more than one tag on a user at a time. - __Parameters__ - __`String` _key___ - Key of your choosing to create or update. - __`String` _value___ - Value to set on the key. - _NOTE:_ Passing in a blank String deletes the key, you can also call deleteTag or deleteTags. __Example__ [block:code] { "codes": [ { "code": "OneSignal.sendTag(\"key\", \"value\");", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"sendTags\">" } [/block] #### sendTags Tag a user based on an app event of your choosing so later you can create segments on [onesignal.com](https://onesignal.com) to target these users. - __Parameters__ - __`JSONObject` _keyValues___ - Key value pairs of your choosing to create or update. - _NOTE:_ Passing in a blank String as a value deletes the key, you can also call deleteTag or deleteTags. __Example__ [block:code] { "codes": [ { "code": "\tJSONObject tags = new JSONObject();\n\ttags.put(\"key1\", \"value1\");\n\ttags.put(\"key2\", \"value2\");\n\tOneSignal.sendTags(tags);", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"getTags\">" } [/block] #### getTags Retrieve a list of tags that have been set on the user from the OneSignal server. - __Parameters__ - __`GetTagsHandler` _handler___ - Calls `tagsAvailable` on the Object once the tags are available. __Example__ [block:code] { "codes": [ { "code": "OneSignal.getTags(new GetTagsHandler() {\n\t\t@Override\n\t\tpublic void tagsAvailable(JSONObject tags) {\n\t\t\tLog.d(\"debug\", tags.toString());\n\t\t}\n\t});", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"deleteTag\">" } [/block] #### deleteTag Deletes a tag that was previously set on a user with `sendTag` or `sendTags`. Use `deleteTags` if you need to delete more than one. - __Parameters__ - __`String` _key___ - Key to remove. __Example__ [block:code] { "codes": [ { "code": "OneSignal.deleteTag(\"key\");", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"deleteTags\">" } [/block] #### deleteTags Deletes tags that were previously set on a user with `sendTag` or `sendTags`. - __Parameters__ - __`Collection<String>` _keys___ - Keys to remove. __Example__ [block:code] { "codes": [ { "code": "Collection<String> tempList = new ArrayList<String>();\ntempList.add(key);\nOneSignal.deleteTags(tempList);", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"IdsAvailable\">" } [/block] #### idsAvailable Lets you retrieve the OneSignal user id and the Google registration id. Your handler is called after the device is successfully registered with OneSignal. - __Parameters__ - __`IdsAvailableHandler` _handler___ - Calls `tagsAvailable` on the Object when the user id is available. __Example__ [block:code] { "codes": [ { "code": "OneSignal.idsAvailable(new IdsAvailableHandler() {\n\t\t@Override\n\t\tpublic void idsAvailable(String userId, String registrationId) {\n\t\t\tLog.d(\"debug\", \"User:\" + userId);\n\t\t\tif (registrationId != null)\n\t\t\t\tLog.d(\"debug\", \"registrationId:\" + registrationId);\n\t\t}\n\t});", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"enableVibrate\">" } [/block] ### enableVibrate *You can call this from your UI from a button press for example to give your user's options for your notifications.* By default OneSignal always vibrates the device when a notification is displayed unless the device is in a total silent mode. Passing false means that the device will only vibrate lightly when the device is in it's vibrate only mode. __Example__ [block:code] { "codes": [ { "code": "OneSignal.enableVibrate(false);", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"enableSound\">" } [/block] ### enableSound *You can call this from your UI from a button press for example to give your user's options for your notifications.* By default OneSignal plays the system's default notification sound when the device's notification system volume is turned on. Passing false means that the device will only vibrate unless the device is set to a total silent mode. __Example__ [block:code] { "codes": [ { "code": "OneSignal.enableSound(false);", "language": "java" } ] } [/block] <br><div id="enableNotificationsWhenActive"> #### enableNotificationsWhenActive By default this is false and notifications will not be shown when the user is in your app, instead the NotificationOpenedHandler is fired. If set to true notifications will always show in the notification area and NotificationOpenedHandler will not fire until the user taps on the notification. __Parameters__ - __`boolean` _enable___ __Example__ [block:code] { "codes": [ { "code": "OneSignal.enableNotificationsWhenActive(true);", "language": "java" } ] } [/block] <br><div id="enableInAppAlertNotification"> #### enableInAppAlertNotification By default this is false and notifications will not be shown when the user is in your app, instead the NotificationOpenedHandler is fired. If set to true notifications will be shown as native alert boxes if a notification is received when the user is in your app. The NotificationOpenedHandler is then fired after the alert box is closed. __Parameters__ - __`boolean` _enable___ __Example__ [block:code] { "codes": [ { "code": "OneSignal.enableInAppAlertNotification(true);", "language": "java" } ] } [/block] <br><div id="setSubscription"> #### setSubscription You can call this method with false to opt users out of receiving all notifications through OneSignal. You can pass true later to opt users back into notifications. __Parameters__ - __`boolean` _enable___ __Example__ [block:code] { "codes": [ { "code": "OneSignal.setSubscription(false);", "language": "java" } ] } [/block] <br><div id="postNotification"> #### postNotification Allows you to send notifications from user to user or schedule ones in the future to be delivered to the current device. __Parameters__ - __`JSONObject` _parameters___ - JSONObject of notification options, see our [create notification POST](http://documentation.onesignal.com/v2.0/docs/notifications-create-notification) call for all options. - __`PostNotificationResponseHandler` _handler___ - delegate fires when the notification was created or fails to be created. - __`void onSuccess(JSONObject response)` __ - Json response from OneSignal's server. - __`void onFailure(JSONObject response)` __ - Json response from OneSignal's server. __Example__ [block:code] { "codes": [ { "code": "try {\n OneSignal.postNotification(new JSONObject(\"{'contents': {'en':'Test Message'}, 'include_player_ids': ['\" + userId + \"']}\"), null);\n} catch (JSONException e) {\n e.printStackTrace();\n}", "language": "java", "name": "Simple" }, { "code": "try {\n OneSignal.postNotification(new JSONObject(\"{'contents': {'en':'Test Message'}, 'include_player_ids': ['\" + \"userId\" + \"']}\"),\n new OneSignal.PostNotificationResponseHandler() {\n @Override\n public void onSuccess(JSONObject response) {\n Log.i(\"OneSignalExample\", \"postNotification Success: \" + response.toString());\n }\n\n @Override\n public void onFailure(JSONObject response) {\n Log.e(\"OneSignalExample\", \"postNotification Failure: \" + response.toString());\n }\n });\n} catch (JSONException e) {\n e.printStackTrace();\n}", "language": "java", "name": "With Response Handler" } ] } [/block] See the [create notification](http://documentation.onesignal.com/v2.0/docs/notifications-create-notification) REST API POST call for a list of all possible options. Note: You can only use `include_player_ids` as a targeting parameter from your app. Other target options such as `tags` and `included_segments` require your OneSignal App REST API key which can only be used from your server. <br><div id="promptLocation"> #### promptLocation Prompts the user for location permissions. This allows for geotagging so you can send notifications to users based on location. *Note:* Make sure you also have the required location permission in your AndroidManifest.xml. __Example__ [block:code] { "codes": [ { "code": "OneSignal.promptLocation();", "language": "java" } ] } [/block] <br><div id="clearOneSignalNotifications"> #### clearOneSignalNotifications Removes all OneSignal notifications from the Notification Shade. If you just use `NotificationManager.cancelAll();` OneSignal notifications will be restored your app is restarted. __Example__ [block:code] { "codes": [ { "code": "OneSignal.clearOneSignalNotifications();", "language": "java" } ] } [/block] <br><div id="cancelNotification"> #### cancelNotification Cancels a single OneSignal notification based on its Android notification integer id. Use instead of `NotificationManager.cancel(id);` otherwise the notification will be restored when your app is restarted. __Example__ [block:code] { "codes": [ { "code": "int id = 1234;\nOneSignal.cancelNotification(id);", "language": "java" } ] } [/block] <br><div id="setLogLevel"> #### setLogLevel Enable logging to help debug if you run into an issue setting up OneSignal. The following options are available with increasingly more information; NONE, FATAL, ERROR, WARN, INFO, DEBUG, VERBOSE __Parameters__ - __`LOG_LEVEL` _logLevel___ - Sets the logging level to print to the Android LogCat log. - __`LOG_LEVEL` _visualLevel___ - Sets the logging level to show as alert dialogs. __Example__ [block:code] { "codes": [ { "code": "OneSignal.setLogLevel(OneSignal.LOG_LEVEL.DEBUG, OneSignal.LOG_LEVEL.DEBUG);", "language": "java" } ] } [/block] [block:html] { "html": "<br><br><br>" } [/block] [block:api-header] { "type": "basic", "title": "Handler Interfaces" } [/block] [block:html] { "html": "<a name=\"NotificationOpenedHandler\">" } [/block] #### NotificationOpenedHandler Interface containing the method `notificationOpened` which you can implement to process information on the notification the user just opened. [block:html] { "html": "<a name=\"notificationOpened\">" } [/block] #### notificationOpened - __Parameters__ - __`String` _message___ - The message text the user seen in the notification. - __`JSONObject` _additionalData___ - Key value pairs that were set on the notification. - **`String` actionSelected** - Contains the id of the button pressed if Action Buttons were set on the notification. Will be "\_\_DEFAULT\_\_" if there were buttons but the notification itself was tapped on. - **`JSONArray` stacked\_notifications** - Contains a JSONObject for each notification that exists in the stack. "message" as well as keys listed above and ones you set with additional data will be available - __`boolean` _isActive___ - True if your app was currently being used when a notification came in. __Example__ [block:code] { "codes": [ { "code": "@Override\npublic static void notificationOpened(String message, JSONObject additionalData, boolean isActive) {\n String messageTitle;\n AlertDialog.Builder builder = null;\n\n if (additionalData != null) {\n if (additionalData.has(\"discount\"))\n messageTitle = \"Discount!\";\n else if (additionalData.has(\"bonusCredits\"))\n messageTitle = \"Bonus Credits!\";\n else\n messageTitle = \"Other Extra Data\";\n\n builder = new AlertDialog.Builder(this)\n .setTitle(messageTitle)\n .setMessage(message + \"\\n\\n\" + additionalData.toString());\n }\n else if (isActive) // If a push notification is received when the app is being used it does not display in the notification bar so display in the app.\n builder = new AlertDialog.Builder(this)\n .setTitle(\"OneSignal Message\")\n .setMessage(message);\n\n // Add your app logic around this so the user is not interrupted during gameplay.\n if (builder != null)\n builder.setCancelable(true)\n .setPositiveButton(\"OK\",null)\n .create().show();\n}", "language": "java" } ] } [/block] If want to process a notification before it is clicked or want to handle receiving a silent notification see our [Background Data documentation](/v2.0/docs/android-notification-customizations#background-data-silent-notifications). [block:html] { "html": "<br>" } [/block] [block:html] { "html": "<a name=\"IdsAvailableHandler\">" } [/block] #### IdsAvailableHandler Interface which you can implement and pass to `OneSignal.idsAvailable` to get the OneSignal userId and the Google registration Id. #### IdsAvailable - __Parameters__ - __`String` _userId___ - OneSignal userId is a UUID formatted string.(_unique per device per app_) - __`String` _registrationId___ - Registration Id is a Google assigned identifier(_unique per device per app and changes on reinstalls_). [block:callout] { "type": "warning", "title": "NOTE", "body": "Might be `null` if Google play services are not installed on the device or there was a connection issue." } [/block] __Example__ [block:code] { "codes": [ { "code": "OneSignal.idsAvailable(new IdsAvailableHandler() {\n @Override\n\t public void idsAvailable(String userId, String registrationId) {\n\t Log.d(\"debug\", \"User:\" + userId);\n\t\t if (registrationId != null)\n\t\t\t Log.d(\"debug\", \"registrationId:\" + registrationId);\n\t }\n});", "language": "java" } ] } [/block] [block:html] { "html": "<a name=\"GetTagsHandler\">" } [/block] #### GetTagsHandler Interface which you can implement and pass to `OneSignal.getTags` to get the all the tags set on a user from onesignal.com. [block:html] { "html": "<a name=\"tagsAvailable\">" } [/block] #### tagsAvailable - __Parameters__ - __`JSONObject` _tags___ - JSONObject of key value pairs retrieved from the OneSignal server __Example__ [block:code] { "codes": [ { "code": "OneSignal.getTags(new GetTagsHandler() {\n @Override\n\tpublic void tagsAvailable(JSONObject tags) {\n\t\tLog.d(\"debug\",\"Current Tags on User:\" + tags.toString());\n\t}\n});", "language": "java" } ] } [/block]

OneSignal Push Notification Service Documentation

Introduction

iOS

Android

Amazon

Windows Phone

Chrome Apps/Extensions

Mac OS X

Website Push

Corona SDK

Unity SDK

Marmalade SDK

Adobe Air

PhoneGap, Cordova, Ionic

Xamarin SDK

React Native

Cocos2d-x

Server REST API

Troubleshooting

Miscellaneous