npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@awesome-cordova-library/onesignal

v1.0.3

Published

OneSignal is a free email, sms, push notification, and in-app message service for mobile apps. This plugin makes it easy to integrate your Cordova based (e.g. Ionic, PhoneGap, and PhoneGap Build app with OneSignal.

Downloads

32

Readme


id: plugin-onesignal title: Onesignal tags:

  • cordova
  • capacitor
  • ionic
  • javascript
  • typescript
  • plugin
  • mobile
  • onesignal
  • notification
  • notification push

Onesignal

OneSignal is a free email, sms, push notification, and in-app message service for mobile apps. This plugin makes it easy to integrate your Cordova based (e.g. Ionic, PhoneGap, and PhoneGap Build app with OneSignal.

Online documentation

Onesignal documentation

Installation

Cordova

cordova plugin add onesignal-cordova-plugin
npm install @awesome-cordova-library/onesignal

Capacitor / Ionic

npm install onesignal-cordova-plugin
npm install @awesome-cordova-library/onesignal
npx cap sync

Vanilla

Declaration

class Onesignal {
  static setAppId(appId: string): void;
  /**
   * Set the callback to run just before displaying a notification while the app is in focus.
   * @param  {(event:NotificationReceivedEvent)=>void} handler
   * @returns void
   */
  static setNotificationWillShowInForegroundHandler(
    handler: (event: NotificationReceivedEvent) => void
  ): void;
  /**
   * Set the callback to run on notification open.
   * @param  {(openedEvent:OpenedEvent) => void} handler
   * @returns void
   */
  static setNotificationOpenedHandler(
    handler: (openedEvent: OpenedEvent) => void
  ): void;
  /**
   * Sets an In-App Message click event handler.
   * @param  {(action:InAppMessageAction)=>void} handler
   * @returns void
   */
  static setInAppMessageClickHandler(
    handler: (action: InAppMessageAction) => void
  ): void;
  /**
   * Sets the In-App Message lifecycle handler object to run on displaying and/or dismissing an In-App Message.
   * @param  {InAppMessageLifecycleHandlerObject} handlerObject
   * @returns void
   */
  static setInAppMessageLifecycleHandler(
    handlerObject: InAppMessageLifecycleHandlerObject
  ): void;
  /**
   * This method returns a "snapshot" of the device state for when it was called.
   * @param  {(response: DeviceState) => void} handler
   * @returns void
   */
  static getDeviceState(handler: (response: DeviceState) => void): void;
  /**
   * Allows you to set the app defined language with the OneSignal SDK.
   * @param  {string} language
   * @param  {(success:object)=>void} onSuccess
   * @param  {(failure:object)=>void} onFailure
   * @returns void
   */
  static setLanguage(
    language: string,
    onSuccess?: (success: object) => void,
    onFailure?: (failure: object) => void
  ): void;
  /**
   * Add a callback that fires when the OneSignal subscription state changes.
   * @param  {(event:ChangeEvent<SubscriptionChange>)=>void} observer
   * @returns void
   */
  static addSubscriptionObserver(
    observer: (event: ChangeEvent<SubscriptionChange>) => void
  ): void;
  /**
   * Add a callback that fires when the OneSignal email subscription changes.
   * @param  {(event:ChangeEvent<EmailSubscriptionChange>)=>void} observer
   * @returns void
   */
  static addEmailSubscriptionObserver(
    observer: (event: ChangeEvent<EmailSubscriptionChange>) => void
  ): void;
  /**
   * Add a callback that fires when the OneSignal sms subscription changes.
   * @param  {(event:ChangeEvent<SMSSubscriptionChange>)=>void} observer
   * @returns void
   */
  static addSMSSubscriptionObserver(
    observer: (event: ChangeEvent<SMSSubscriptionChange>) => void
  ): void;
  /**
   * Add a callback that fires when the native push permission changes.
   * @param  {(event:ChangeEvent<PermissionChange>)=>void} observer
   * @returns void
   */
  static addPermissionObserver(
    observer: (event: ChangeEvent<PermissionChange>) => void
  ): void;
  /**
   * Retrieve a list of tags that have been set on the user from the OneSignal server.
   * @param  {(tags:object)=>void} handler
   * @returns void
   */
  static getTags(handler: (tags: object) => void): void;
  /**
   * Tag a user based on an app event of your choosing so they can be targeted later via segments.
   * @param  {string} key
   * @param  {string} value
   * @returns void
   */
  static sendTag(key: string, value: string): void;
  /**
   * Deletes multiple tags that were previously set on a user.
   * @param  {string[]} keys
   * @returns void
   */
  static deleteTags(keys: string[]): void;
  /**
   * Only applies to iOS (does nothing on Android as it always silently registers)
   * Call only if you passed false to autoRegister
   * Request for Direct-To-History push notification authorization
   *
   * For more information: https://documentation.onesignal.com/docs/ios-customizations#provisional-push-notifications
   *
   * @param  {(response:{accepted:boolean})=>void} handler
   * @returns void
   */
  static registerForProvisionalAuthorization(
    handler?: (response: { accepted: boolean }) => void
  ): void;
  /**
   * Prompts the user for push notifications permission in iOS and Android 13+.
   * Use the fallbackToSettings parameter to prompt to open the settings app if a user has already declined push permissions.
   *
   * Call with promptForPushNotificationsWithUserResponse(fallbackToSettings?, handler?)
   *
   * @param  {boolean} fallbackToSettings
   * @param  {(response:boolean)=>void} handler
   * @returns void
   */
  static promptForPushNotificationsWithUserResponse(
    fallbackToSettingsOrHandler?: boolean | ((response: boolean) => void),
    handler?: (response: boolean) => void
  ): void;
  /**
   * Android Only. iOS provides a standard way to clear notifications by clearing badge count.
   * @returns void
   */
  static clearOneSignalNotifications(): void;
  /**
   * Android Only. If notifications are disabled for your application, unsubscribe the user from OneSignal.
   * @param  {boolean} unsubscribe
   * @returns void
   */
  static unsubscribeWhenNotificationsAreDisabled(unsubscribe: boolean): void;
  /**
   * Removes a single OneSignal notification based on its Android notification integer id.
   * @param  {number} id - notification id to cancel
   * @returns void
   */
  static removeNotification(id: number): void;
  /**
   * Removes all OneSignal notifications based on its Android notification group Id.
   * @param  {string} id - notification group id to cancel
   * @returns void
   */
  static removeGroupedNotifications(id: string): void;
  /**
   * Disable the push notification subscription to OneSignal.
   * @param  {boolean} disable
   * @returns void
   */
  static disablePush(disable: boolean): void;
  /**
   * Send a notification
   * @param  {object} notificationObject - JSON payload (see REST API reference)
   * @param  {(success:object)=>void} onSuccess
   * @param  {(failure:object)=>void} onFailure
   * @returns void
   */
  static postNotification(
    notificationObject: object,
    onSuccess?: (success: object) => void,
    onFailure?: (failure: object) => void
  ): void;
  /**
   * iOS only.
   * This method can be used to set if launch URLs should be opened within the application or in Safari.
   * @param  {boolean} isEnabled - false will open the link in Safari or user's default browser
   * @returns void
   */
  static setLaunchURLsInApp(isEnabled: boolean): void;
  /**
   * Enable logging to help debug if you run into an issue setting up OneSignal.
   * @param  {LogLevel} nsLogLevel - Sets the logging level to print to the Android LogCat log or Xcode log.
   * @param  {LogLevel} visualLogLevel - Sets the logging level to show as alert dialogs.
   * @returns void
   */
  static setLogLevel(nsLogLevel: LogLevel, visualLogLevel: LogLevel): void;
  /**
   * Did the user provide privacy consent for GDPR purposes.
   * @param  {(response: boolean) => void} handler
   * @returns void
   */
  static userProvidedPrivacyConsent(handler: (response: boolean) => void): void;
  /**
   * True if the application requires user privacy consent, false otherwise
   * Passes a boolean on Android and passes an object on iOS to the handler.
   *
   * @param  {(response: boolean | {value: boolean}) => void} handler
   * @returns void
   */
  static requiresUserPrivacyConsent(
    handler: (
      response:
        | boolean
        | {
            value: boolean;
          }
    ) => void
  ): void;
  /**
   * For GDPR users, your application should call this method before setting the App ID.
   * @param  {boolean} required
   * @returns void
   */
  static setRequiresUserPrivacyConsent(required: boolean): void;
  /**
   * If your application is set to require the user's privacy consent, you can provide this consent using this method.
   * @param  {boolean} granted
   * @returns void
   */
  static provideUserConsent(granted: boolean): void;
  /**
   * Allows you to set the user's email address with the OneSignal SDK.
   * @param  {string} email
   * @param  {string} authCode
   * @param  {Function} onSuccess
   * @param  {Function} onFailure
   * @returns void
   */
  static setEmail(
    email: string,
    authCode?: string,
    onSuccess?: Function,
    onFailure?: Function
  ): void;
  /**
   * If your app implements logout functionality, you can call logoutEmail to dissociate the email from the device.
   * @param  {Function} onSuccess
   * @param  {Function} onFailure
   * @returns void
   */
  static logoutEmail(onSuccess?: Function, onFailure?: Function): void;
  /**
   * Allows you to set the user's SMS number with the OneSignal SDK.
   * @param  {string} smsNumber
   * @param  {string} authCode
   * @param  {Function} onSuccess
   * @param  {Function} onFailure
   * @returns void
   */
  static setSMSNumber(
    smsNumber: string,
    authCode?: string,
    onSuccess?: Function,
    onFailure?: Function
  ): void;
  /**
   * If your app implements logout functionality, you can call logoutSMSNumber to dissociate the SMS number from the device.
   * @param  {Function} onSuccess
   * @param  {Function} onFailure
   * @returns void
   */
  static logoutSMSNumber(onSuccess?: Function, onFailure?: Function): void;
  /**
   * Allows you to use your own system's user ID's to send push notifications to your users.
   *
   * Possible function usages:
   * setExternalUserId(externalId: string?): void
   * setExternalUserId(externalId: string?, handler: function?): void
   * setExternalUserId(externalId: string?, externalIdAuthCode: string?, handler: function?): void
   *
   * @param  {string} externalId
   * @param  {string} externalIdAuthCode
   * @param  {(results:object) => void} handler
   * @returns void
   */
  static setExternalUserId(
    externalId: string | null,
    handlerOrAuth?: ((results: object) => void) | string,
    handler?: (results: object) => void
  ): void;
  /**
   * Removes whatever was set as the current user's external user ID.
   * @param  {(results:object)=>void} handler
   * @returns void
   */
  static removeExternalUserId(handler?: (results: object) => void): void;
  /**
   * Adds Multiple In-App Message Triggers.
   * @param  {[key: string]: string | number | boolean} triggers
   * @returns void
   */
  static addTriggers(triggers: {
    [key: string]: string | number | boolean;
  }): void;
  /**
   * Add an In-App Message Trigger.
   * @param  {string} key
   * @param  {string | number | boolean} value
   * @returns void
   */
  static addTrigger(key: string, value: string | number | boolean): void;
  /**
   * Removes a list of triggers based on a key.
   * @param  {string} key
   * @returns void
   */
  static removeTriggerForKey(key: string): void;
  /**
   * Removes a list of triggers based on a collection of keys.
   * @param  {string[]} keys
   * @returns void
   */
  static removeTriggersForKeys(keys: string[]): void;
  /**
   * Gets a trigger value for a provided trigger key.
   * @param  {string} key
   * @param  {(value: string) => void} handler
   * @returns void
   */
  static getTriggerValueForKey(
    key: string,
    handler: (value: string) => void
  ): void;
  /**
   * Pause & unpause In-App Messages
   * @param  {boolean} pause
   * @returns void
   */
  static pauseInAppMessages(pause: boolean): void;
  /**
   * Increases the "Count" of this Outcome by 1 and will be counted each time sent.
   * @param  {string} name
   * @param  {(event:OutcomeEvent)=>void} handler
   * @returns void
   */
  static sendOutcome(
    name: string,
    handler?: (event: OutcomeEvent) => void
  ): void;
  /**
   * Increases "Count" by 1 only once. This can only be attributed to a single notification.
   * @param  {string} name
   * @param  {(event:OutcomeEvent)=>void} handler
   * @returns void
   */
  static sendUniqueOutcome(
    name: string,
    handler?: (event: OutcomeEvent) => void
  ): void;
  /**
   * Increases the "Count" of this Outcome by 1 and the "Sum" by the value. Will be counted each time sent.
   * If the method is called outside of an attribution window, it will be unattributed until a new session occurs.
   * @param  {string} name
   * @param  {string|number} value
   * @param  {(event:OutcomeEvent)=>void} handler
   * @returns void
   */
  static sendOutcomeWithValue(
    name: string,
    value: string | number,
    handler?: (event: OutcomeEvent) => void
  ): void;
  /**
   * Prompts the user for location permissions to allow geotagging from the OneSignal dashboard.
   * @returns void
   */
  static promptLocation(): void;
  /**
   * Disable or enable location collection (defaults to enabled if your app has location permission).
   * @param  {boolean} shared
   * @returns void
   */
  static setLocationShared(shared: boolean): void;
  /**
   * True if the application has location share activated, false otherwise
   * Passes a boolean on Android and passes an object on iOS to the handler.
   *
   * @param  {(response: boolean | {value: boolean}) => void} handler
   * @returns void
   */
  static isLocationShared(
    handler: (
      response:
        | boolean
        | {
            value: boolean;
          }
    ) => void
  ): void;
}
export {
  LogLevel,
  InAppMessageAction,
  InAppMessageLifecycleHandlerObject,
  OpenedEvent,
  OutcomeEvent,
  NotificationReceivedEvent,
  ChangeEvent,
  DeviceState,
  EmailSubscriptionChange,
  PermissionChange,
  SMSSubscriptionChange,
  SubscriptionChange,
};

Usages

import Onesignal, { OpenedEvent } from "@awesome-cordova-library/onesignal";

Onesignal.setAppId("YOUR_ONESIGNAL_APP_ID");
Onesignal.setNotificationOpenedHandler((jsonData: OpenedEvent) => {
  console.log("notificationOpenedCallback: " + JSON.stringify(jsonData));
});

React

Declaration

const useOnesignal: (appId: string) => {
  setAppId: (appId: string) => void;
  setNotificationWillShowInForegroundHandler: (
    handler: (event: NotificationReceivedEvent) => void
  ) => void;
  setNotificationOpenedHandler: (
    handler: (openedEvent: OpenedEvent) => void
  ) => void;
  setInAppMessageClickHandler: (
    handler: (action: InAppMessageAction) => void
  ) => void;
  setInAppMessageLifecycleHandler: (
    handlerObject: InAppMessageLifecycleHandlerObject
  ) => void;
  getDeviceState: (handler: (response: DeviceState) => void) => void;
  setLanguage: (language: string) => Promise<unknown>;
  addSubscriptionObserver: (
    observer: (event: ChangeEvent<SubscriptionChange>) => void
  ) => void;
  addEmailSubscriptionObserver: (
    observer: (event: ChangeEvent<EmailSubscriptionChange>) => void
  ) => void;
  addSMSSubscriptionObserver: (
    observer: (event: ChangeEvent<SMSSubscriptionChange>) => void
  ) => void;
  addPermissionObserver: (
    observer: (event: ChangeEvent<PermissionChange>) => void
  ) => void;
  getTags: (handler: (tags: object) => void) => void;
  sendTag: (key: string, value: string) => void;
  deleteTags: (keys: string[]) => void;
  registerForProvisionalAuthorization: (
    handler?: ((response: { accepted: boolean }) => void) | undefined
  ) => void;
  promptForPushNotificationsWithUserResponse: (
    fallbackToSettingsOrHandler?:
      | boolean
      | ((response: boolean) => void)
      | undefined,
    handler?: ((response: boolean) => void) | undefined
  ) => void;
  clearOneSignalNotifications: () => void;
  unsubscribeWhenNotificationsAreDisabled: (unsubscribe: boolean) => void;
  removeNotification: (id: number) => void;
  removeGroupedNotifications: (id: string) => void;
  disablePush: (disable: boolean) => void;
  postNotification: (notificationObject: object) => Promise<unknown>;
  setLaunchURLsInApp: (isEnabled: boolean) => void;
  setLogLevel: (nsLogLevel: LogLevel, visualLogLevel: LogLevel) => void;
  userProvidedPrivacyConsent: (handler: (response: boolean) => void) => void;
  requiresUserPrivacyConsent: (
    handler: (
      response:
        | boolean
        | {
            value: boolean;
          }
    ) => void
  ) => void;
  setRequiresUserPrivacyConsent: (required: boolean) => void;
  provideUserConsent: (granted: boolean) => void;
  setEmail: (email: string, authCode?: string) => Promise<unknown>;
  logoutEmail: () => Promise<unknown>;
  setSMSNumber: (smsNumber: string, authCode?: string) => Promise<unknown>;
  logoutSMSNumber: () => Promise<unknown>;
  setExternalUserId: (
    externalId: string | null,
    handlerOrAuth?: string | ((results: object) => void) | undefined,
    handler?: ((results: object) => void) | undefined
  ) => void;
  removeExternalUserId: (handler: (results: object) => void) => void;
  addTriggers: (triggers: { [key: string]: string | number | boolean }) => void;
  addTrigger: (key: string, value: string | number | boolean) => void;
  removeTriggerForKey: (key: string) => void;
  removeTriggersForKeys: (keys: string[]) => void;
  getTriggerValueForKey: (
    key: string,
    handler: (value: string) => void
  ) => void;
  pauseInAppMessages: (pause: boolean) => void;
  sendOutcome: (
    name: string,
    handler?: ((event: OutcomeEvent) => void) | undefined
  ) => void;
  sendUniqueOutcome: (
    name: string,
    handler?: ((event: OutcomeEvent) => void) | undefined
  ) => void;
  sendOutcomeWithValue: (
    name: string,
    value: string | number,
    handler?: ((event: OutcomeEvent) => void) | undefined
  ) => void;
  promptLocation: () => void;
  setLocationShared: (shared: boolean) => void;
  isLocationShared: (
    handler: (
      response:
        | boolean
        | {
            value: boolean;
          }
    ) => void
  ) => void;
};

Usages

import { useState, useEffect } from "react";
import useOnesignal from "@awesome-cordova-library/onesignal/lib/react";
import { OpenedEvent } from "@awesome-cordova-library/onesignal";

function App() {
  const [notificationData, setNotificationData] = useState<
    OpenedEvent | undefined
  >();
  const { setNotificationOpenedHandler } = useOnesignal(
    "YOUR_ONESIGNAL_APP_ID"
  );
  useEffect(() => {
    setNotificationOpenedHandler((jsonData) => {
      setNotificationData(jsonData);
    });
  }, []);

  return <div />;
}