0
# Configuration
1

2
Configuration system for customizing network reachability testing, including custom endpoints, timeout settings, and platform-specific options.
3

4
## Capabilities
5

6
### NetInfo Configuration
7

8
The main configuration interface for customizing how network reachability is tested and network information is gathered.
9

10
```typescript { .api }
11
interface NetInfoConfiguration {
12
  /** The URL to call to test if the internet is reachable */
13
  reachabilityUrl: string;
14
  /** The HTTP request method to use for reachability testing */
15
  reachabilityMethod?: NetInfoMethodType;
16
  /** HTTP headers to include in reachability requests */
17
  reachabilityHeaders?: Record<string, string>;
18
  /** Function to determine if reachability response indicates internet access */
19
  reachabilityTest: (response: Response) => Promise<boolean>;
20
  /** Timeout between reachability checks when internet was previously detected */
21
  reachabilityLongTimeout: number;
22
  /** Timeout between reachability checks when internet was not previously detected */
23
  reachabilityShortTimeout: number;
24
  /** Maximum time allowed for a single reachability check */
25
  reachabilityRequestTimeout: number;
26
  /** Function to determine if reachability checks should run */
27
  reachabilityShouldRun: () => boolean;
28
  /** Whether to attempt fetching WiFi SSID on supported platforms */
29
  shouldFetchWiFiSSID: boolean;
30
  /** Whether to use native platform reachability checks when available */
31
  useNativeReachability: boolean;
32
}
33

34
type NetInfoMethodType = 'HEAD' | 'GET';
35
```
36

37
### Default Configuration Values
38

39
Default configuration varies by platform to optimize for each environment.
40

41
**Standard Platforms (iOS, Android, macOS, Windows):**
42

43
```typescript
44
const DEFAULT_CONFIGURATION = {
45
  reachabilityUrl: 'https://clients3.google.com/generate_204',
46
  reachabilityMethod: 'HEAD',
47
  reachabilityHeaders: {},
48
  reachabilityTest: (response: Response) => Promise.resolve(response.status === 204),
49
  reachabilityShortTimeout: 5 * 1000, // 5 seconds
50
  reachabilityLongTimeout: 60 * 1000, // 60 seconds
51
  reachabilityRequestTimeout: 15 * 1000, // 15 seconds
52
  reachabilityShouldRun: () => true,
53
  shouldFetchWiFiSSID: false,
54
  useNativeReachability: true
55
};
56
```
57

58
**Web Platform:**
59

60
```typescript
61
const DEFAULT_WEB_CONFIGURATION = {
62
  reachabilityUrl: '/',
63
  reachabilityMethod: 'HEAD',
64
  reachabilityHeaders: {},
65
  reachabilityTest: (response: Response) => Promise.resolve(response.status === 200),
66
  reachabilityShortTimeout: 5 * 1000, // 5 seconds
67
  reachabilityLongTimeout: 60 * 1000, // 60 seconds
68
  reachabilityRequestTimeout: 15 * 1000, // 15 seconds
69
  reachabilityShouldRun: () => true,
70
  shouldFetchWiFiSSID: true,
71
  useNativeReachability: true
72
};
73
```
74

75
## Configuration Examples
76

77
### Basic Reachability Customization
78

79
```typescript
80
import { configure } from "@react-native-community/netinfo";
81

82
// Use custom reachability endpoint
83
configure({
84
  reachabilityUrl: 'https://www.google.com/generate_204',
85
  reachabilityTest: async (response) => response.status === 204,
86
});
87

88
// Use different endpoint with GET method
89
configure({
90
  reachabilityUrl: 'https://httpbin.org/status/200',
91
  reachabilityMethod: 'GET',
92
  reachabilityTest: async (response) => response.status === 200,
93
});
94
```
95

96
### Custom Headers and Authentication
97

98
```typescript
99
configure({
100
  reachabilityUrl: 'https://api.company.com/health',
101
  reachabilityHeaders: {
102
    'Authorization': 'Bearer token123',
103
    'X-API-Key': 'api-key-456',
104
    'User-Agent': 'MyApp/1.0.0',
105
  },
106
  reachabilityTest: async (response) => {
107
    const data = await response.json();
108
    return data.status === 'healthy';
109
  },
110
});
111
```
112

113
### Timeout Configuration
114

115
```typescript
116
configure({
117
  // Check every 30 seconds when connected
118
  reachabilityLongTimeout: 30 * 1000,
119
  
120
  // Check every 2 seconds when disconnected  
121
  reachabilityShortTimeout: 2 * 1000,
122
  
123
  // Allow 10 seconds per request
124
  reachabilityRequestTimeout: 10 * 1000,
125
});
126
```
127

128
### Conditional Reachability Testing
129

130
```typescript
131
configure({
132
  // Only run reachability checks during business hours
133
  reachabilityShouldRun: () => {
134
    const hour = new Date().getHours();
135
    return hour >= 9 && hour <= 17;
136
  },
137
});
138

139
// Or based on app state
140
configure({
141
  reachabilityShouldRun: () => {
142
    // Only test when app is in foreground
143
    return AppState.currentState === 'active';
144
  },
145
});
146
```
147

148
### Platform-Specific Configuration
149

150
```typescript
151
import { Platform } from 'react-native';
152

153
configure({
154
  // Different endpoints per platform
155
  reachabilityUrl: Platform.select({
156
    ios: 'https://captive.apple.com/hotspot-detect.html',
157
    android: 'https://clients3.google.com/generate_204',
158
    default: 'https://www.google.com/generate_204',
159
  }),
160
  
161
  // Enable WiFi SSID fetching on iOS (requires meeting Apple's requirements)
162
  shouldFetchWiFiSSID: Platform.OS === 'ios',
163
  
164
  // Use native reachability when available
165
  useNativeReachability: Platform.OS !== 'web',
166
});
167
```
168

169
### Complex Reachability Testing
170

171
```typescript
172
configure({
173
  reachabilityUrl: 'https://api.example.com/connectivity',
174
  reachabilityMethod: 'GET',
175
  reachabilityHeaders: {
176
    'Accept': 'application/json',
177
  },
178
  reachabilityTest: async (response) => {
179
    try {
180
      // Custom logic for determining connectivity
181
      if (response.status !== 200) {
182
        return false;
183
      }
184
      
185
      const data = await response.json();
186
      
187
      // Check if API is responsive and not in maintenance
188
      return data.status === 'ok' && !data.maintenance;
189
    } catch (error) {
190
      // JSON parsing failed, assume no connectivity
191
      return false;
192
    }
193
  },
194
});
195
```
196

197
### Disabling Features
198

199
```typescript
200
configure({
201
  // Disable automatic reachability testing
202
  reachabilityShouldRun: () => false,
203
  
204
  // Don't attempt to fetch WiFi SSID
205
  shouldFetchWiFiSSID: false,
206
  
207
  // Force use of custom reachability instead of native
208
  useNativeReachability: false,
209
});
210
```
211

212
## Configuration Notes
213

214
### iOS WiFi SSID Requirements
215

216
To fetch WiFi SSID on iOS, your app must meet at least one of Apple's requirements and set `shouldFetchWiFiSSID: true`:
217

218
- Use Core Location and have location permission
219
- Have valid WiFi Assist entitlement  
220
- Use NEHotspotHelper with proper entitlements
221

222
Setting `shouldFetchWiFiSSID: true` without meeting requirements will cause memory leaks.
223

224
### Android Permissions
225

226
For WiFi details (SSID, BSSID) on Android, you need:
227

228
- `ACCESS_FINE_LOCATION` permission in AndroidManifest.xml
229
- Runtime location permission granted by user
230

231
### Platform Availability
232

233
| Feature | iOS | Android | macOS | Windows | Web |
234
|---------|-----|---------|-------|---------|-----|
235
| Basic connectivity | ✅ | ✅ | ✅ | ✅ | ✅ |
236
| WiFi SSID | ✅* | ✅* | ✅ | ✅ | ❌ |
237
| Cellular generation | ✅ | ✅ | ❌ | ✅ | ❌ |
238
| Connection cost | ✅ | ✅ | ✅ | ✅ | ✅ |
239
| Native reachability | ✅ | ✅ | ✅ | ✅ | ❌ |
240
241
*Requires permissions/configuration