0
# Utils
1

2
Platform utilities including file path constants, Google Play Services helpers, Firebase Test Lab detection, and cross-platform development utilities.
3

4
## Capabilities
5

6
### Utils Module Access
7

8
The Utils module provides platform-specific utilities and is available through both the traditional and modular APIs.
9

10
```typescript { .api }
11
// Traditional API
12
import firebase from '@react-native-firebase/app';
13
const utils = firebase.utils();
14

15
// Direct import
16
import { utils } from '@react-native-firebase/app';
17
const utilsInstance = utils();
18
```
19

20
### Test Lab Detection
21

22
Determines if the app is currently running inside a Firebase Test Lab environment.
23

24
```typescript { .api }
25
/**
26
 * Returns true if this app is running inside a Firebase Test Lab environment
27
 * Android only - iOS always returns false
28
 */
29
interface Utils.Module {
30
  isRunningInTestLab: boolean;
31
}
32
```
33

34
**Usage Examples:**
35

36
```typescript
37
import firebase from '@react-native-firebase/app';
38

39
const utils = firebase.utils();
40

41
if (utils.isRunningInTestLab) {
42
  console.log('Running in Firebase Test Lab');
43
  // Disable animations or enable test-specific behavior
44
} else {
45
  console.log('Running on real device or simulator');
46
}
47
```
48

49
### Google Play Services Management
50

51
Comprehensive Google Play Services availability checking and resolution functionality for Android devices.
52

53
```typescript { .api }
54
/**
55
 * Google Play Services availability status and management
56
 * Android only - iOS returns placeholder values
57
 */
58
interface Utils.Module {
59
  /** Current Play Services availability status */
60
  playServicesAvailability: PlayServicesAvailability;
61
  
62
  /** Gets current Play Services status */
63
  getPlayServicesStatus(): Promise<PlayServicesAvailability>;
64
  
65
  /** Prompts user to update Play Services */
66
  promptForPlayServices(): Promise<void>;
67
  
68
  /** Attempts to make Play Services available */
69
  makePlayServicesAvailable(): Promise<void>;
70
  
71
  /** Resolves Play Services errors via user interaction */
72
  resolutionForPlayServices(): Promise<void>;
73
  
74
  /** Logs information messages for debugging */
75
  logInfo(...args: any[]): void;
76
}
77

78
interface PlayServicesAvailability {
79
  status: PlayServicesAvailabilityStatusCodes;
80
  isAvailable: boolean;
81
  hasResolution: boolean | undefined;
82
  isUserResolvableError: boolean | undefined;
83
  error: string | undefined;
84
}
85

86
enum PlayServicesAvailabilityStatusCodes {
87
  SUCCESS = 0,
88
  SERVICE_MISSING = 1,
89
  SERVICE_VERSION_UPDATE_REQUIRED = 2,
90
  SERVICE_DISABLED = 3,
91
  SIGN_IN_REQUIRED = 4,
92
  INVALID_ACCOUNT = 5,
93
  RESOLUTION_REQUIRED = 6,
94
  NETWORK_ERROR = 7,
95
  INTERNAL_ERROR = 8,
96
  SERVICE_INVALID = 9,
97
  DEVELOPER_ERROR = 10,
98
  LICENSE_CHECK_FAILED = 11,
99
  CANCELED = 13,
100
  TIMEOUT = 14,
101
  INTERRUPTED = 15,
102
  API_UNAVAILABLE = 16,
103
  SIGN_IN_FAILED = 17,
104
  SERVICE_UPDATING = 18,
105
  SERVICE_MISSING_PERMISSION = 19,
106
  RESTRICTED_PROFILE = 20,
107
  DRIVE_EXTERNAL_STORAGE_REQUIRED = 1500,
108
}
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import firebase from '@react-native-firebase/app';
115
import { Platform } from 'react-native';
116

117
const utils = firebase.utils();
118

119
if (Platform.OS === 'android') {
120
  // Check Play Services availability
121
  const availability = utils.playServicesAvailability;
122
  
123
  if (availability.isAvailable) {
124
    console.log('Google Play Services is available');
125
  } else {
126
    console.log('Google Play Services not available:', availability.error);
127
    
128
    if (availability.hasResolution) {
129
      try {
130
        // Try to resolve the issue
131
        await utils.resolutionForPlayServices();
132
        console.log('Play Services issue resolved');
133
      } catch (error) {
134
        console.log('Could not resolve Play Services issue');
135
      }
136
    }
137
  }
138
  
139
  // Get current status
140
  const status = await utils.getPlayServicesStatus();
141
  console.log('Play Services Status:', status.status);
142
  
143
  // Prompt user to update if needed
144
  if (status.status === 2) { // SERVICE_VERSION_UPDATE_REQUIRED
145
    await utils.promptForPlayServices();
146
  }
147
  
148
  // Log debugging information
149
  utils.logInfo('Play Services initialized successfully');
150
}
151
```
152

153
### File Path Constants
154

155
Platform-specific file path constants for accessing device directories.
156

157
```typescript { .api }
158
/**
159
 * File path constants for accessing device directories
160
 * Cross-platform with platform-specific availability
161
 */
162
interface Utils.FilePath {
163
  /** iOS only - Returns absolute path to applications main bundle */
164
  MAIN_BUNDLE: string;
165
  
166
  /** Returns absolute path to application specific cache directory */
167
  CACHES_DIRECTORY: string;
168
  
169
  /** Returns absolute path to users Documents directory */
170
  DOCUMENT_DIRECTORY: string;
171
  
172
  /** Android only - Returns path to external storage directory, null if unavailable */
173
  EXTERNAL_DIRECTORY: string | null;
174
  
175
  /** Android only - Returns path to external storage directory, null if unavailable */
176
  EXTERNAL_STORAGE_DIRECTORY: string | null;
177
  
178
  /** Returns absolute path to temporary directory */
179
  TEMP_DIRECTORY: string;
180
  
181
  /** Returns absolute path to apps library/resources directory */
182
  LIBRARY_DIRECTORY: string;
183
  
184
  /** Returns absolute path to pictures directory */
185
  PICTURES_DIRECTORY: string;
186
  
187
  /** Returns absolute path to movies directory */
188
  MOVIES_DIRECTORY: string;
189

190
  /** File type constant for regular files */
191
  FILE_TYPE_REGULAR: string;
192
  
193
  /** File type constant for directories */
194
  FILE_TYPE_DIRECTORY: string;
195
}
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
import firebase from '@react-native-firebase/app';
202
import { Platform } from 'react-native';
203

204
const utils = firebase.utils();
205
const filePaths = utils.FilePath;
206

207
// Cross-platform paths
208
console.log('Documents:', filePaths.DOCUMENT_DIRECTORY);
209
console.log('Cache:', filePaths.CACHES_DIRECTORY);
210
console.log('Temp:', filePaths.TEMP_DIRECTORY);
211

212
// Platform-specific paths
213
if (Platform.OS === 'ios') {
214
  console.log('Main Bundle:', filePaths.MAIN_BUNDLE);
215
} else if (Platform.OS === 'android') {
216
  if (filePaths.EXTERNAL_DIRECTORY) {
217
    console.log('External Storage:', filePaths.EXTERNAL_DIRECTORY);
218
  } else {
219
    console.log('External storage not available');
220
  }
221
}
222

223
// File operations using paths
224
const documentPath = `${filePaths.DOCUMENT_DIRECTORY}/myfile.txt`;
225
const cachePath = `${filePaths.CACHES_DIRECTORY}/cached_data.json`;
226
```
227

228
### Utils Static Properties
229

230
Static utilities and constants available without instantiating the utils module.
231

232
```typescript { .api }
233
/**
234
 * Static utilities available on the utils module
235
 */
236
interface Utils.Statics {
237
  FilePath: Utils.FilePath;
238
}
239

240
// Access via firebase.utils.FilePath (static)
241
import firebase from '@react-native-firebase/app';
242
const staticFilePaths = firebase.utils.FilePath;
243
```
244

245
## Platform Considerations
246

247
### iOS Behavior
248
- `isRunningInTestLab`: Always returns `false`
249
- `playServicesAvailability`: Returns `{ isAvailable: true, status: 0 }`
250
- Google Play Services methods: All return resolved promises with no action
251
- `MAIN_BUNDLE`: Available with path to app bundle
252
- External storage paths: Return `null`
253

254
### Android Behavior  
255
- `isRunningInTestLab`: Returns actual Test Lab detection status
256
- `playServicesAvailability`: Returns real Google Play Services status
257
- Google Play Services methods: Perform actual system interactions
258
- `MAIN_BUNDLE`: Not available (returns `null`)
259
- External storage paths: Return actual paths if available
260

261
### Web/Other Platforms
262
- File paths: Return empty object `{}` (no native file system access)
263
- Google Play Services: Return iOS-style placeholder values
264
- Test Lab detection: Returns `false`
265

266
## Complete Usage Example
267

268
```typescript
269
import firebase from '@react-native-firebase/app';
270
import { Platform } from 'react-native';
271

272
class UtilsManager {
273
  private utils = firebase.utils();
274
  
275
  async initialize() {
276
    // Check Test Lab environment
277
    if (this.utils.isRunningInTestLab) {
278
      console.log('Configuring for Test Lab environment');
279
      // Disable animations, enable test mode, etc.
280
    }
281
    
282
    // Handle Play Services on Android
283
    if (Platform.OS === 'android') {
284
      await this.checkPlayServices();
285
    }
286
    
287
    // Set up file paths
288
    this.setupFilePaths();
289
  }
290
  
291
  private async checkPlayServices() {
292
    const availability = this.utils.playServicesAvailability;
293
    
294
    if (!availability.isAvailable) {
295
      console.warn('Google Play Services not available');
296
      
297
      if (availability.hasResolution) {
298
        try {
299
          await this.utils.makePlayServicesAvailable();
300
          console.log('Play Services made available');
301
        } catch (error) {
302
          console.error('Failed to make Play Services available:', error);
303
        }
304
      }
305
    }
306
  }
307
  
308
  private setupFilePaths() {
309
    const paths = this.utils.FilePath;
310
    
311
    // Configure app-specific paths
312
    this.documentPath = paths.DOCUMENT_DIRECTORY;
313
    this.cachePath = paths.CACHES_DIRECTORY;
314
    this.tempPath = paths.TEMP_DIRECTORY;
315
    
316
    console.log('File paths configured:', {
317
      documents: this.documentPath,
318
      cache: this.cachePath,
319
      temp: this.tempPath
320
    });
321
  }
322
}
323

324
// Usage
325
const utilsManager = new UtilsManager();
326
await utilsManager.initialize();
327
```