0
# Constants and Configuration
1

2
Configuration constants for FCM endpoints, timeouts, and error handling. These constants are used internally by the library but can be referenced for debugging and configuration purposes.
3

4
## Capabilities
5

6
### FCM Service Configuration
7

8
Core FCM service endpoints and connection settings.
9

10
```javascript { .api }
11
const Constants = require('node-gcm').Constants;
12

13
/** FCM service endpoint hostname */
14
Constants.GCM_SEND_ENDPOINT; // 'fcm.googleapis.com'
15

16
/** FCM service endpoint path */
17
Constants.GCM_SEND_ENDPATH; // '/fcm/send'
18

19
/** Complete FCM service URL */
20
Constants.GCM_SEND_URI; // 'https://fcm.googleapis.com/fcm/send'
21
```
22

23
### Timeout and Retry Configuration
24

25
Network timeout and retry behavior settings.
26

27
```javascript { .api }
28
/** Socket timeout in milliseconds (3 minutes) */
29
Constants.SOCKET_TIMEOUT; // 180000
30

31
/** Initial delay for retry backoff in milliseconds */
32
Constants.BACKOFF_INITIAL_DELAY; // 1000
33

34
/** Maximum backoff delay in milliseconds */
35
Constants.MAX_BACKOFF_DELAY; // 1024000
36
```
37

38
**Usage Example:**
39

40
```javascript
41
const gcm = require('node-gcm');
42

43
// Create sender with custom timeout based on constants
44
const sender = new gcm.Sender('YOUR_API_KEY', {
45
    timeout: gcm.Constants.SOCKET_TIMEOUT / 2  // Half the default timeout
46
});
47

48
// Use constants for custom retry logic
49
const customBackoff = gcm.Constants.BACKOFF_INITIAL_DELAY * 2;
50
```
51

52
### Error Constants
53

54
FCM error codes for response handling and debugging.
55

56
```javascript { .api }
57
/** Quota exceeded for sender */
58
Constants.ERROR_QUOTA_EXCEEDED; // 'QuotaExceeded'
59

60
/** Device quota exceeded */
61
Constants.ERROR_DEVICE_QUOTA_EXCEEDED; // 'DeviceQuotaExceeded'
62

63
/** Registration token missing from request */
64
Constants.ERROR_MISSING_REGISTRATION; // 'MissingRegistration'
65

66
/** Invalid registration token format */
67
Constants.ERROR_INVALID_REGISTRATION; // 'InvalidRegistration'
68

69
/** Registration token doesn't match sender ID */
70
Constants.ERROR_MISMATCH_SENDER_ID; // 'MismatchSenderId'
71

72
/** Registration token is no longer valid */
73
Constants.ERROR_NOT_REGISTERED; // 'NotRegistered'
74

75
/** Message payload exceeds size limit */
76
Constants.ERROR_MESSAGE_TOO_BIG; // 'MessageTooBig'
77

78
/** Collapse key missing for required message type */
79
Constants.ERROR_MISSING_COLLAPSE_KEY; // 'MissingCollapseKey'
80

81
/** FCM service temporarily unavailable */
82
Constants.ERROR_UNAVAILABLE; // 'Unavailable'
83

84
/** FCM internal server error */
85
Constants.ERROR_INTERNAL_SERVER_ERROR; // 'InternalServerError'
86
```
87

88
**Usage Example:**
89

90
```javascript
91
const gcm = require('node-gcm');
92

93
sender.send(message, recipients, function(err, response) {
94
    if (response && response.results) {
95
        response.results.forEach((result, index) => {
96
            if (result.error) {
97
                switch (result.error) {
98
                    case gcm.Constants.ERROR_NOT_REGISTERED:
99
                        console.log(`Token ${index} is no longer registered`);
100
                        // Remove token from database
101
                        break;
102
                        
103
                    case gcm.Constants.ERROR_INVALID_REGISTRATION:
104
                        console.log(`Token ${index} has invalid format`);
105
                        // Remove invalid token
106
                        break;
107
                        
108
                    case gcm.Constants.ERROR_MESSAGE_TOO_BIG:
109
                        console.log('Message payload too large');
110
                        // Reduce message size
111
                        break;
112
                        
113
                    case gcm.Constants.ERROR_QUOTA_EXCEEDED:
114
                        console.log('Sending quota exceeded');
115
                        // Implement rate limiting
116
                        break;
117
                        
118
                    default:
119
                        console.log(`Unknown error: ${result.error}`);
120
                }
121
            }
122
        });
123
    }
124
});
125
```
126

127
### Deprecated Constants (Legacy Support)
128

129
These constants are marked as deprecated but still available for backward compatibility.
130

131
```javascript { .api }
132
// JSON field names - used internally for response parsing
133
Constants.TOKEN_MESSAGE_ID; // 'id'
134
Constants.TOKEN_CANONICAL_REG_ID; // 'registration_id' 
135
Constants.TOKEN_ERROR; // 'Error'
136
Constants.JSON_REGISTRATION_IDS; // 'registration_ids'
137
Constants.JSON_PAYLOAD; // 'data'
138
Constants.JSON_NOTIFICATION; // 'notification'
139
Constants.JSON_SUCCESS; // 'success'
140
Constants.JSON_FAILURE; // 'failure'
141
Constants.JSON_CANONICAL_IDS; // 'canonical_ids'
142
Constants.JSON_MULTICAST_ID; // 'multicast_id'
143
Constants.JSON_RESULTS; // 'results'
144
Constants.JSON_ERROR; // 'error'
145
Constants.JSON_MESSAGE_ID; // 'message_id'
146
Constants.UTF8; // 'UTF-8'
147
```
148

149
## Constant Categories
150

151
### Network Configuration
152
- `GCM_SEND_ENDPOINT` - FCM hostname
153
- `GCM_SEND_ENDPATH` - FCM API path  
154
- `GCM_SEND_URI` - Complete FCM URL
155
- `SOCKET_TIMEOUT` - Request timeout
156

157
### Retry Configuration  
158
- `BACKOFF_INITIAL_DELAY` - Initial retry delay
159
- `MAX_BACKOFF_DELAY` - Maximum retry delay
160

161
### Error Handling
162
- `ERROR_*` constants - FCM error code strings
163
- Used for response error matching and handling
164

165
### Internal Protocol (Deprecated)
166
- `TOKEN_*` and `JSON_*` constants - Response field names
167
- Used internally for JSON parsing
168
- Should not be used in application code
169

170
## Usage Patterns
171

172
### Error Handling with Constants
173

174
```javascript
175
const { Sender, Message, Constants } = require('node-gcm');
176

177
function handleSendResponse(response, originalTokens) {
178
    const tokensToRemove = [];
179
    const tokensToUpdate = [];
180
    
181
    response.results.forEach((result, index) => {
182
        const token = originalTokens[index];
183
        
184
        if (result.error) {
185
            switch (result.error) {
186
                case Constants.ERROR_NOT_REGISTERED:
187
                case Constants.ERROR_INVALID_REGISTRATION:
188
                    tokensToRemove.push(token);
189
                    break;
190
                    
191
                case Constants.ERROR_UNAVAILABLE:
192
                case Constants.ERROR_INTERNAL_SERVER_ERROR:
193
                    // These are retried automatically by the library
194
                    console.log(`Temporary error for token ${token}`);
195
                    break;
196
            }
197
        } else if (result.registration_id) {
198
            tokensToUpdate.push({
199
                oldToken: token,
200
                newToken: result.registration_id
201
            });
202
        }
203
    });
204
    
205
    return { tokensToRemove, tokensToUpdate };
206
}
207
```
208

209
### Custom Timeout Configuration
210

211
```javascript
212
const sender = new Sender('YOUR_API_KEY', {
213
    // Use half the default socket timeout
214
    timeout: Constants.SOCKET_TIMEOUT / 2,
215
    
216
    // Custom retry configuration
217
    retries: 3,
218
    backoff: Constants.BACKOFF_INITIAL_DELAY * 1.5
219
});
220
```
221

222
## Important Notes
223

224
- **Internal Usage**: Most constants are used internally by the library
225
- **Error Matching**: Use error constants for reliable error handling instead of hardcoded strings
226
- **Deprecated Constants**: Avoid using deprecated `TOKEN_*` and `JSON_*` constants in new code
227
- **Timeout Values**: All timeout values are in milliseconds
228
- **Backoff Strategy**: Retry delays use exponential backoff between `BACKOFF_INITIAL_DELAY` and `MAX_BACKOFF_DELAY`
229
- **FCM Compatibility**: Constants reflect current FCM API specifications