0
# React Native OneSignal
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: react-native-onesignal
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-onesignal`
10

11
## Core Imports
12

13
```typescript
14
import { OneSignal, LogLevel } from "react-native-onesignal";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { OneSignal, LogLevel } = require("react-native-onesignal");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { OneSignal, LogLevel } from "react-native-onesignal";
27

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

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

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

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

42
// Add user tags for segmentation
43
OneSignal.User.addTag("subscription", "premium");
44
```
45

46
## Architecture
47

48
React Native OneSignal is built around several key components:
49

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

59
## Capabilities
60

61
### Core SDK Functions
62

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

65
```typescript { .api }
66
function initialize(appId: string): void;
67
function login(externalId: string): void;
68
function logout(): void;
69
function setConsentRequired(required: boolean): void;
70
function setConsentGiven(granted: boolean): void;
71
```
72

73
[Core SDK](./core-sdk.md)
74

75
### User Management
76

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

79
```typescript { .api }
80
namespace User {
81
  function addEventListener(event: 'change', listener: (event: UserChangedState) => void): void;
82
  function getOnesignalId(): Promise<string | null>;
83
  function getExternalId(): Promise<string | null>;
84
  function addTag(key: string, value: string): void;
85
  function addTags(tags: object): void;
86
  function addEmail(email: string): void;
87
  function addSms(smsNumber: string): void;
88
}
89
```
90

91
[User Management](./user-management.md)
92

93
### Push Subscription Management
94

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

97
```typescript { .api }
98
namespace User.pushSubscription {
99
  function addEventListener(event: 'change', listener: (event: PushSubscriptionChangedState) => void): void;
100
  function getIdAsync(): Promise<string | null>;
101
  function getTokenAsync(): Promise<string | null>;
102
  function getOptedInAsync(): Promise<boolean>;
103
  function optIn(): void;
104
  function optOut(): void;
105
}
106
```
107

108
[Push Subscription Management](./push-subscription.md)
109

110
### Notification Handling
111

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

114
```typescript { .api }
115
namespace Notifications {
116
  function getPermissionAsync(): Promise<boolean>;
117
  function requestPermission(fallbackToSettings: boolean): Promise<boolean>;
118
  function addEventListener<K extends NotificationEventName>(
119
    event: K,
120
    listener: (event: NotificationEventTypeMap[K]) => void
121
  ): void;
122
  function clearAll(): void;
123
}
124
```
125

126
[Notification Handling](./notifications.md)
127

128
### In-App Messages
129

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

132
```typescript { .api }
133
namespace InAppMessages {
134
  function addEventListener<K extends InAppMessageEventName>(
135
    event: K,
136
    listener: (event: InAppMessageEventTypeMap[K]) => void
137
  ): void;
138
  function addTrigger(key: string, value: string): void;
139
  function addTriggers(triggers: { [key: string]: string }): void;
140
  function setPaused(pause: boolean): void;
141
}
142
```
143

144
[In-App Messages](./in-app-messages.md)
145

146
### Live Activities (iOS)
147

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

150
```typescript { .api }
151
namespace LiveActivities {
152
  function enter(activityId: string, token: string, handler?: Function): void;
153
  function exit(activityId: string, handler?: Function): void;
154
  function setupDefault(options?: LiveActivitySetupOptions): void;
155
  function startDefault(activityId: string, attributes: object, content: object): void;
156
}
157
```
158

159
[Live Activities](./live-activities.md)
160

161
### Location Services
162

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

165
```typescript { .api }
166
namespace Location {
167
  function requestPermission(): void;
168
  function setShared(shared: boolean): void;
169
  function isShared(): Promise<boolean>;
170
}
171
```
172

173
[Location Services](./location.md)
174

175
### Session Analytics
176

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

179
```typescript { .api }
180
namespace Session {
181
  function addOutcome(name: string): void;
182
  function addUniqueOutcome(name: string): void;
183
  function addOutcomeWithValue(name: string, value: string | number): void;
184
}
185
```
186

187
[Session Analytics](./session.md)
188

189
## Types
190

191
```typescript { .api }
192
enum LogLevel {
193
  None,
194
  Fatal,
195
  Error,
196
  Warn,
197
  Info,
198
  Debug,
199
  Verbose
200
}
201

202
enum OSNotificationPermission {
203
  NotDetermined = 0,
204
  Denied,
205
  Authorized,
206
  Provisional,
207
  Ephemeral
208
}
209

210
interface UserState {
211
  externalId?: string;
212
  onesignalId?: string;
213
}
214

215
interface UserChangedState {
216
  current: UserState;
217
}
218

219
interface PushSubscriptionState {
220
  id?: string;
221
  token?: string;
222
  optedIn: boolean;
223
}
224

225
interface PushSubscriptionChangedState {
226
  previous: PushSubscriptionState;
227
  current: PushSubscriptionState;
228
}
229

230
class OSNotification {
231
  body: string;
232
  sound?: string;
233
  title?: string;
234
  launchURL?: string;
235
  rawPayload: object | string;
236
  actionButtons?: object[];
237
  additionalData?: object;
238
  notificationId: string;
239
  // Android-specific properties
240
  groupKey?: string;
241
  groupMessage?: string;
242
  ledColor?: string;
243
  priority?: number;
244
  smallIcon?: string;
245
  largeIcon?: string;
246
  bigPicture?: string;
247
  collapseId?: string;
248
  fromProjectNumber?: string;
249
  smallIconAccentColor?: string;
250
  lockScreenVisibility?: string;
251
  androidNotificationId?: number;
252
  // iOS-specific properties
253
  badge?: string;
254
  badgeIncrement?: string;
255
  category?: string;
256
  threadId?: string;
257
  subtitle?: string;
258
  templateId?: string;
259
  templateName?: string;
260
  attachments?: object;
261
  mutableContent?: boolean;
262
  contentAvailable?: string;
263
  relevanceScore?: number;
264
  interruptionLevel?: string;
265
  
266
  display(): void;
267
}
268

269
class NotificationWillDisplayEvent {
270
  notification: OSNotification;
271
  
272
  preventDefault(): void;
273
  getNotification(): OSNotification;
274
}
275

276
interface NotificationClickResult {
277
  actionId?: string;
278
  url?: string;
279
}
280

281
interface InAppMessageClickResult {
282
  closingMessage: boolean;
283
  actionId?: string;
284
  url?: string;
285
  urlTarget?: string;
286
}
287

288
interface InAppMessage {
289
  messageId: string;
290
}
291

292
interface NotificationClickEvent {
293
  result: NotificationClickResult;
294
  notification: OSNotification;
295
}
296

297
interface InAppMessageClickEvent {
298
  message: InAppMessage;
299
  result: InAppMessageClickResult;
300
}
301

302
interface InAppMessageWillDisplayEvent {
303
  message: InAppMessage;
304
}
305

306
interface InAppMessageDidDisplayEvent {
307
  message: InAppMessage;
308
}
309

310
interface InAppMessageWillDismissEvent {
311
  message: InAppMessage;
312
}
313

314
interface InAppMessageDidDismissEvent {
315
  message: InAppMessage;
316
}
317

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

320
type NotificationEventTypeMap = {
321
  click: NotificationClickEvent;
322
  foregroundWillDisplay: NotificationWillDisplayEvent;
323
  permissionChange: boolean;
324
};
325

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

328
type InAppMessageEventTypeMap = {
329
  click: InAppMessageClickEvent;
330
  willDisplay: InAppMessageWillDisplayEvent;
331
  didDisplay: InAppMessageDidDisplayEvent;
332
  willDismiss: InAppMessageWillDismissEvent;
333
  didDismiss: InAppMessageDidDismissEvent;
334
};
335

336
interface LiveActivitySetupOptions {
337
  enablePushToStart: boolean;
338
  enablePushToUpdate: boolean;
339
}
340
```