0
# Notification Permissions
1

2
Specialized handling for notification permissions with granular control over notification types and settings. Provides detailed information about what notification capabilities are available and enabled.
3

4
## Capabilities
5

6
### Check Notification Status
7

8
Get the current notification permission status along with detailed settings for each notification type.
9

10
```typescript { .api }
11
/**
12
 * Check notification permissions and get detailed settings
13
 * @returns Promise resolving to notification status and settings object
14
 */
15
function checkNotifications(): Promise<NotificationsResponse>;
16

17
interface NotificationsResponse {
18
  status: PermissionStatus;
19
  settings: NotificationSettings;
20
}
21

22
interface NotificationSettings {
23
  alert?: boolean;
24
  badge?: boolean;
25
  sound?: boolean;
26
  carPlay?: boolean;
27
  criticalAlert?: boolean;
28
  provisional?: boolean;
29
  providesAppSettings?: boolean;
30
  lockScreen?: boolean;
31
  notificationCenter?: boolean;
32
}
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
import { checkNotifications, RESULTS } from "react-native-permissions";
39

40
const notificationResult = await checkNotifications();
41

42
console.log("Overall status:", notificationResult.status);
43

44
if (notificationResult.status === RESULTS.GRANTED) {
45
  const { settings } = notificationResult;
46
  
47
  // Check basic notification types
48
  console.log("Can show alerts:", settings.alert);
49
  console.log("Can show badges:", settings.badge);
50
  console.log("Can play sounds:", settings.sound);
51
  
52
  // Check advanced capabilities (iOS)
53
  console.log("CarPlay support:", settings.carPlay);
54
  console.log("Critical alerts:", settings.criticalAlert);
55
  console.log("Provisional notifications:", settings.provisional);
56
  
57
  // Check display locations
58
  console.log("Lock screen display:", settings.lockScreen);
59
  console.log("Notification center:", settings.notificationCenter);
60
}
61

62
// Determine what notifications are effectively enabled
63
function getEnabledNotificationTypes(settings: NotificationSettings): string[] {
64
  const enabled = [];
65
  if (settings.alert) enabled.push('alert');
66
  if (settings.badge) enabled.push('badge');
67
  if (settings.sound) enabled.push('sound');
68
  return enabled;
69
}
70

71
const enabledTypes = getEnabledNotificationTypes(notificationResult.settings);
72
console.log("Enabled notification types:", enabledTypes);
73
```
74

75
### Request Notification Permissions
76

77
Request notification permissions with specific notification types and optional rationale.
78

79
```typescript { .api }
80
/**
81
 * Request notification permissions with specific options
82
 * @param options - Array of notification types to request (optional)
83
 * @param rationale - Optional rationale dialog for Android
84
 * @returns Promise resolving to notification status and settings
85
 */
86
function requestNotifications(
87
  options?: NotificationOption[],
88
  rationale?: Rationale
89
): Promise<NotificationsResponse>;
90

91
type NotificationOption = 
92
  | 'alert'          // Show alert notifications
93
  | 'badge'          // Show badge on app icon
94
  | 'sound'          // Play notification sounds
95
  | 'carPlay'        // Show notifications in CarPlay (iOS)
96
  | 'criticalAlert'  // Critical alerts that bypass silent mode (iOS)
97
  | 'provisional'    // Quiet notifications delivered directly to notification center (iOS)
98
  | 'providesAppSettings'; // Indicates app has custom notification settings (iOS)
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import { requestNotifications, RESULTS } from "react-native-permissions";
105

106
// Request basic notification permissions (default)
107
const basicRequest = await requestNotifications();
108
console.log("Basic notification status:", basicRequest.status);
109

110
// Request specific notification types (iOS)
111
const specificRequest = await requestNotifications([
112
  'alert',
113
  'badge',
114
  'sound'
115
]);
116

117
if (specificRequest.status === RESULTS.GRANTED) {
118
  console.log("Requested notifications granted");
119
  console.log("Settings:", specificRequest.settings);
120
}
121

122
// Request advanced notification types (iOS)
123
const advancedRequest = await requestNotifications([
124
  'alert',
125
  'badge',
126
  'sound',
127
  'criticalAlert',
128
  'provisional',
129
  'carPlay'
130
]);
131

132
// Request with rationale (Android)
133
const androidRequest = await requestNotifications(
134
  ['alert', 'badge', 'sound'],
135
  {
136
    title: "Enable Notifications",
137
    message: "Stay updated with important messages and app updates. You can customize notification types in settings.",
138
    buttonPositive: "Enable Notifications",
139
    buttonNegative: "Skip"
140
  }
141
);
142

143
// Check for critical alert capability
144
if (advancedRequest.settings.criticalAlert) {
145
  console.log("Critical alerts are available - important notifications will bypass Do Not Disturb");
146
}
147

148
// Check for provisional notifications
149
if (advancedRequest.settings.provisional) {
150
  console.log("Provisional notifications enabled - quiet notifications delivered to notification center");
151
}
152
```
153

154
## Notification Types Explained
155

156
### Basic Notification Types
157

158
These are the core notification types available on both platforms:
159

160
```typescript
161
// Basic types supported on iOS and Android
162
const basicTypes: NotificationOption[] = ['alert', 'badge', 'sound'];
163

164
const basicNotifications = await requestNotifications(basicTypes);
165
```
166

167
- **alert**: Visual notifications that appear on screen
168
- **badge**: Red badge number on the app icon  
169
- **sound**: Audio alerts for notifications
170

171
### iOS-Specific Notification Types
172

173
Advanced notification types available only on iOS:
174

175
```typescript
176
// iOS-specific advanced types
177
const iosAdvancedTypes: NotificationOption[] = [
178
  'carPlay',           // Show in CarPlay interface
179
  'criticalAlert',     // Bypass silent mode and Do Not Disturb
180
  'provisional',       // Quiet delivery to notification center
181
  'providesAppSettings' // App has custom notification settings
182
];
183

184
const iosNotifications = await requestNotifications([
185
  ...basicTypes,
186
  ...iosAdvancedTypes
187
]);
188
```
189

190
- **carPlay**: Notifications appear in CarPlay interface when connected
191
- **criticalAlert**: Critical notifications that bypass silent mode and Do Not Disturb
192
- **provisional**: Delivered quietly to notification center without interrupting user
193
- **providesAppSettings**: Indicates the app provides custom notification settings UI
194

195
### Notification Settings Details
196

197
The `NotificationSettings` object provides detailed information about what's enabled:
198

199
```typescript
200
interface NotificationSettings {
201
  // Requested notification types
202
  alert?: boolean;
203
  badge?: boolean;
204
  sound?: boolean;
205
  carPlay?: boolean;
206
  criticalAlert?: boolean;
207
  provisional?: boolean;
208
  providesAppSettings?: boolean;
209
  
210
  // System-determined display locations
211
  lockScreen?: boolean;        // Can appear on lock screen
212
  notificationCenter?: boolean; // Can appear in notification center
213
}
214

215
// Example usage
216
const result = await checkNotifications();
217
const { settings } = result;
218

219
// Check if notifications will be visible to user
220
const isVisible = settings.alert || settings.lockScreen || settings.notificationCenter;
221

222
// Check if notifications will make sound/vibration
223
const isAudible = settings.sound;
224

225
// Check if app icon will show badge
226
const showsBadge = settings.badge;
227

228
console.log(`Notifications visible: ${isVisible}, audible: ${isAudible}, shows badge: ${showsBadge}`);
229
```
230

231
## Platform Differences
232

233
### iOS Notification Behavior
234

235
```typescript
236
// iOS allows granular control over notification types
237
const iosResult = await requestNotifications([
238
  'alert',
239
  'badge', 
240
  'sound',
241
  'provisional' // iOS-specific: quiet delivery
242
]);
243

244
// iOS users can partially grant - some types enabled, others disabled
245
if (iosResult.status === RESULTS.GRANTED) {
246
  if (iosResult.settings.provisional && !iosResult.settings.alert) {
247
    console.log("User granted quiet notifications only");
248
  }
249
}
250

251
// Critical alerts require special entitlement
252
const criticalResult = await requestNotifications(['criticalAlert']);
253
if (criticalResult.settings.criticalAlert) {
254
  console.log("Critical alerts enabled - will bypass Do Not Disturb");
255
}
256
```
257

258
### Android Notification Behavior
259

260
```typescript
261
// Android treats notifications more as all-or-nothing
262
const androidResult = await requestNotifications(
263
  ['alert', 'badge', 'sound'],
264
  {
265
    title: "Stay Connected",
266
    message: "Enable notifications to receive important updates and messages from your contacts.",
267
    buttonPositive: "Allow",
268
    buttonNegative: "Not now"
269
  }
270
);
271

272
// Android notification channels provide additional control
273
// (handled by the native implementation)
274
```
275

276
## Common Usage Patterns
277

278
### Progressive Notification Requests
279

280
Request basic notifications first, then advanced features:
281

282
```typescript
283
import { requestNotifications, RESULTS } from "react-native-permissions";
284

285
async function setupNotifications() {
286
  // Start with basic notifications
287
  let result = await requestNotifications(['alert', 'badge', 'sound']);
288
  
289
  if (result.status === RESULTS.GRANTED) {
290
    console.log("Basic notifications enabled");
291
    
292
    // Request advanced features if basic ones are granted
293
    const advancedResult = await requestNotifications([
294
      'alert', 'badge', 'sound', // Include previously granted
295
      'provisional',              // Add new advanced feature
296
      'criticalAlert'
297
    ]);
298
    
299
    if (advancedResult.settings.provisional) {
300
      console.log("Provisional notifications available");
301
    }
302
    
303
    return advancedResult;
304
  } else {
305
    console.log("Basic notifications denied");
306
    return result;
307
  }
308
}
309
```
310

311
### Notification Settings Analysis
312

313
Analyze notification capabilities for app features:
314

315
```typescript
316
import { checkNotifications } from "react-native-permissions";
317

318
async function analyzeNotificationCapabilities() {
319
  const result = await checkNotifications();
320
  
321
  const capabilities = {
322
    canShowAlerts: result.settings.alert === true,
323
    canShowBadges: result.settings.badge === true,  
324
    canPlaySounds: result.settings.sound === true,
325
    hasQuietDelivery: result.settings.provisional === true,
326
    hasCriticalAlerts: result.settings.criticalAlert === true,
327
    appearsOnLockScreen: result.settings.lockScreen === true,
328
    appearsInNotificationCenter: result.settings.notificationCenter === true
329
  };
330
  
331
  console.log("Notification capabilities:", capabilities);
332
  
333
  // Adapt app behavior based on capabilities
334
  if (!capabilities.canShowAlerts && capabilities.appearsInNotificationCenter) {
335
    console.log("Notifications delivered quietly to notification center");
336
  }
337
  
338
  if (capabilities.hasCriticalAlerts) {
339
    console.log("Can send emergency notifications that bypass Do Not Disturb");
340
  }
341
  
342
  return capabilities;
343
}
344
```
345

346
### Handling Notification Permission States
347

348
```typescript
349
import { checkNotifications, requestNotifications, openSettings, RESULTS } from "react-native-permissions";
350

351
async function ensureNotificationsEnabled(): Promise<boolean> {
352
  let result = await checkNotifications();
353
  
354
  if (result.status === RESULTS.GRANTED) {
355
    console.log("Notifications already enabled");
356
    return true;
357
  }
358
  
359
  if (result.status === RESULTS.DENIED) {
360
    // Try to request permission
361
    result = await requestNotifications(['alert', 'badge', 'sound']);
362
    
363
    if (result.status === RESULTS.GRANTED) {
364
      console.log("Notifications enabled by user");
365
      return true;
366
    }
367
  }
368
  
369
  if (result.status === RESULTS.BLOCKED) {
370
    // Direct user to settings
371
    console.log("Notifications blocked - directing to settings");
372
    await openSettings('notifications');
373
    return false;
374
  }
375
  
376
  console.log("Notifications not available or denied");
377
  return false;
378
}
379
```
380

381
## Error Handling
382

383
```typescript
384
import { requestNotifications } from "react-native-permissions";
385

386
async function safeRequestNotifications(options?: NotificationOption[]) {
387
  try {
388
    const result = await requestNotifications(options);
389
    return { success: true, result };
390
  } catch (error) {
391
    console.error("Failed to request notifications:", error);
392
    
393
    // Provide fallback behavior
394
    return { 
395
      success: false, 
396
      error,
397
      result: {
398
        status: 'unavailable' as const,
399
        settings: {}
400
      }
401
    };
402
  }
403
}
404

405
// Usage
406
const response = await safeRequestNotifications(['alert', 'badge']);
407
if (response.success) {
408
  console.log("Notification request completed:", response.result);
409
} else {
410
  console.log("Notification request failed, continuing without notifications");
411
}
412
```