or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-sdk.mdin-app-messages.mdindex.mdlive-activities.mdlocation.mdnotifications.mdpush-subscription.mdsession.mduser-management.md
tile.json

tessl/npm-react-native-onesignal

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-native-onesignal@5.2.x

To install, run

npx @tessl/cli install tessl/npm-react-native-onesignal@5.2.0

index.mddocs/

React Native OneSignal

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;
}