0
# Permissions & Registration
1

2
Permission management and device registration for receiving push notifications. These features are primarily iOS-focused, as Android handles permissions differently.
3

4
## Capabilities
5

6
### Request Permissions
7

8
Requests notification permissions from the user. Required on iOS before receiving notifications. Android permissions are handled at install time.
9

10
```typescript { .api }
11
/**
12
 * Request notification permissions (iOS primarily)
13
 * @param permissions - Optional iOS permission configuration
14
 * @returns Promise resolving to AuthorizationStatus
15
 */
16
function requestPermission(permissions?: IOSPermissions): Promise<AuthorizationStatus>;
17

18
interface IOSPermissions {
19
  /** Request permission to display alerts (default: true) */
20
  alert?: boolean;
21
  /** Request permission for Siri to read notifications over AirPods (default: false, iOS 13+) */
22
  announcement?: boolean;
23
  /** Request permission to update the application badge (default: true) */
24
  badge?: boolean;
25
  /** Request permission for critical alerts (default: false) */
26
  criticalAlert?: boolean;
27
  /** Request permission to display notifications in CarPlay (default: true) */
28
  carPlay?: boolean;
29
  /** Request provisional authorization for quiet notifications (default: false, iOS 12+) */
30
  provisional?: boolean;
31
  /** Request permission to play sounds (default: true) */
32
  sound?: boolean;
33
  /** Request permission to display notification settings button (default: false, iOS 12+) */
34
  providesAppNotificationSettings?: boolean;
35
}
36

37
enum AuthorizationStatus {
38
  /** User has not yet chosen whether to allow notifications (iOS) */
39
  NOT_DETERMINED = -1,
40
  /** App is not authorized to create notifications */
41
  DENIED = 0,
42
  /** App is authorized to create notifications */
43
  AUTHORIZED = 1,
44
  /** App is authorized for provisional notifications (iOS 12+) */
45
  PROVISIONAL = 2,
46
  /** App is authorized for limited time (iOS 14+, App Clips) */
47
  EPHEMERAL = 3,
48
}
49
```
50

51
**Usage Examples:**
52

53
```typescript
54
import messaging from '@react-native-firebase/messaging';
55

56
// Request default permissions
57
const authStatus = await messaging().requestPermission();
58

59
if (authStatus === messaging.AuthorizationStatus.AUTHORIZED) {
60
  console.log('Authorization status:', authStatus);
61
} else if (authStatus === messaging.AuthorizationStatus.PROVISIONAL) {
62
  console.log('Provisional authorization granted');
63
} else {
64
  console.log('Permission denied');
65
}
66

67
// Request specific permissions (iOS)
68
const customAuthStatus = await messaging().requestPermission({
69
  alert: true,
70
  badge: true,
71
  sound: true,
72
  provisional: false,
73
  criticalAlert: false,
74
  carPlay: true,
75
  announcement: false,
76
  providesAppNotificationSettings: true,
77
});
78

79
// Modular API
80
import { getMessaging, requestPermission } from '@react-native-firebase/messaging';
81
const messagingInstance = getMessaging();
82
const authStatus = await requestPermission(messagingInstance, {
83
  alert: true,
84
  badge: true,
85
  sound: true,
86
});
87
```
88

89
### Check Permission Status
90

91
Checks the current notification permission status without requesting new permissions.
92

93
```typescript { .api }
94
/**
95
 * Returns current authorization status for notifications
96
 * @returns Promise resolving to current AuthorizationStatus
97
 */
98
function hasPermission(): Promise<AuthorizationStatus>;
99
```
100

101
**Usage Examples:**
102

103
```typescript
104
import messaging from '@react-native-firebase/messaging';
105

106
// Check current permission status
107
const authStatus = await messaging().hasPermission();
108

109
switch (authStatus) {
110
  case messaging.AuthorizationStatus.AUTHORIZED:
111
    console.log('User has authorized notifications');
112
    break;
113
  case messaging.AuthorizationStatus.DENIED:
114
    console.log('User has denied notifications');
115
    break;
116
  case messaging.AuthorizationStatus.NOT_DETERMINED:
117
    console.log('Permission not requested yet');
118
    // Request permission
119
    await messaging().requestPermission();
120
    break;
121
  case messaging.AuthorizationStatus.PROVISIONAL:
122
    console.log('User has provisional authorization');
123
    break;
124
}
125

126
// Modular API
127
import { getMessaging, hasPermission } from '@react-native-firebase/messaging';
128
const messagingInstance = getMessaging();
129
const authStatus = await hasPermission(messagingInstance);
130
```
131

132
### Device Registration for Remote Messages
133

134
Explicitly register the device for remote notifications. Only needed on iOS when auto-registration is disabled.
135

136
```typescript { .api }
137
/**
138
 * Register device for remote notifications (iOS only)
139
 * @returns Promise that resolves when registration is complete
140
 */
141
function registerDeviceForRemoteMessages(): Promise<void>;
142

143
/**
144
 * Check if device is registered for remote notifications
145
 * @returns Boolean indicating registration status (iOS only, Android always returns true)
146
 */
147
readonly isDeviceRegisteredForRemoteMessages: boolean;
148

149
/**
150
 * Unregister device from remote notifications (iOS only)
151
 * @returns Promise that resolves when unregistration is complete
152
 */
153
function unregisterDeviceForRemoteMessages(): Promise<void>;
154
```
155

156
**Usage Examples:**
157

158
```typescript
159
import messaging from '@react-native-firebase/messaging';
160

161
// Check if already registered
162
if (!messaging().isDeviceRegisteredForRemoteMessages) {
163
  // Register for remote notifications
164
  await messaging().registerDeviceForRemoteMessages();
165
  console.log('Device registered for remote messages');
166
}
167

168
// Unregister when user opts out
169
await messaging().unregisterDeviceForRemoteMessages();
170
console.log('Device unregistered from remote messages');
171

172
// Modular API
173
import { 
174
  getMessaging, 
175
  isDeviceRegisteredForRemoteMessages,
176
  registerDeviceForRemoteMessages,
177
  unregisterDeviceForRemoteMessages 
178
} from '@react-native-firebase/messaging';
179

180
const messagingInstance = getMessaging();
181

182
if (!isDeviceRegisteredForRemoteMessages(messagingInstance)) {
183
  await registerDeviceForRemoteMessages(messagingInstance);
184
}
185

186
await unregisterDeviceForRemoteMessages(messagingInstance);
187
```
188

189
### Utility Functions
190

191
Additional utilities for checking messaging support and configuration.
192

193
```typescript { .api }
194
/**
195
 * Check if messaging is supported on current platform
196
 * @returns Promise resolving to boolean indicating support
197
 */
198
function isSupported(): Promise<boolean>;
199
```
200

201
**Usage Examples:**
202

203
```typescript
204
import messaging from '@react-native-firebase/messaging';
205

206
// Check if messaging is supported
207
const supported = await messaging().isSupported();
208

209
if (supported) {
210
  console.log('Messaging is supported');
211
  // Proceed with messaging setup
212
  await messaging().requestPermission();
213
} else {
214
  console.log('Messaging not supported on this platform');
215
  // Handle unsupported scenario
216
}
217

218
// Modular API
219
import { getMessaging, isSupported } from '@react-native-firebase/messaging';
220
const messagingInstance = getMessaging();
221
const supported = await isSupported(messagingInstance);
222
```
223

224
## Permission Workflow
225

226
### iOS Permission Flow
227

228
1. **Check Status**: Use `hasPermission()` to check current state
229
2. **Request Permission**: Call `requestPermission()` if needed
230
3. **Handle Response**: Process the authorization status
231
4. **Register Device**: Call `registerDeviceForRemoteMessages()` if auto-registration disabled
232
5. **Get Token**: Retrieve FCM token once permissions granted
233

234
### Android Permission Flow
235

236
1. **Automatic**: Permissions granted at install time for target SDK < 33
237
2. **Runtime**: For target SDK 33+, use standard Android permission request
238
3. **Always Authorized**: `requestPermission()` always returns `AUTHORIZED`
239

240
## Permission Best Practices
241

242
1. **Check Before Request**: Always check current status before requesting
243
2. **Explain Purpose**: Show UI explaining why notifications are needed
244
3. **Handle Denial**: Provide fallback experience when permissions denied
245
4. **Respect Preferences**: Don't repeatedly ask after denial
246
5. **Guide to Settings**: Direct users to system settings if needed
247

248
## Common Permission Scenarios
249

250
```typescript
251
import messaging from '@react-native-firebase/messaging';
252

253
async function setupMessaging() {
254
  // Check if messaging is supported
255
  const supported = await messaging().isSupported();
256
  if (!supported) {
257
    console.log('Messaging not supported');
258
    return;
259
  }
260

261
  // Check current permission status
262
  let authStatus = await messaging().hasPermission();
263
  
264
  if (authStatus === messaging.AuthorizationStatus.NOT_DETERMINED) {
265
    // Request permission
266
    authStatus = await messaging().requestPermission({
267
      alert: true,
268
      badge: true,
269
      sound: true,
270
      provisional: false,
271
    });
272
  }
273

274
  if (authStatus === messaging.AuthorizationStatus.AUTHORIZED || 
275
      authStatus === messaging.AuthorizationStatus.PROVISIONAL) {
276
    
277
    // Ensure device is registered (iOS)
278
    if (!messaging().isDeviceRegisteredForRemoteMessages) {
279
      await messaging().registerDeviceForRemoteMessages();
280
    }
281
    
282
    // Get FCM token
283
    const token = await messaging().getToken();
284
    console.log('FCM Token:', token);
285
    
286
    return token;
287
  } else {
288
    console.log('Permission denied');
289
    return null;
290
  }
291
}
292
```