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
```