# Network Info Module

The `network_info` module automatically collects signals related to the user's network connection type, speed, and quality. It uses the Network Information API when available to provide insights about connection characteristics.

## Collected Signals

The module collects the following signals:

- **`n_online`**: Whether the browser is currently online (boolean: true/false)
- **`n_type`**: Network connection type (wifi, cellular, ethernet, bluetooth, wimax, other, none, unknown, or unsupported)
- **`n_effective_type`**: Effective connection type based on measured performance (slow-2g, 2g, 3g, 4g, unknown, or unsupported)
- **`n_downlink`**: Current downlink speed estimate in Mbps (number or unknown/unsupported)
- **`n_rtt`**: Round-trip time estimate in milliseconds (number or unknown/unsupported)
- **`n_save_data`**: Whether the user has enabled data saver mode (boolean: true/false, unknown, or unsupported)
- **`n_downlink_max`**: Maximum downlink speed for the connection type in Mbps (number or unknown/unsupported)

All signals use the `n_` prefix (network) for consistency and are marked as non-hashed since they represent technical network information, not personally identifiable data.

## Browser Compatibility

The Network Information API is supported in:
- ✅ Chrome/Edge 61+
- ✅ Opera 48+
- ❌ Firefox (behind flag)
- ❌ Safari (not supported)

For browsers that don't support the Network Information API, all signals except `n_online` will return `"unsupported"`.

## Signal Descriptions

### n_online
Always available. Indicates whether the browser is currently online. This is based on the browser's network connectivity status.

**Possible values:** `true`, `false`

### n_type
The type of network connection the device is using. This represents the actual physical connection type.

**Possible values:**
- `wifi` - WiFi connection
- `cellular` - Mobile data connection (2G/3G/4G/5G)
- `ethernet` - Wired Ethernet connection
- `bluetooth` - Bluetooth connection
- `wimax` - WiMAX connection
- `other` - Other connection type
- `none` - No connection
- `unknown` - Connection type unknown
- `unsupported` - API not available

### n_effective_type
The effective connection type based on measured network performance. This is more useful than the actual connection type as it reflects real-world network quality.

**Possible values:**
- `slow-2g` - Very poor connection (~50 kbps)
- `2g` - Poor connection (~250 kbps)
- `3g` - Moderate connection (~700 kbps)
- `4g` - Good connection (≥700 kbps)
- `unknown` - Cannot determine
- `unsupported` - API not available

### n_downlink
Current downlink (download) speed estimate in megabits per second (Mbps). This is a rounded value based on recent network activity.

**Example values:** `10`, `1.5`, `0.5`, `unknown`, `unsupported`

### n_rtt
Round-trip time estimate in milliseconds. This represents the time it takes for a signal to go from the client to the server and back. Lower is better.

**Example values:** `50`, `100`, `250`, `unknown`, `unsupported`

**Interpretation:**
- < 50ms: Excellent
- 50-100ms: Good
- 100-300ms: Fair
- > 300ms: Poor

### n_save_data
Indicates whether the user has enabled data saver mode in their browser. When true, you might want to serve lighter content.

**Possible values:** `true`, `false`, `unknown`, `unsupported`

### n_downlink_max
The maximum theoretical downlink speed for the connection type in Mbps. This is based on the connection technology, not current performance.

**Example values:** `100` (for WiFi), `10` (for 4G), `unknown`, `unsupported`

## Usage

The module is automatically loaded when included in the IdGraph modules configuration:

```typescript
const idGraph = new IdGraph('my-container', {
  modules: ['network_info'], // Include the network_info module
  // ... other options
});
```

Or it's included by default when no modules are specified:

```typescript
const idGraph = new IdGraph('my-container', {
  // network_info is loaded by default along with other modules
});
```

## Privacy Considerations

- **All network signals are NOT hashed** as they represent technical information, not personally identifiable data
- Network information cannot be used to identify individual users
- The data helps optimize content delivery and understand connectivity patterns

## Use Cases

### 1. Adaptive Content Delivery
Use network information to serve appropriate content quality:

```typescript
const signals = idGraph.getSignals();
const effectiveType = signals.find(s => s.name === 'n_effective_type')?.value;

if (effectiveType === 'slow-2g' || effectiveType === '2g') {
  // Serve low-quality images and minimal scripts
} else if (effectiveType === '3g') {
  // Serve medium-quality content
} else {
  // Serve high-quality content
}
```

### 2. Data Saver Mode Detection
Respect user's data saver preference:

```typescript
const signals = idGraph.getSignals();
const saveData = signals.find(s => s.name === 'n_save_data')?.value === 'true';

if (saveData) {
  // Disable auto-playing videos
  // Use compressed images
  // Defer non-essential content
}
```

### 3. Analytics and Monitoring
Track connection quality distribution among users:

```typescript
// Collected signals will show:
// - What percentage of users have poor connections
// - Regional connection quality patterns
// - Impact of connection quality on engagement metrics
```

### 4. Offline Experience
Handle offline scenarios gracefully:

```typescript
const signals = idGraph.getSignals();
const isOnline = signals.find(s => s.name === 'n_online')?.value === 'true';

if (!isOnline) {
  // Show offline message
  // Enable offline mode
  // Queue actions for when connection returns
}
```

## Example Output

When the Network Information API is supported:

```typescript
console.log(idGraph.getSignals());
// Output:
// [
//   { name: "n_online", value: "true", hashed: false },
//   { name: "n_type", value: "wifi", hashed: false },
//   { name: "n_effective_type", value: "4g", hashed: false },
//   { name: "n_downlink", value: "10", hashed: false },
//   { name: "n_rtt", value: "50", hashed: false },
//   { name: "n_save_data", value: "false", hashed: false },
//   { name: "n_downlink_max", value: "100", hashed: false }
// ]
```

When the Network Information API is NOT supported:

```typescript
console.log(idGraph.getSignals());
// Output:
// [
//   { name: "n_online", value: "true", hashed: false },
//   { name: "n_type", value: "unsupported", hashed: false },
//   { name: "n_effective_type", value: "unsupported", hashed: false },
//   { name: "n_downlink", value: "unsupported", hashed: false },
//   { name: "n_rtt", value: "unsupported", hashed: false },
//   { name: "n_save_data", value: "unsupported", hashed: false },
//   { name: "n_downlink_max", value: "unsupported", hashed: false }
// ]
```

## Troubleshooting

### No network data collected (all "unsupported")

**Cause:** The Network Information API is not supported in your browser.

**Solution:** This is expected behavior for browsers like Firefox and Safari. The `n_online` status will still be collected. Consider using feature detection in your application code.

### Values showing as "unknown"

**Cause:** The browser supports the API, but specific properties are not available or cannot be determined.

**Solution:** This is normal when certain network properties cannot be measured. Handle these cases gracefully in your application logic.

### Testing network conditions

Use Chrome DevTools to simulate different network conditions:

1. Open DevTools (F12)
2. Go to Network tab
3. Click the throttling dropdown (usually says "No throttling")
4. Select a network profile (Fast 3G, Slow 3G, Offline, etc.)
5. Reload the page to see different network signals collected

## Debug Mode

Enable debug mode to see network signal collection:

```typescript
const idGraph = new IdGraph('my-container', {
  debug: true,
  modules: ['network_info']
});

// Check console for:
// "Samhub -> IdGraph Module loaded: network_info"
// And all collected signals when flushed
```

## Vendor Prefixes

The module automatically checks for vendor-prefixed versions of the Network Information API:

- `navigator.connection` (standard)
- `navigator.mozConnection` (Firefox)
- `navigator.webkitConnection` (older WebKit browsers)

This ensures maximum compatibility with different browser implementations.