OneSignal

Improve this doc

$ ionic plugin add onesignal-cordova-plugin

Repo: https://github.com/OneSignal/OneSignal-Cordova-SDK

The OneSignal plugin is an client implementation for using the OneSignal Service. OneSignal is a simple implementation for delivering push notifications.

Requires Cordova plugin: onesignal-cordova-plugin. For more info, please see the OneSignal Cordova Docs.

Supported platforms

Usage

import { OneSignal } from 'ionic-native';

OneSignal.startInit('b2f7f966-d8cc-11e4-bed1-df8f05be55ba', '703322744261');

OneSignal.inFocusDisplaying(OneSignal.OSInFocusDisplayOption.InAppAlert);

OneSignal.handleNotificationReceived().subscribe(() => {
 // do something when notification is received
});

OneSignal.handleNotificationOpened().subscribe(() => {
  // do something when a notification is opened
});

OneSignal.endInit();

Static Members

OSInFocusDisplayOption

constants to use in inFocusDisplaying()

startInit(appId, googleProjectNumber)

Start the initialization process. Once you are done configuring OneSignal, call the endInit function.

Param Type Details
appId string

Your OneSignal app id

googleProjectNumber string

ANDROID - your Google project number; only required for Android GCM/FCM pushes.

Returns: any

handleNotificationReceived()

Callback to run when a notification is received, whether it was displayed or not.

Returns: Observable<OneSignalReceivedNotification>

handleNotificationOpened()

Callback to run when a notification is tapped on from the notification shade (ANDROID) or notification center (iOS), or when closing an Alert notification shown in the app (if InAppAlert is enabled in inFocusDisplaying).

Returns: Observable<OneSignalOpenedNotification>

iOSSettings(settings)

iOS - Settings for iOS apps

Param Type Details
settings

kOSSettingsKeyAutoPrompt: boolean = true Auto prompt user for notification permissions.

kOSSettingsKeyInAppLaunchURL: boolean = false Launch notifications with a launch URL as an in app webview.

Returns: any

endInit()

Must be called after startInit to complete initialization of OneSignal.

Returns: any

getTags()

Retrieve a list of tags that have been set on the user from the OneSignal server.

Returns: Promise<any> Returns a Promise that resolves when tags are recieved.

getIds()

Lets you retrieve the OneSignal user id and device token. Your handler is called after the device is successfully registered with OneSignal.

Returns: Promise<Object> Returns a Promise that resolves if the device was successfully registered.

userId {string} OneSignal userId is a UUID formatted string. (unique per device per app)

pushToken {string} A push token is a Google/Apple assigned identifier(unique per device per app).

sendTag(Key, Value)

Tag a user based on an app event of your choosing so later you can create segments on 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.

Param Type Details
Key string

of your choosing to create or update.

Value string

to set on the key. NOTE: Passing in a blank String deletes the key, you can also call deleteTag.

sendTags(Pass)

Tag a user based on an app event of your choosing so later you can create segments on 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.

Param Type Details
Pass string

a json object with key/value pairs like: {key: "value", key2: "value2"}

deleteTag(Key)

Deletes a tag that was previously set on a user with sendTag or sendTags. Use deleteTags if you need to delete more than one.

Param Type Details
Key string

to remove.

deleteTags(Keys)

Deletes tags that were previously set on a user with sendTag or sendTags.

Param Type Details
Keys Array<string>

to remove.

registerForPushNotifications()

Call this when you would like to prompt an iOS user to accept push notifications with the default system prompt. Only works if you set kOSSettingsAutoPrompt to false in iOSSettings

enableVibrate(false)

Warning: 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.

Param Type Details
false boolean

to disable vibrate, true to re-enable it.

enableSound(false)

Warning: 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.

Param Type Details
false boolean

to disable sound, true to re-enable it.

inFocusDisplaying(displayOption)

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 inAppAlert, which can be helpful during development.

Param Type Details
displayOption DisplayType

Returns: any

setSubscription(enable)

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.

Param Type Details
enable boolean

postNotification(Parameters)

Param Type Details
Parameters notificationObj

see POST documentation

Returns: Promise<any> Returns a Promise that resolves if the notification was send successfully.

promptLocation()

Prompts the user for location permission to allow geotagging based on the “Location radius” filter on the OneSignal dashboard.

syncHashedEmail(email)

Param Type Details
email string

setLogLevel(contains)

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.

Param Type Details
contains loglevel

two properties: logLevel (for console logging) and visualLevel (for dialog messages)

OSNotification

Param Type Details
isAppInFocus boolean

Was app in focus.

shown boolean

Was notification shown to the user. Will be false for silent notifications.

androidNotificationId
(optional)
number

ANDROID - Android Notification assigned to the notification. Can be used to cancel or replace the notification.

payload OSNotificationPayload

Payload received from OneSignal.

displayType OSDisplayType

How the notification was displayed to the user. Can be set to Notification, InAppAlert, or None if it was not displayed.

groupedNotifications
(optional)
OSNotificationPayload[]

ANDROID - Notification is a summary notification for a group this will contain all notification payloads it was created from.

app_id
(optional)
string
contents any
headings
(optional)
any
isIos
(optional)
boolean
isAndroid
(optional)
boolean
isWP
(optional)
boolean
isWP_WNS
(optional)
boolean
isAdm
(optional)
boolean
isChrome
(optional)
boolean
isChromeWeb
(optional)
boolean
isSafari
(optional)
boolean
isAnyWeb
(optional)
boolean
included_segments
(optional)
string[]
excluded_segments
(optional)
string[]
include_player_ids
(optional)
string[]
include_ios_tokens
(optional)
string[]
include_android_reg_ids
(optional)
string[]
include_wp_uris
(optional)
string[]
include_wp_wns_uris
(optional)
string[]
include_amazon_reg_ids
(optional)
string[]
include_chrome_reg_ids
(optional)
string[]
include_chrome_web_reg_ids
(optional)
string[]
app_ids
(optional)
string[]
tags
(optional)
any[]
ios_badgeType
(optional)
string
ios_badgeCount
(optional)
number
ios_sound
(optional)
string
android_sound
(optional)
string
adm_sound
(optional)
string
wp_sound
(optional)
string
wp_wns_sound
(optional)
string
data
(optional)
any
buttons
(optional)
any
small_icon
(optional)
string
large_icon
(optional)
string
big_picture
(optional)
string
adm_small_icon
(optional)
string
adm_large_icon
(optional)
string
adm_big_picture
(optional)
string
chrome_icon
(optional)
string
chrome_big_picture
(optional)
string
chrome_web_icon
(optional)
string
firefox_icon
(optional)
string
url
(optional)
string
send_after
(optional)
string
delayed_option
(optional)
string
delivery_time_of_day
(optional)
string
android_led_color
(optional)
string
android_accent_color
(optional)
string
android_visibility
(optional)
number
content_available
(optional)
boolean
amazon_background_data
(optional)
boolean
template_id
(optional)
string
android_group
(optional)
string
android_group_message
(optional)
any
adm_group
(optional)
string
adm_group_message
(optional)
any
ttl
(optional)
number
priority
(optional)
number
ios_category
(optional)
string

OSLockScreenVisibility

Param Type Details
Public 1

Fully visible (default)

Private 0

Contents are hidden

Secret -1

Not shown

OSDisplayType

Param Type Details
None 0

notification is silent, or inFocusDisplaying is disabled.

InAppAlert 1

(DEFAULT) - native alert dialog display.

Notification 2

native notification display.

OSNotificationPayload

Param Type Details
notificationID string

OneSignal notification UUID.

title string

Title of the notification.

body string

Body of the notification.

additionalData
(optional)
any

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.

smallIcon
(optional)
string

ANDROID - Small icon resource name set on the notification.

largeIcon
(optional)
string

ANDROID - Large icon set on the notification.

bigPicture
(optional)
string

ANDROID - Big picture image set on the notification.

smallIconAccentColor
(optional)
string

ANDROID - Accent color shown around small notification icon on Android 5+ devices. ARGB format.

launchUrl
(optional)
string

URL to open when opening the notification.

sound string

Sound resource to play when the notification is shown.

ledColor
(optional)
string

ANDROID - Devices that have a notification LED will blink in this color. ARGB format.

lockScreenVisibility
(optional)
OSLockScreenVisibility
groupKey
(optional)
string

ANDROID - Notifications with this same key will be grouped together as a single summary notification.

groupMessage
(optional)
string

ANDROID - Summary text displayed in the summary notification.

actionButtons OSActionButton[]

List of action buttons on the notification.

fromProjectNumber
(optional)
string

ANDROID - The Google project number the notification was sent under.

backgroundImageLayout
(optional)
OSBackgroundImageLayout

ANDROID - If a background image was set this object will be available.

priority
(optional)
number
rawPayload string

List of action buttons on the notification.

OSActionButton

Param Type Details
id string

Id assigned to the button.

text string

Text show on the button to the user.

icon string

ANDROID - Icon shown on the button.

OSBackgroundImageLayout

Param Type Details
image string

Image URL or name used as the background image.

titleTextColor string

Text color of the title on the notification. ARGB Format.

bodyTextColor string

Text color of the body on the notification. ARGB Format.

OSNotificationOpenedResult

Param Type Details
action */ actionID?: string; }
notification OSNotification

OSActionType

Param Type Details
Opened 0
ActionTake 1

API

Native

General