0
# Notification Handling
1

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

4
## Capabilities
5

6
### Permission Management
7

8
Manage notification permissions and check permission status.
9

10
```typescript { .api }
11
/**
12
 * Whether this app has push notification permission. Returns true if the user has accepted 
13
 * permissions, or if the app has ephemeral or provisional permission.
14
 * @returns Promise resolving to permission status
15
 */
16
function getPermissionAsync(): Promise<boolean>;
17

18
/**
19
 * Prompt the user for permission to receive push notifications. This will display the native 
20
 * system prompt to request push notification permission. Use the fallbackToSettings parameter 
21
 * to prompt to open the settings app if a user has already declined push permissions.
22
 * @param fallbackToSettings - Whether to fallback to settings if permission was previously declined
23
 * @returns Promise resolving to whether permission was granted
24
 */
25
function requestPermission(fallbackToSettings: boolean): Promise<boolean>;
26

27
/**
28
 * Whether attempting to request notification permission will show a prompt. Returns true if 
29
 * the device has not been prompted for push notification permission already.
30
 * @returns Promise resolving to whether permission can be requested
31
 */
32
function canRequestPermission(): Promise<boolean>;
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { OneSignal } from "react-native-onesignal";
39

40
// Check current permission status
41
const hasPermission = await OneSignal.Notifications.getPermissionAsync();
42
console.log('Has notification permission:', hasPermission);
43

44
// Check if we can request permission (hasn't been asked before)
45
const canRequest = await OneSignal.Notifications.canRequestPermission();
46
if (canRequest) {
47
  // Request permission with fallback to settings
48
  const granted = await OneSignal.Notifications.requestPermission(true);
49
  console.log('Permission granted:', granted);
50
}
51
```
52

53
### iOS-Specific Permission Features
54

55
Advanced iOS permission features including provisional authorization and native permission status.
56

57
```typescript { .api }
58
/**
59
 * Instead of having to prompt the user for permission to send them push notifications, your app 
60
 * can request provisional authorization. iOS only.
61
 * For more information: https://documentation.onesignal.com/docs/ios-customizations#provisional-push-notifications
62
 * @param handler - Callback function receiving authorization result
63
 */
64
function registerForProvisionalAuthorization(handler: (response: boolean) => void): void;
65

66
/**
67
 * iOS Only. Returns the enum for the native permission of the device. It will be one of:
68
 * OSNotificationPermissionNotDetermined,
69
 * OSNotificationPermissionDenied,
70
 * OSNotificationPermissionAuthorized,
71
 * OSNotificationPermissionProvisional - only available in iOS 12,
72
 * OSNotificationPermissionEphemeral - only available in iOS 14
73
 * @returns Promise resolving to native permission status
74
 */
75
function permissionNative(): Promise<OSNotificationPermission>;
76
```
77

78
**Usage Examples:**
79

80
```typescript
81
import { Platform } from "react-native";
82

83
// iOS-specific provisional authorization
84
if (Platform.OS === 'ios') {
85
  OneSignal.Notifications.registerForProvisionalAuthorization((granted) => {
86
    console.log('Provisional authorization:', granted);
87
  });
88
  
89
  // Get detailed iOS permission status
90
  const nativePermission = await OneSignal.Notifications.permissionNative();
91
  console.log('Native permission status:', nativePermission);
92
}
93
```
94

95
### Notification Event Handling
96

97
Handle notification click events, display lifecycle, and permission changes.
98

99
```typescript { .api }
100
/**
101
 * Add listeners for notification click and/or lifecycle events.
102
 * @param event - The event type to listen for
103
 * @param listener - Callback function for the event
104
 */
105
function addEventListener<K extends NotificationEventName>(
106
  event: K,
107
  listener: (event: NotificationEventTypeMap[K]) => void
108
): void;
109

110
/**
111
 * Remove listeners for notification click and/or lifecycle events.
112
 * @param event - The event type to stop listening for
113
 * @param listener - The callback function to remove
114
 */
115
function removeEventListener<K extends NotificationEventName>(
116
  event: K,  
117
  listener: (event: NotificationEventTypeMap[K]) => void
118
): void;
119
```
120

121
**Usage Examples:**
122

123
```typescript
124
// Handle notification clicks
125
OneSignal.Notifications.addEventListener('click', (event) => {
126
  console.log('Notification clicked:', {
127
    notification: event.notification,
128
    actionId: event.result.actionId,
129
    url: event.result.url
130
  });
131
  
132
  // Navigate or perform action based on click
133
  if (event.result.url) {
134
    // Open URL or navigate to screen
135
  }
136
});
137

138
// Handle notifications that will display in foreground
139
OneSignal.Notifications.addEventListener('foregroundWillDisplay', (event) => {
140
  console.log('Notification will display:', event.notification);
141
  
142
  // Optionally prevent display
143
  // event.preventDefault();
144
});
145

146
// Handle permission changes
147
OneSignal.Notifications.addEventListener('permissionChange', (granted) => {
148
  console.log('Permission changed:', granted);
149
  
150
  if (granted) {
151
    // Permission was granted - user can now receive notifications
152
  } else {
153
    // Permission was denied or revoked
154
  }
155
});
156
```
157

158
### Notification Management
159

160
Clear and remove notifications from the notification center.
161

162
```typescript { .api }
163
/**
164
 * Removes all OneSignal notifications.
165
 */
166
function clearAll(): void;
167

168
/**
169
 * Android Only. Removes a single OneSignal notification based on its Android notification integer id.
170
 * @param id - Android notification ID to remove
171
 */
172
function removeNotification(id: number): void;
173

174
/**
175
 * Android Only. Removes all OneSignal notifications based on its Android notification group Id.
176
 * @param id - Notification group ID to cancel
177
 */
178
function removeGroupedNotifications(id: string): void;
179
```
180

181
**Usage Examples:**
182

183
```typescript
184
import { Platform } from "react-native";
185

186
// Clear all notifications
187
OneSignal.Notifications.clearAll();
188

189
// Android-specific notification removal
190
if (Platform.OS === 'android') {
191
  // Remove specific notification by ID
192
  OneSignal.Notifications.removeNotification(12345);
193
  
194
  // Remove all notifications in a group
195
  OneSignal.Notifications.removeGroupedNotifications("promo-group");
196
}
197
```
198

199
### Deprecated Methods
200

201
```typescript { .api }
202
/**
203
 * @deprecated This method is deprecated. It has been replaced by getPermissionAsync.
204
 */
205
function hasPermission(): boolean;
206
```
207

208
**Migration Example:**
209

210
```typescript
211
// OLD (deprecated) - synchronous method
212
const oldHasPermission = OneSignal.Notifications.hasPermission();
213

214
// NEW - async method with better error handling  
215
const newHasPermission = await OneSignal.Notifications.getPermissionAsync();
216
```
217

218
## Types
219

220
```typescript { .api }
221
type NotificationEventName = 'click' | 'foregroundWillDisplay' | 'permissionChange';
222

223
type NotificationEventTypeMap = {
224
  click: NotificationClickEvent;
225
  foregroundWillDisplay: NotificationWillDisplayEvent;
226
  permissionChange: boolean;
227
};
228

229
interface NotificationClickEvent {
230
  result: NotificationClickResult;
231
  notification: OSNotification;
232
}
233

234
interface NotificationClickResult {
235
  actionId?: string;
236
  url?: string;
237
}
238

239
enum OSNotificationPermission {
240
  NotDetermined = 0,
241
  Denied,
242
  Authorized,
243
  Provisional,
244
  Ephemeral
245
}
246

247
class OSNotification {
248
  body: string;
249
  title?: string;
250
  notificationId: string;
251
  // ... additional platform-specific properties
252
  
253
  display(): void;
254
}
255

256
class NotificationWillDisplayEvent {
257
  notification: OSNotification;
258
  
259
  preventDefault(): void;
260
  getNotification(): OSNotification;
261
}
262
```