tessl/npm-react-native-onesignal

React Native SDK for OneSignal's push notification, email, SMS, and in-app messaging service

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

React Native OneSignal

Name: tessl/npm-react-native-onesignal
Author: tessl

React Native OneSignal is a comprehensive SDK for OneSignal's push notification, email, SMS, and in-app messaging service. It provides a modern TypeScript API for React Native applications to integrate push notifications, user management, and messaging across iOS and Android platforms.

Package Information

Package Name: react-native-onesignal
Package Type: npm
Language: TypeScript
Installation: npm install react-native-onesignal

Core Imports

import { OneSignal, LogLevel } from "react-native-onesignal";

For CommonJS:

const { OneSignal, LogLevel } = require("react-native-onesignal");

Basic Usage

import { OneSignal, LogLevel } from "react-native-onesignal";

// Initialize OneSignal with your app ID
OneSignal.initialize("your-app-id");

// Set up notification listeners
OneSignal.Notifications.addEventListener('click', (event) => {
  console.log('Notification clicked:', event);
});

// Request notification permission
const hasPermission = await OneSignal.Notifications.requestPermission(true);

// Set user identification for cross-device tracking
OneSignal.login("user-external-id");

// Add user tags for segmentation
OneSignal.User.addTag("subscription", "premium");

Architecture

React Native OneSignal is built around several key components:

Core SDK: Central initialization and configuration (OneSignal namespace)
User Management: User identification, aliases, tags, and contact info (OneSignal.User)
Push Notifications: Permission handling, subscription management, and event handling (OneSignal.Notifications, OneSignal.User.pushSubscription)
In-App Messages: Trigger-based messaging with lifecycle events (OneSignal.InAppMessages)
Live Activities: iOS-specific live activity support (OneSignal.LiveActivities)
Location Services: Location-based targeting (OneSignal.Location)
Analytics: Outcome tracking and attribution (OneSignal.Session)
Debug Tools: Logging and debugging utilities (OneSignal.Debug)

Capabilities

Core SDK Functions

Essential SDK initialization and configuration functions for app startup and user lifecycle management.

function initialize(appId: string): void;
function login(externalId: string): void;
function logout(): void;
function setConsentRequired(required: boolean): void;
function setConsentGiven(granted: boolean): void;

Core SDK

User Management

Comprehensive user identification and data management including aliases, tags, email, SMS subscriptions, and state tracking.

namespace User {
  function addEventListener(event: 'change', listener: (event: UserChangedState) => void): void;
  function getOnesignalId(): Promise<string | null>;
  function getExternalId(): Promise<string | null>;
  function addTag(key: string, value: string): void;
  function addTags(tags: object): void;
  function addEmail(email: string): void;
  function addSms(smsNumber: string): void;
}

User Management

Push Subscription Management

Push notification subscription handling including permission status, subscription state, and opt-in/opt-out controls.

namespace User.pushSubscription {
  function addEventListener(event: 'change', listener: (event: PushSubscriptionChangedState) => void): void;
  function getIdAsync(): Promise<string | null>;
  function getTokenAsync(): Promise<string | null>;
  function getOptedInAsync(): Promise<boolean>;
  function optIn(): void;
  function optOut(): void;
}

Push Subscription Management

Notification Handling

Notification permission management, event handling, and notification control including click events and display lifecycle.

namespace Notifications {
  function getPermissionAsync(): Promise<boolean>;
  function requestPermission(fallbackToSettings: boolean): Promise<boolean>;
  function addEventListener<K extends NotificationEventName>(
    event: K,
    listener: (event: NotificationEventTypeMap[K]) => void
  ): void;
  function clearAll(): void;
}

Notification Handling

In-App Messages

Trigger-based in-app messaging system with lifecycle event handling and display control.

namespace InAppMessages {
  function addEventListener<K extends InAppMessageEventName>(
    event: K,
    listener: (event: InAppMessageEventTypeMap[K]) => void
  ): void;
  function addTrigger(key: string, value: string): void;
  function addTriggers(triggers: { [key: string]: string }): void;
  function setPaused(pause: boolean): void;
}

In-App Messages

Live Activities (iOS)

iOS-specific Live Activity support for dynamic, real-time widget updates including push-to-start and push-to-update functionality.

namespace LiveActivities {
  function enter(activityId: string, token: string, handler?: Function): void;
  function exit(activityId: string, handler?: Function): void;
  function setupDefault(options?: LiveActivitySetupOptions): void;
  function startDefault(activityId: string, attributes: object, content: object): void;
}

Live Activities

Location Services

Location permission and sharing management for geo-targeted messaging capabilities.

namespace Location {
  function requestPermission(): void;
  function setShared(shared: boolean): void;
  function isShared(): Promise<boolean>;
}

Location Services

Session Analytics

Outcome tracking and attribution for measuring notification effectiveness and user engagement.

namespace Session {
  function addOutcome(name: string): void;
  function addUniqueOutcome(name: string): void;
  function addOutcomeWithValue(name: string, value: string | number): void;
}

Session Analytics

Types

enum LogLevel {
  None,
  Fatal,
  Error,
  Warn,
  Info,
  Debug,
  Verbose
}

enum OSNotificationPermission {
  NotDetermined = 0,
  Denied,
  Authorized,
  Provisional,
  Ephemeral
}

interface UserState {
  externalId?: string;
  onesignalId?: string;
}

interface UserChangedState {
  current: UserState;
}

interface PushSubscriptionState {
  id?: string;
  token?: string;
  optedIn: boolean;
}

interface PushSubscriptionChangedState {
  previous: PushSubscriptionState;
  current: PushSubscriptionState;
}

class OSNotification {
  body: string;
  sound?: string;
  title?: string;
  launchURL?: string;
  rawPayload: object | string;
  actionButtons?: object[];
  additionalData?: object;
  notificationId: string;
  // Android-specific properties
  groupKey?: string;
  groupMessage?: string;
  ledColor?: string;
  priority?: number;
  smallIcon?: string;
  largeIcon?: string;
  bigPicture?: string;
  collapseId?: string;
  fromProjectNumber?: string;
  smallIconAccentColor?: string;
  lockScreenVisibility?: string;
  androidNotificationId?: number;
  // iOS-specific properties
  badge?: string;
  badgeIncrement?: string;
  category?: string;
  threadId?: string;
  subtitle?: string;
  templateId?: string;
  templateName?: string;
  attachments?: object;
  mutableContent?: boolean;
  contentAvailable?: string;
  relevanceScore?: number;
  interruptionLevel?: string;
  
  display(): void;
}

class NotificationWillDisplayEvent {
  notification: OSNotification;
  
  preventDefault(): void;
  getNotification(): OSNotification;
}

interface NotificationClickResult {
  actionId?: string;
  url?: string;
}

interface InAppMessageClickResult {
  closingMessage: boolean;
  actionId?: string;
  url?: string;
  urlTarget?: string;
}

interface InAppMessage {
  messageId: string;
}

interface NotificationClickEvent {
  result: NotificationClickResult;
  notification: OSNotification;
}

interface InAppMessageClickEvent {
  message: InAppMessage;
  result: InAppMessageClickResult;
}

interface InAppMessageWillDisplayEvent {
  message: InAppMessage;
}

interface InAppMessageDidDisplayEvent {
  message: InAppMessage;
}

interface InAppMessageWillDismissEvent {
  message: InAppMessage;
}

interface InAppMessageDidDismissEvent {
  message: InAppMessage;
}

type NotificationEventName = 'click' | 'foregroundWillDisplay' | 'permissionChange';

type NotificationEventTypeMap = {
  click: NotificationClickEvent;
  foregroundWillDisplay: NotificationWillDisplayEvent;
  permissionChange: boolean;
};

type InAppMessageEventName = 'click' | 'willDisplay' | 'didDisplay' | 'willDismiss' | 'didDismiss';

type InAppMessageEventTypeMap = {
  click: InAppMessageClickEvent;
  willDisplay: InAppMessageWillDisplayEvent;
  didDisplay: InAppMessageDidDisplayEvent;
  willDismiss: InAppMessageWillDismissEvent;
  didDismiss: InAppMessageDidDismissEvent;
};

interface LiveActivitySetupOptions {
  enablePushToStart: boolean;
  enablePushToUpdate: boolean;
}