API Reference

[block:callout] { "type": "warning", "title": "3.0 SDK Update", "body": "A number the methods and classes below are only available on our new 3.0 SDK.\nPlease follow our [Upgrading to SDK 3.0](upgrading-to-sdk-30) guide if you are still on our 2.0 version." } [/block] [block:api-header] { "type": "basic", "title": "Initialization Builder Methods" } [/block] [init](#init) [setNotificationOpenedHandler](#setNotificationOpenedHandler) [setNotificationReceivedHandler](#setNotificationReceivedHandler) [inFocusDisplaying](#inFocusDisplaying) [autoPromptLocation](#autoPromptLocation) [disableGmsMissingPrompt](#disableGmsMissingPrompt) [block:api-header] { "type": "basic", "title": "List of Methods" } [/block] [startInit](#startInit) [sendTag](#sendTag) [sendTags](#sendTags) [getTags](#getTags) [deleteTag](#deleteTag) [deleteTags](#deleteTags) [IdsAvailable](#IdsAvailable) [enableVibrate](#enableVibrate) [enableSound](#enableSound) [setSubscription](#setSubscription) [postNotification](#postNotification) [promptLocation](#promptLocation) [syncHashedEmail](#syncHashedEmail) [clearOneSignalNotifications](#clearOneSignalNotifications) [cancelNotification](#cancelNotification) [setLogLevel](#setLogLevel) [block:api-header] { "type": "basic", "title": "List of Handler Interfaces" } [/block] [NotificationOpenedHandler](#NotificationOpenedHandler) [NotificationReceivedHandler](#NotificationReceivedHandler) [IdsAvailableHandler](#IdsAvailableHandler) [GetTagsHandler](#GetTagsHandler) [block:api-header] { "type": "basic", "title": "List of Classes" } [/block] [OSNotificationOpenResult](#OSNotificationOpenResult) [OSNotification](#OSNotification) [OSNotificationAction](#OSNotificationAction) [OSNotificationPayload](#OSNotificationPayload) <br> <br> [block:api-header] { "type": "basic", "title": "Initialization Builder Methods" } [/block] <div id="init"> #### init Initializes OneSignal to register the device for push notifications. Should be called in the `onCreate` method of your Application class. __Example__ [block:code] { "codes": [ { "code": "OneSignal.startInit(this).init();", "language": "java" } ] } [/block] <br> <div id="setNotificationOpenedHandler"> #### setNotificationOpenedHandler Sets a notification opened handler. The instance will be called when a notification is tapped on from the notification shade or when closing an Alert notification shown in the app. __Parameters__ - [NotificationOpenedHandler](#NotificationOpenedHandler) - `handler` - Instance to a class implementing this interference. __Example__ [block:code] { "codes": [ { "code": "OneSignal.startInit(this) \n .setNotificationOpenedHandler(new ExampleNotificationOpenedHandler())\n .init();", "language": "java" } ] } [/block] See the documentation on the [NotificationOpenedHandler](#NotificationOpenedHandler) documentation for an example of the `ExampleNotificationOpenedHandler` class. <br> <div id="setNotificationReceivedHandler"> #### setNotificationReceivedHandler Sets a notification received handler. The instance will be called when a notification is received whether it was displayed or not. __Parameters__ - [NotificationReceivedHandler](#NotificationReceivedHandler) - `handler` - Instance to a class implementing this interference. __Example__ [block:code] { "codes": [ { "code": "OneSignal.startInit(this) \n .setNotificationReceivedHandler(new ExampleNotificationReceivedHandler())\n .init();", "language": "java" } ] } [/block] See the documentation on the [NotificationReceivedHandler](#NotificationReceivedHandler) documentation for an example of the `ExampleNotificationReceivedHandler` class. <br> <div id="inFocusDisplaying"> #### inFocusDisplaying Setting to control how OneSignal notifications will be shown when one is received while your app is in focus. By default this is set to in app alert box. __Parameters__ - **OSInFocusDisplayOption** - `displayOption` - Options are `None`, `InAppAlert`, and `Notification`. __Example__ [block:code] { "codes": [ { "code": "OneSignal.startInit(this)\n .inFocusDisplaying(OneSignal.OSInFocusDisplayOption.Notification)\n .init();", "language": "java" } ] } [/block] <br> <div id="autoPromptLocation"> #### autoPromptLocation Prompts the user for location permissions. This allows for geotagging so you can send notifications to users based on location. See [promptLocation](#promptLocation) for more details. __Parameters__ - **boolean** - `prompt` - Default is false, set to true to prompt users for location permissions when your app starts. __Example__ [block:code] { "codes": [ { "code": "OneSignal.startInit(this)\n .autoPromptLocation(true)\n .init();", "language": "java" } ] } [/block] <br> <div id="disableGmsMissingPrompt"> #### disableGmsMissingPrompt Prompts the user to update Google Play services if it is out of date or disabled on the device. It is required for users to have the same version or newer of the Google Play services app as you build your app with to register for push notifications. __Parameters__ - **boolean** - `prompt` - Default is `true`, set to `false` to never show the out of date prompt. __Example__ [block:code] { "codes": [ { "code": "OneSignal.startInit(this)\n .disableGmsMissingPrompt(true)\n .init();", "language": "java" } ] } [/block] <br> [block:api-header] { "type": "basic", "title": "Methods" } [/block] [block:html] { "html": "<a name=\"startInit\">" } [/block] #### startInit Initializes OneSignal to register the device for push notifications. Should be call in the onCreate of your Application class. __Parameters__ - **Context** - `context` - Your Application context. __Returns__ - **OneSignal.Builder** - See [Initialization Builder Methods](#initialization-builder-methods) for a list of methods available. __Example__ [block:code] { "codes": [ { "code": "public class YourAppClass extends Application {\n @Override\n public void onCreate() {\n super.onCreate();\n OneSignal.startInit(this).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 `idsAvailable` 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="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="syncHashedEmail"> #### syncHashedEmail Sends the user's email as an anonymized hash to prevent duplicated users. [block:code] { "codes": [ { "code": "OneSignal.syncHashedEmail(\"[email protected]\");", "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": "Classes" } [/block] <div id="OSNotificationOpenResult"> #### OSNotificationOpenResult - [OSNotification](#OSNotification) - `notification` - Notification the user opened. - [OSNotificationAction](#OSNotificationAction) - `action` - The action the user took on the notification. <div id="OSNotification"> #### OSNotification - **boolean** - `isAppInFocus` - Was app in focus. - **boolean** - `shown` - Was notification shown to the user. Will be false for silent notifications. - **int** - `androidNotificationId` - Android Notification assigned to the notification. Can be used to cancel or replace the notification. - [OSNotificationPayload](#OSNotificationPayload) - `payload` - Payload received from OneSignal. - **DisplayType**- `displayType` - How the notification was displayed to the user. Can be set to `Notification`, `InAppAlert`, or `None` if it was not displayed. - **List<[OSNotificationPayload](#OSNotificationPayload)>** - `groupedNotifications` - Notification is a summary notification for a group this will contain all notification payloads it was created from. <div id="OSNotificationAction"> #### OSNotificationAction - **ActionType** - `type` - Was the notification opened normally (`Opened`) or was a button pressed on the notification (`ActionTaken`). - **String** - `actionID` - If `type` == `ActionTaken` then this will contain the id of the button pressed. <br> <div id="OSNotificationPayload"> #### OSNotificationPayload - **String** - `notificationId` - OneSignal notification UUID. - **String** - `title` - Title of the notification. - **String** - `body` - Body of the notification. - **JSONObject** - `additionalData` - Custom additional data that was sent with the notification. Set on the dashboard under Options > Additional Data or with the 'data' field on the REST API. - **String** - `smallIcon` - Small icon resource name set on the notification. - **String** - `largeIcon` - Large icon set on the notification. - **String** - `bigPicture` - Big picture image set on the notification. - **String** - `smallIconAccentColor` - Accent color shown around small notification icon on Android 5+ devices. ARGB format. - **String** - `launchUrl` - URL to open when opening the notification. - **String** - `sound` - Sound resource to play when the notification is shown. - **String** - `ledColor` - Devices that have a notification LED will blink in this color. ARGB format. - **int** - `lockScreenVisibility ` - Privacy setting for how the notification should be shown on the lockscreen of Android 5+ devices. 1 = Public (fully visible)(default), 0 = Private (Contents are hidden), -1 = Secret (not shown). - **String** - `groupKey` - Notifications with this same key will be grouped together as a single summary notification. - **String** - `groupMessage` - Summary text displayed in the summary notification. - **List<[ActionButton](#ActionButton)>** - `actionButtons` - List of action buttons on the notification. - **String** - `fromProjectNumber` - The Google project number the notification was sent under. - **BackgroundImageLayout ** - `backgroundImageLayout` - If a background image was set this object will be available. - **String** - `rawPayload` - Raw JSON payload string received from OneSignal. <div id="ActionButton"> #### OSNotificationPayload.ActionButton - **String** - `id` - Id assigned to the button. - **String** - `text` - Text show on the button to the user. - **String** - `icon` - Icon shown on the button. <div id="BackgroundImageLayout "> #### OSNotificationPayload.BackgroundImageLayout - **String** - `image` - Image URL or name used as the background image. - **String** - `titleTextColor` - Text color of the title on the notification. ARGB Format. - **String** - `bodyTextColor` - Text color of the body on the notification. ARGB Format. <br><br> [block:api-header] { "type": "basic", "title": "Handler Interfaces" } [/block] <div id="NotificationOpenedHandler"> #### NotificationOpenedHandler Use to process a OneSignal notification the user just tapped on. __Parameters__ - [OSNotificationOpenResult](#OSNotificationOpenResult) - `result` - Object containing both the user's response and properties of the notification. __Example__ [block:code] { "codes": [ { "code": "class ExampleNotificationOpenedHandler implements OneSignal.NotificationOpenedHandler {\n // This fires when a notification is opened by tapping on it.\n @Override\n public void notificationOpened(OSNotificationOpenResult result) {\n OSNotificationAction.ActionType actionType = result.action.type;\n JSONObject data = result.notification.payload.additionalData;\n String customKey;\n\n if (data != null) {\n customKey = data.optString(\"customkey\", null);\n if (customKey != null)\n Log.i(\"OneSignalExample\", \"customkey set with value: \" + customKey);\n }\n\n if (actionType == OSNotificationAction.ActionType.ActionTaken)\n Log.i(\"OneSignalExample\", \"Button pressed with id: \" + result.action.actionID);\n\n // The following can be used to open an Activity of your choice.\n\n // Intent intent = new Intent(getApplicationContext(), YourActivity.class);\n // intent.setFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT | Intent.FLAG_ACTIVITY_NEW_TASK);\n // startActivity(intent);\n\n // Follow the instructions in the link below to prevent the launcher Activity from starting.\n // https://documentation.onesignal.com/docs/android-notification-customizations#changing-the-open-action-of-a-notification\n }\n}", "language": "java" } ] } [/block] [block:html] { "html": "<br>" } [/block] <div id="NotificationReceivedHandler"> #### NotificationReceivedHandler Fired when when a OneSignal notification is displayed to the user. Or when it is received if it is a background / silent notification. __Parameters__ - [OSNotification](#OSNotification) - `notification`- Object containing properties of the notification. __Example__ [block:code] { "codes": [ { "code": "class ExampleNotificationReceivedHandler implements OneSignal.NotificationReceivedHandler {\n @Override\n public void notificationReceived(OSNotification notification) {\n JSONObject data = notification.payload.additionalData;\n String customKey;\n\n if (data != null) {\n customKey = data.optString(\"customkey\", null);\n if (customKey != null)\n Log.i(\"OneSignalExample\", \"customkey set with value: \" + customKey);\n }\n }\n}", "language": "java" } ] } [/block] [block:callout] { "type": "warning", "body": "- If you will be displaying your own in app message when a notification is received make sure to call [inFocusDisplaying](#inFocusDisplaying) with `None` to disable OneSignal's in app AlertBox.\n- If want to change how a notification is displayed in the notification shade or process a silent notification when your app isn't running see our [Background Data and Notification Overriding ](android-notification-customizations#background-data-and-notification-overriding) guide.", "title": "Important behavior notes" } [/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

Website Push

Amazon

Windows Phone

Chrome Apps/Extensions

Mac OS X

Corona SDK

Unity SDK

Marmalade SDK

Adobe Air

PhoneGap

Cordova

Ionic

Intel XDK

Xamarin SDK

React Native

Cocos2d-x

Server REST API

Troubleshooting

Miscellaneous