OneSignal

Improve this doc

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

Please view the official OneSignal Ionic SDK Installation guide for more information.

Icons

If you want to use generated icons with command ionic cordova resources:

1. Add a file to your hooks directory called copy_android_notification_icons.js

2. Configure the hook in your config.xml

   <platform name="android">
       <hook type="after_prepare" src="hooks/copy_android_notification_icons.js" />
   </platform>
   

3. Put the following code in it:

#!/usr/bin/env node

var fs = require('fs');
var path = require('path');

var filestocopy = [{
    "resources/android/icon/drawable-hdpi-icon.png":
        "platforms/android/app/src/main/res/drawable-hdpi/ic_stat_onesignal_default.png"
}, {
    "resources/android/icon/drawable-mdpi-icon.png":
        "platforms/android/app/src/main/res/drawable-mdpi/ic_stat_onesignal_default.png"
}, {
    "resources/android/icon/drawable-xhdpi-icon.png":
        "platforms/android/app/src/main/res/drawable-xhdpi/ic_stat_onesignal_default.png"
}, {
    "resources/android/icon/drawable-xxhdpi-icon.png":
        "platforms/android/app/src/main/res/drawable-xxhdpi/ic_stat_onesignal_default.png"
}, {
    "resources/android/icon/drawable-xxxhdpi-icon.png":
        "platforms/android/app/src/main/res/drawable-xxxhdpi/ic_stat_onesignal_default.png"
} ];

module.exports = function(context) {

    // no need to configure below
    var rootdir = context.opts.projectRoot;

    filestocopy.forEach(function(obj) {
        Object.keys(obj).forEach(function(key) {
            var val = obj[key];
            var srcfile = path.join(rootdir, key);
            var destfile = path.join(rootdir, val);
            console.log("copying "+srcfile+" to "+destfile);
            var destdir = path.dirname(destfile);
            if (fs.existsSync(srcfile) && fs.existsSync(destdir)) {
                fs.createReadStream(srcfile).pipe(
                    fs.createWriteStream(destfile));
            }
        });
    });

};

1. From the root of your project make the file executable: $ chmod +x hooks/copy_android_notification_icons.js

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

Installation

1. Install the Cordova and Ionic Native plugins:
   

   $ ionic cordova plugin add onesignal-cordova-plugin
   $ npm install --save @ionic-native/onesignal
   

2. Add this plugin to your app's module

Supported platforms

• Amazon Fire OS
• Android
• iOS
• Windows

Usage

import { OneSignal } from '@ionic-native/onesignal';

constructor(private oneSignal: OneSignal) { }

...

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

this.oneSignal.inFocusDisplaying(this.oneSignal.OSInFocusDisplayOption.InAppAlert);

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

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

this.oneSignal.endInit();

Instance Members

startInit(appId, googleProjectNumber)

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

handleNotificationReceived()

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

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).

iOSSettings(settings)

Platforms:iOS 

iOS - Settings for iOS apps

endInit()

Must be called after startInit to complete initialization of OneSignal.

promptForPushNotificationsWithUserResponse()

Platforms:iOS 

Prompt the user for notification permissions. Callback fires as soon as the user accepts or declines notifications.

getTags()

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

Quirk: You must wait for getTags to resolve before calling it again, as the plugin will only process the last method call and discard any previous ones.

getIds()

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

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.

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.

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.

deleteTags(Keys)

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

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.

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.

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.

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.

getPermissionSubscriptionState()

Get the current notification and permission state. Returns a OSPermissionSubscriptionState type described below.

postNotification(Parameters)

cancelNotification(notificationId)

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.

promptLocation()

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

syncHashedEmail(email)

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.

setLocationShared(shared)

Disable or enable location collection (Defaults to enabled) if your app has location permission.

addPermissionObserver()

The passed in function will be fired when a notification permission setting changes. This includes the following events:

• Notification permission prompt shown
• The user accepting or declining the permission prompt
• Enabling/disabling notifications for your app in the device Settings after returning to your app.

addSubscriptionObserver()

The passed in function will be fired when a notification subscription property changes. This includes the following events:

• Getting a push token from Apple / Google.
• Getting a player / user id from OneSignal
• OneSignal.setSubscription is called
• User disables or enables notifications

setEmail(email, emailAuthToken)

Allows you to set the user’s email address with the OneSignal SDK.

logoutEmail()

If your app implements logout functionality, you can call logoutEmail to dissociate the email from the device

addEmailSubscriptionObserver()

The passed in function will be fired when a notification subscription property changes. This includes the following events:

• Getting a push token from Apple / Google.
• Getting a player / user id from OneSignal
• OneSignal.setSubscription is called
• User disables or enables notifications

clearOneSignalNotifications()

Clears all OneSignal notifications

setRequiresUserPrivacyConsent(required)

Allows you to delay the initialization of the SDK until the user provides privacy consent. The SDK will not be fully initialized until the provideUserConsent(true) method is called.

provideUserConsent(granted)

If your application is set to require the user’s privacy consent, you can provide this consent using this method. Until you call provideUserConsent(true), the SDK will not fully initialize and will not send any data to OneSignal.

userProvidedPrivacyConsent(callback)

Accepts a callback, which returns a boolean variable indicating if the user has given privacy consent yet.

OSNotification

OSLockScreenVisibility

OSDisplayType

OSNotificationPayload

OSActionButton

OSBackgroundImageLayout

OSNotificationOpenedResult

OSActionType