{"__v":0,"_id":"5792d58090ad641700d46bdc","category":{"project":"542b6018044e1e2200413772","version":"551ef4ef4986f62b00a7202e","_id":"5792d30b23106419009c431b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-23T02:14:35.619Z","from_sync":false,"order":15,"slug":"intel-xdk","title":"Intel XDK"},"parentDoc":null,"project":"542b6018044e1e2200413772","user":"542b6010044e1e220041376f","version":{"__v":10,"_id":"551ef4ef4986f62b00a7202e","forked_from":"542b6018044e1e2200413775","project":"542b6018044e1e2200413772","createdAt":"2015-04-03T20:15:43.149Z","releaseDate":"2015-04-03T20:15:43.149Z","categories":["551ef4ef4986f62b00a7202f","551ef4ef4986f62b00a72030","551ef4ef4986f62b00a72031","551ef4ef4986f62b00a72032","551ef4ef4986f62b00a72033","551ef4ef4986f62b00a72034","551ef4ef4986f62b00a72035","551ef4ef4986f62b00a72036","551ef4ef4986f62b00a72037","551ef4ef4986f62b00a72038","551ef4ef4986f62b00a72039","551ef4ef4986f62b00a7203a","551ef4ef4986f62b00a7203b","551ef4ef4986f62b00a7203c","551ef4ef4986f62b00a7203d","551ef4ef4986f62b00a7203e","55d7f1879510f00d007ec727","56b94a5a9fc0de1700b60ae9","56bd0e48ac1c5c1900b2dbe4","56d74afc3eb4dd0b0020196a","5723ab8a1f41110e003081ed","576b4dd327d6252b00085422","5792ca4369c5120e00efe023","5792ca55366dd20e004736d7","5792d30b23106419009c431b"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"updates":[],"createdAt":"2016-07-23T02:25:04.422Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"never","params":[],"url":""},"isReference":false,"order":2,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"List of Functions\"\n}\n[/block]\n[init](#init)\n\n[registerForPushNotifications](#registerForPushNotifications)\n\n[sendTag](#sendTag)\n\n[sendTags](#sendTags)\n\n[getTags](#getTags)\n\n[deleteTag](#deleteTag)\n\n[deleteTags](#deleteTags)\n\n[getIds](#getIds)\n\n[enableVibrate](#enableVibrate)\n\n[enableSound](#enableSound)\n\n[enableNotificationsWhenActive](#enableNotificationsWhenActive)\n\n[enableInAppAlertNotification](#enableInAppAlertNotification)\n\n[setSubscription](#setSubscription)\n\n[postNotification](#postNotification)\n\n[promptLocation](#promptLocation)\n\n[setLogLevel](#setLogLevel)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"List of Callbacks\"\n}\n[/block]\n[notificationOpenedCallback](#notificationOpenedCallback)\n\n[tagsReceivedCallBack](#tagsReceivedCallBack)\n\n[idsReceivedCallBack](#idsReceivedCallBack)\n[block:html]\n{\n  \"html\": \"<br><br><br>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Functions\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<a name=\\\"init\\\">\"\n}\n[/block]\n#### init\nOnly required method you need to call to setup OneSignal to receive push notifications. Call this from the `deviceready` event.\n\n- ##### Parameters\n - __`string` _appId___ - Your OneSignal app id from onesignal.com\n - __`JSON` _options___ - {googleProjectNumber: \"############\"} is required for Android. {autoRegister: false} is optional for iOS.(If this is used then you must call registerForPushNotifications at anther point in your app)\n - __`function` _didReceiveRemoteNotificationCallBack(Optional)___ - Function that gets called when a notification is opened or one is received when your app is in use. Function will receive one parameter with JSON about the incoming notification.\n\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.init(\\\"5eb5a37e-b458-11e3-ac11-000c2940e62c\\\",\\n                               {googleProjectNumber: \\\"703322744261\\\",\\n                                autoRegister: true},\\n                                app.didReceiveRemoteNotificationCallBack);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"registerForPushNotifications\\\">\"\n}\n[/block]\n#### registerForPushNotifications\nCall this when you would like to prompt an iOS user to accept push notifications with the default system prompt. Only use if you passed false to autoRegister when calling init.\n\n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.registerForPushNotifications();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"sendTag\\\">\"\n}\n[/block]\n#### sendTag\nTag 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.\n\n- ##### Parameters\n - __`string` _key___ - Key of your choosing to create or update.\n - __`string` _value___ - Value to set on the key.\n     - _NOTE:_ Passing in a blank String deletes the key, you can also call deleteTag.\n\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.sendTag(\\\"key\\\", \\\"value\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"sendTags\\\">\"\n}\n[/block]\n#### sendTags\nTag 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.\n\n- __Parameters__\n - __`JSON` _keyValues___ - Key value pairs of your choosing to create or update.\n   - _NOTE:_ Passing in a blank String as a value deletes the key, you can also call deleteTag or deleteTags.\n\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.sendTags({key: \\\"value\\\", key2: \\\"value2\\\"});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"getTags\\\">\"\n}\n[/block]\n#### getTags\nRetrieve a list of tags that have been set on the user from the OneSignal server.\n\n- __Parameters__\n - __`function` _tagsReceivedCallBack___ - Passed in function which will receive one parameter containing JSON.\n   \n\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.getTags(function(tags) {\\n  console.log('Tags Received: ' + JSON.stringify(tags));\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"deleteTag\\\">\"\n}\n[/block]\n#### deleteTag\nDeletes a tag that was previously set on a user with `sendTag` or `sendTags`. Use `deleteTags` if you need to delete more than one.\n\n- __Parameters__\n - __`String` _key___ - Key to remove.\n   \n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.deleteTag(\\\"key\\\");\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"deleteTags\\\">\"\n}\n[/block]\n#### deleteTags\nDeletes tags that were previously set on a user with `sendTag` or `sendTags`.\n\n- __Parameters__\n - __`Array` _keys___ - Keys to remove.\n   \n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.deleteTags([\\\"key1\\\", \\\"key2\\\"]);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"getIds\\\">\"\n}\n[/block]\n#### getIds\nLets you retrieve the OneSignal user id and device token. Your handler is called after the device is successfully registered with OneSignal.\n\n- __Parameters__\n - __`function`  _idsReceivedCallBack___ -  Passed in function which will receive one parameter containing JSON with userId and pushToken.\n\n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.getIds(function(ids) {\\n  console.log('getIds: ' + JSON.stringify(ids));\\n  alert(\\\"userId = \\\" + ids.userId + \\\", pushToken = \\\" + ids.pushToken);\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"enableVibrate\\\">\"\n}\n[/block]\n### enableVibrate\n*Only applies to Android and Amazon. You can call this from your UI from a button press for example to give your user's options for your notifications.*\n\nBy 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.\n- __Parameters__\n - __`boolean`  _enable___ -  false to disable vibrate, true to re-enable it.\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.enableVibrate(false);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"enableSound\\\">\"\n}\n[/block]\n### enableSound\n*Only applies to Android and Amazon. You can call this from your UI from a button press for example to give your user's options for your notifications.*\n\nBy 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.\n- __Parameters__\n - __`boolean`  _enable___ -  false to disable sound, true to re-enable it.\n\n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.enableSound(false);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<br><div id=\"enableNotificationsWhenActive\">\n#### enableNotificationsWhenActive\n*Only applies to Android and Amazon devices.*\n\nBy default this is false and notifications will not be shown when the user is in your app, instead the notificationOpenedCallback is fired. If set to true notifications will always show in the notification area and notificationOpenedCallback will not fire until the user taps on the notification.\n\n__Parameters__\n   - __`boolean` _enable___\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.enableNotificationsWhenActive(true);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<br><div id=\"enableInAppAlertNotification\">\n#### enableInAppAlertNotification\n\nBy default this is false and notifications will not be shown when the user is in your app, instead the notificationOpenedCallback 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 notificationOpenedCallback is then fired after the alert box is closed.\n\n__Parameters__\n   - __`boolean` _enable___\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.enableInAppAlertNotification(true);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<br><div id=\"setSubscription\">\n#### setSubscription\n\nYou 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.\n\n__Parameters__\n   - __`boolean` _enable___\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.setSubscription(false);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<br><div id=\"postNotification\">\n#### postNotification\n\nAllows you to send notifications from user to user or schedule ones in the future to be delivered to the current device.\n\n__Parameters__\n   - __`Object` _parameters___ - Object of notification options, see our [create notification POST](http://documentation.onesignal.com/v2.0/docs/notifications-create-notification) call for all options.\n   - __`function` _onSuccess___ - (Optional) callback fires when the notification was created on OneSignal's server.\n      - __`JSON` _returnedJson___ - Json response from OneSignal's server.\n   - __`function` _onFailure___  (Optional) callback fires when the notification failed to create\n       - __`JSON` _returnedJson___ - Json response from OneSignal's server.\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.getIds(function(ids) {\\n  var notificationObj = { contents: {en: \\\"message body\\\"},\\n                          include_player_ids: [ids.userId]};\\n  window.plugins.OneSignal.postNotification(notificationObj,\\n    function(successResponse) {\\n      console.log(\\\"Notification Post Success:\\\", successResponse);\\n    },\\n    function (failedResponse) {\\n      console.log(\\\"Notification Post Failed: \\\", failedResponse);\\n      alert(\\\"Notification Post Failed:\\\\n\\\" + JSON.stringify(failedResponse));\\n    }\\n  );\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<br><div id=\"promptLocation\">\n#### promptLocation\n\nPrompts the user for location permission to allow geotagging based on the \"Location radius\" filter on the OneSignal dashboard.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.promptLocation();\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nRequired iOS plist settings.\n`NSLocationUsageDescription` and `NSLocationWhenInUseUsageDescription `\n\nRequired Android Permission.\n```\n<uses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\"/>\nOR\n<uses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\"/>\n```\n\n\n<br><div id=\"setLogLevel\">\n#### setLogLevel\nEnable logging to help debug if you run into an issue setting up OneSignal. The logging levels are as follows: 0 = None, 1= Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose\n\nThe higher the value the more information is shown.\n\n__Parameters__\n   - __`Integer` _logLevel___ - Sets the logging level to print the iOS Xcode log or the Android LogCat log.\n   - __`Integer` _visualLevel___ - Sets the logging level to show as alert dialogs.\n \n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Will show popup dialogs when the devices registers with Apple/Google and with OneSignal.\\n// Errors will be shown as popups too if there are any issues.\\nwindow.plugins.OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><br><br>\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Callbacks\"\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<a name=\\\"notificationOpenedCallback\\\">\"\n}\n[/block]\n#### notificationOpenedCallback\nFunction that gets called when a notification is opened or one is received when your app is in use. Function will receive one parameter with JSON about the incoming notification.\n\n __JSON__\n- __`String` _message___ - The message text the user seen in the notification.\n- __`JSONObject` _additionalData___ - Key value pairs that were set on the notification.\n   - __`String` _title___ - Title displayed in the notification.\n   - __`ArrrayOfObjects` _actionButtons___ - Any buttons that were present on the notification.\n      - __`String` _text___ - Text displayed on the button.\n      - __`String` _id___ - Id set on the button.\n   - __`String` _actionSelected___ - Id of the button on the notification that was clicked. \"\\_\\_DEFAULT\\_\\_\" will be set if buttons were set on the notification but the user tap on the notification itself.\n   - __`String` _sound___ - Sound set on the notification.\n   - __`String` _launchURL___ - launchURL set on the notification.\n   - __`ArrrayOfObjects` stacked\\_notifications__ - Contains an object for each notification that exists in the stack. `message` as well as keys listed above and ones you set with additional data.\n- __`boolean` _isActive___ - True if your app was currently being used when a notification came in.\n\n__Examples__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" var notificationOpenedCallback = function(jsonData) {\\n\\talert(\\\"Notification received:\\\\n\\\" + JSON.stringify(jsonData));\\n  console.log('didReceiveRemoteNotificationCallBack: ' + JSON.stringify(jsonData));\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"Basic\"\n    },\n    {\n      \"code\": \"// This example will show an alert box if the user presses the button with the id \\\"id1\\\" on the notification.\\n var notificationOpenedCallback = function(jsonData) {\\n\\tif (jsonData.additionalData) {\\n  \\tif (jsonData.additionalData.actionSelected == \\\"id1\\\")\\n      alert(\\\"Button id1 pressed!\\\");\\n  }\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"Handle Action Buttons\"\n    },\n    {\n      \"code\": \"// Set 'Additional Data' ('data' field on the REST API) when you send your notification with targetUrl equal to the url you want to navigate to.\\nvar notificationOpenedCallback = function(jsonData) {\\n\\tif (jsonData.additionalData && jsonData.additionalData.targetUrl)\\n      location.href = jsonData.additionalData.targetUrl;\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"Open page in app\"\n    },\n    {\n      \"code\": \"// Any additional data you set on the notification will be stored in stacked_notifications with your key\\n var notificationOpenedCallback = function(jsonData) {\\n  if (   jsonData.additionalData\\n      && jsonData.additionalData.stacked_notifications) {\\n    var notifications = jsonData.additionalData.stacked_notifications;\\n    for (var i = 0; i < notifications.length; i++) {\\n      alert(notifications[i].message);\\n      console.log(notifications[i]);\\n    }\\n  }\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"Stacked Notifications\"\n    },\n    {\n      \"code\": \"// Set 'Additional Data' ('data' field on the REST API) when you send your notification with targetUrl equal to the url you want to navigate to.\\nvar notificationOpenedCallback = function(jsonData) {\\n\\tif (jsonData.additionalData && jsonData.additionalData.targetUrl) {\\n      var state = $injector.get($state);\\n\\t\\t\\tstate.go(jsonData.additionalData.targetUrl);\\n  }\\n}\",\n      \"language\": \"javascript\",\n      \"name\": \"Open page in app (Ionic)\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"tagsReceivedCallBack\\\">\"\n}\n[/block]\n#### tagsReceivedCallBack\nGets all the tags set on a user from onesignal.com.\n\n   - __Parameters__\n     - __`JSON` _tags___ - JSON object of key value pairs retrieved from the OneSignal server.\n\n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.getTags(function(tags) {\\n  console.log('Tags Received: ' + JSON.stringify(tags));\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:html]\n{\n  \"html\": \"<br><a name=\\\"idsReceivedCallBack\\\">\"\n}\n[/block]\n#### idsReceivedCallBack\nGet the OneSignal userId and the device's push token.\n\n   - __JSON__\n     - __`String` _userId___ - OneSignal userId is a UUID formatted string.(_unique per device per app_)\n     - __`String` _pushToken___ - a push token is a Google/Apple assigned identifier(_unique per device per app_).\n     - _NOTE:_ Might be blank if push notifications are not accepted on iOS, Google Play services are not installed, or from a connection issue.\n\n__Example__\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"window.plugins.OneSignal.getIds(function(ids) {\\n\\tdocument.getElementById(\\\"OneSignalUserID\\\").innerHTML = \\\"UserID: \\\" + ids.userId;\\n  document.getElementById(\\\"OneSignalPushToken\\\").innerHTML = \\\"PushToken: \\\" + ids.pushToken;\\n  console.log('getIds: ' + JSON.stringify(ids));\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","excerpt":"OneSignal SDK API for Intel XDK","slug":"intel-xdk-api-reference","type":"basic","title":"API Reference"}

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

API Reference

OneSignal SDK API for Intel XDK
[block:api-header] { "type": "basic", "title": "List of Functions" } [/block] [init](#init) [registerForPushNotifications](#registerForPushNotifications) [sendTag](#sendTag) [sendTags](#sendTags) [getTags](#getTags) [deleteTag](#deleteTag) [deleteTags](#deleteTags) [getIds](#getIds) [enableVibrate](#enableVibrate) [enableSound](#enableSound) [enableNotificationsWhenActive](#enableNotificationsWhenActive) [enableInAppAlertNotification](#enableInAppAlertNotification) [setSubscription](#setSubscription) [postNotification](#postNotification) [promptLocation](#promptLocation) [setLogLevel](#setLogLevel) [block:api-header] { "type": "basic", "title": "List of Callbacks" } [/block] [notificationOpenedCallback](#notificationOpenedCallback) [tagsReceivedCallBack](#tagsReceivedCallBack) [idsReceivedCallBack](#idsReceivedCallBack) [block:html] { "html": "<br><br><br>" } [/block] [block:api-header] { "type": "basic", "title": "Functions" } [/block] [block:html] { "html": "<a name=\"init\">" } [/block] #### init Only required method you need to call to setup OneSignal to receive push notifications. Call this from the `deviceready` event. - ##### Parameters - __`string` _appId___ - Your OneSignal app id from onesignal.com - __`JSON` _options___ - {googleProjectNumber: "############"} is required for Android. {autoRegister: false} is optional for iOS.(If this is used then you must call registerForPushNotifications at anther point in your app) - __`function` _didReceiveRemoteNotificationCallBack(Optional)___ - Function that gets called when a notification is opened or one is received when your app is in use. Function will receive one parameter with JSON about the incoming notification. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.init(\"5eb5a37e-b458-11e3-ac11-000c2940e62c\",\n {googleProjectNumber: \"703322744261\",\n autoRegister: true},\n app.didReceiveRemoteNotificationCallBack);", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"registerForPushNotifications\">" } [/block] #### registerForPushNotifications Call this when you would like to prompt an iOS user to accept push notifications with the default system prompt. Only use if you passed false to autoRegister when calling init. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.registerForPushNotifications();", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><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. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.sendTag(\"key\", \"value\");", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><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__ - __`JSON` _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": "window.plugins.OneSignal.sendTags({key: \"value\", key2: \"value2\"});", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"getTags\">" } [/block] #### getTags Retrieve a list of tags that have been set on the user from the OneSignal server. - __Parameters__ - __`function` _tagsReceivedCallBack___ - Passed in function which will receive one parameter containing JSON. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.getTags(function(tags) {\n console.log('Tags Received: ' + JSON.stringify(tags));\n});", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><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": "window.plugins.OneSignal.deleteTag(\"key\");", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"deleteTags\">" } [/block] #### deleteTags Deletes tags that were previously set on a user with `sendTag` or `sendTags`. - __Parameters__ - __`Array` _keys___ - Keys to remove. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.deleteTags([\"key1\", \"key2\"]);", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"getIds\">" } [/block] #### getIds Lets you retrieve the OneSignal user id and device token. Your handler is called after the device is successfully registered with OneSignal. - __Parameters__ - __`function` _idsReceivedCallBack___ - Passed in function which will receive one parameter containing JSON with userId and pushToken. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.getIds(function(ids) {\n console.log('getIds: ' + JSON.stringify(ids));\n alert(\"userId = \" + ids.userId + \", pushToken = \" + ids.pushToken);\n});", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"enableVibrate\">" } [/block] ### enableVibrate *Only applies to Android and Amazon. 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. - __Parameters__ - __`boolean` _enable___ - false to disable vibrate, true to re-enable it. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.enableVibrate(false);", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"enableSound\">" } [/block] ### enableSound *Only applies to Android and Amazon. 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. - __Parameters__ - __`boolean` _enable___ - false to disable sound, true to re-enable it. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.enableSound(false);", "language": "javascript" } ] } [/block] <br><div id="enableNotificationsWhenActive"> #### enableNotificationsWhenActive *Only applies to Android and Amazon devices.* By default this is false and notifications will not be shown when the user is in your app, instead the notificationOpenedCallback is fired. If set to true notifications will always show in the notification area and notificationOpenedCallback will not fire until the user taps on the notification. __Parameters__ - __`boolean` _enable___ __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.enableNotificationsWhenActive(true);", "language": "javascript" } ] } [/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 notificationOpenedCallback 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 notificationOpenedCallback is then fired after the alert box is closed. __Parameters__ - __`boolean` _enable___ __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.enableInAppAlertNotification(true);", "language": "javascript" } ] } [/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": "window.plugins.OneSignal.setSubscription(false);", "language": "javascript" } ] } [/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__ - __`Object` _parameters___ - Object of notification options, see our [create notification POST](http://documentation.onesignal.com/v2.0/docs/notifications-create-notification) call for all options. - __`function` _onSuccess___ - (Optional) callback fires when the notification was created on OneSignal's server. - __`JSON` _returnedJson___ - Json response from OneSignal's server. - __`function` _onFailure___ (Optional) callback fires when the notification failed to create - __`JSON` _returnedJson___ - Json response from OneSignal's server. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.getIds(function(ids) {\n var notificationObj = { contents: {en: \"message body\"},\n include_player_ids: [ids.userId]};\n window.plugins.OneSignal.postNotification(notificationObj,\n function(successResponse) {\n console.log(\"Notification Post Success:\", successResponse);\n },\n function (failedResponse) {\n console.log(\"Notification Post Failed: \", failedResponse);\n alert(\"Notification Post Failed:\\n\" + JSON.stringify(failedResponse));\n }\n );\n});", "language": "javascript" } ] } [/block] <br><div id="promptLocation"> #### promptLocation Prompts the user for location permission to allow geotagging based on the "Location radius" filter on the OneSignal dashboard. [block:code] { "codes": [ { "code": "window.plugins.OneSignal.promptLocation();", "language": "javascript" } ] } [/block] Required iOS plist settings. `NSLocationUsageDescription` and `NSLocationWhenInUseUsageDescription ` Required Android Permission. ``` <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/> OR <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/> ``` <br><div id="setLogLevel"> #### setLogLevel Enable logging to help debug if you run into an issue setting up OneSignal. The logging levels are as follows: 0 = None, 1= Fatal, 2 = Errors, 3 = Warnings, 4 = Info, 5 = Debug, 6 = Verbose The higher the value the more information is shown. __Parameters__ - __`Integer` _logLevel___ - Sets the logging level to print the iOS Xcode log or the Android LogCat log. - __`Integer` _visualLevel___ - Sets the logging level to show as alert dialogs. __Example__ [block:code] { "codes": [ { "code": "// Will show popup dialogs when the devices registers with Apple/Google and with OneSignal.\n// Errors will be shown as popups too if there are any issues.\nwindow.plugins.OneSignal.setLogLevel({logLevel: 4, visualLevel: 4});", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><br><br>" } [/block] [block:api-header] { "type": "basic", "title": "Callbacks" } [/block] [block:html] { "html": "<a name=\"notificationOpenedCallback\">" } [/block] #### notificationOpenedCallback Function that gets called when a notification is opened or one is received when your app is in use. Function will receive one parameter with JSON about the incoming notification. __JSON__ - __`String` _message___ - The message text the user seen in the notification. - __`JSONObject` _additionalData___ - Key value pairs that were set on the notification. - __`String` _title___ - Title displayed in the notification. - __`ArrrayOfObjects` _actionButtons___ - Any buttons that were present on the notification. - __`String` _text___ - Text displayed on the button. - __`String` _id___ - Id set on the button. - __`String` _actionSelected___ - Id of the button on the notification that was clicked. "\_\_DEFAULT\_\_" will be set if buttons were set on the notification but the user tap on the notification itself. - __`String` _sound___ - Sound set on the notification. - __`String` _launchURL___ - launchURL set on the notification. - __`ArrrayOfObjects` stacked\_notifications__ - Contains an object for each notification that exists in the stack. `message` as well as keys listed above and ones you set with additional data. - __`boolean` _isActive___ - True if your app was currently being used when a notification came in. __Examples__ [block:code] { "codes": [ { "code": " var notificationOpenedCallback = function(jsonData) {\n\talert(\"Notification received:\\n\" + JSON.stringify(jsonData));\n console.log('didReceiveRemoteNotificationCallBack: ' + JSON.stringify(jsonData));\n}", "language": "javascript", "name": "Basic" }, { "code": "// This example will show an alert box if the user presses the button with the id \"id1\" on the notification.\n var notificationOpenedCallback = function(jsonData) {\n\tif (jsonData.additionalData) {\n \tif (jsonData.additionalData.actionSelected == \"id1\")\n alert(\"Button id1 pressed!\");\n }\n}", "language": "javascript", "name": "Handle Action Buttons" }, { "code": "// Set 'Additional Data' ('data' field on the REST API) when you send your notification with targetUrl equal to the url you want to navigate to.\nvar notificationOpenedCallback = function(jsonData) {\n\tif (jsonData.additionalData && jsonData.additionalData.targetUrl)\n location.href = jsonData.additionalData.targetUrl;\n}", "language": "javascript", "name": "Open page in app" }, { "code": "// Any additional data you set on the notification will be stored in stacked_notifications with your key\n var notificationOpenedCallback = function(jsonData) {\n if ( jsonData.additionalData\n && jsonData.additionalData.stacked_notifications) {\n var notifications = jsonData.additionalData.stacked_notifications;\n for (var i = 0; i < notifications.length; i++) {\n alert(notifications[i].message);\n console.log(notifications[i]);\n }\n }\n}", "language": "javascript", "name": "Stacked Notifications" }, { "code": "// Set 'Additional Data' ('data' field on the REST API) when you send your notification with targetUrl equal to the url you want to navigate to.\nvar notificationOpenedCallback = function(jsonData) {\n\tif (jsonData.additionalData && jsonData.additionalData.targetUrl) {\n var state = $injector.get($state);\n\t\t\tstate.go(jsonData.additionalData.targetUrl);\n }\n}", "language": "javascript", "name": "Open page in app (Ionic)" } ] } [/block] [block:html] { "html": "<br><a name=\"tagsReceivedCallBack\">" } [/block] #### tagsReceivedCallBack Gets all the tags set on a user from onesignal.com. - __Parameters__ - __`JSON` _tags___ - JSON object of key value pairs retrieved from the OneSignal server. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.getTags(function(tags) {\n console.log('Tags Received: ' + JSON.stringify(tags));\n});", "language": "javascript" } ] } [/block] [block:html] { "html": "<br><a name=\"idsReceivedCallBack\">" } [/block] #### idsReceivedCallBack Get the OneSignal userId and the device's push token. - __JSON__ - __`String` _userId___ - OneSignal userId is a UUID formatted string.(_unique per device per app_) - __`String` _pushToken___ - a push token is a Google/Apple assigned identifier(_unique per device per app_). - _NOTE:_ Might be blank if push notifications are not accepted on iOS, Google Play services are not installed, or from a connection issue. __Example__ [block:code] { "codes": [ { "code": "window.plugins.OneSignal.getIds(function(ids) {\n\tdocument.getElementById(\"OneSignalUserID\").innerHTML = \"UserID: \" + ids.userId;\n document.getElementById(\"OneSignalPushToken\").innerHTML = \"PushToken: \" + ids.pushToken;\n console.log('getIds: ' + JSON.stringify(ids));\n});", "language": "javascript" } ] } [/block]