0
# node-gcm
1

2
node-gcm provides an easy-to-use interface for Firebase Cloud Messaging (FCM), formerly Google Cloud Messaging (GCM). It enables server-side Node.js applications to send push notifications to Android and iOS devices with comprehensive error handling, automatic retries, and support for various message types.
3

4
## Package Information
5

6
- **Package Name**: node-gcm
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install node-gcm`
10
- **Node.js Requirements**: Node.js 12+
11

12
## Core Imports
13

14
```javascript
15
const gcm = require('node-gcm');
16
const { Sender, Message, Constants } = require('node-gcm');
17
```
18

19
ES Modules (if using Node.js with ES modules enabled):
20

21
```javascript
22
import gcm from 'node-gcm';
23
import { Sender, Message, Constants } from 'node-gcm';
24
```
25

26
## Basic Usage
27

28
```javascript
29
const gcm = require('node-gcm');
30

31
// Create a message with data payload
32
const message = new gcm.Message({
33
    data: { 
34
        key1: 'message1',
35
        key2: 'message2' 
36
    },
37
    notification: {
38
        title: 'Hello, World',
39
        body: 'This is a notification message'
40
    }
41
});
42

43
// Set up the sender with your FCM API key
44
const sender = new gcm.Sender('YOUR_FCM_SERVER_KEY');
45

46
// Send to registration tokens
47
const registrationTokens = ['token1', 'token2'];
48

49
sender.send(message, { registrationTokens: registrationTokens }, function (err, response) {
50
    if (err) {
51
        console.error('Error sending message:', err);
52
    } else {
53
        console.log('Message sent successfully:', response);
54
    }
55
});
56
```
57

58
## Architecture
59

60
node-gcm is built around several key components:
61

62
- **Message**: Creates and manages push notification messages with data and notification payloads
63
- **Sender**: Handles authentication and message delivery to FCM with automatic retry logic
64
- **Constants**: Provides FCM endpoint configurations and error codes
65
- **Response Handling**: Structured response parsing for delivery confirmation and error handling
66
- **Retry Mechanism**: Automatic retry with exponential backoff for failed deliveries
67

68
## Capabilities
69

70
### Message Creation
71

72
Core functionality for creating push notification messages with data payloads, notification content, and delivery options.
73

74
```javascript { .api }
75
const Message = require('node-gcm').Message;
76

77
// Constructor
78
new Message(options);
79

80
// Instance methods
81
message.addData(key, value);
82
message.addData(dataObject);
83
message.addNotification(key, value);  
84
message.addNotification(notificationObject);
85
message.toJson();
86
```
87

88
[Message Creation](./message.md)
89

90
### Message Sending
91

92
Message delivery system with FCM authentication, automatic retries, and comprehensive error handling for reliable push notification delivery.
93

94
```javascript { .api }
95
const Sender = require('node-gcm').Sender;
96

97
// Constructor
98
new Sender(apiKey, options);
99

100
// Instance methods
101
sender.send(message, recipient, options, callback);
102
sender.send(message, recipient, callback);
103
sender.send(message, recipient, retries, callback);
104
sender.sendNoRetry(message, recipient, callback);
105
```
106

107
[Message Sending](./sender.md)
108

109
### Constants and Configuration
110

111
Configuration constants for FCM endpoints, timeouts, and error handling.
112

113
```javascript { .api }
114
const Constants = require('node-gcm').Constants;
115

116
// FCM service endpoints and configuration
117
Constants.GCM_SEND_URI;
118
Constants.SOCKET_TIMEOUT;
119
Constants.BACKOFF_INITIAL_DELAY;
120
Constants.MAX_BACKOFF_DELAY;
121

122
// Error constants
123
Constants.ERROR_NOT_REGISTERED;
124
Constants.ERROR_INVALID_REGISTRATION;
125
// ... additional error constants
126
```
127

128
[Constants and Configuration](./constants.md)
129

130
### Deprecated Classes
131

132
Legacy classes maintained for backward compatibility (not recommended for new code).
133

134
```javascript { .api }
135
const { Result, MulitcastResult } = require('node-gcm');
136

137
// Note: Export name has intentional typo "MulitcastResult"
138
const result = new Result();
139
const multiResult = new MulitcastResult();
140
```
141

142
**Result (Deprecated)**: Individual message result representation
143
**MulitcastResult (Deprecated)**: Batch message result representation  
144

145
These classes are deprecated in favor of direct response object handling. See [Message Sending](./sender.md) for modern response handling patterns.
146

147
## Types
148

149
```javascript { .api }
150
// Message options interface
151
interface MessageOptions {
152
    collapseKey?: string;
153
    priority?: 'normal' | 'high';
154
    contentAvailable?: boolean;
155
    mutableContent?: boolean;
156
    delayWhileIdle?: boolean;
157
    timeToLive?: number;
158
    restrictedPackageName?: string;
159
    dryRun?: boolean;
160
    data?: { [key: string]: string };
161
    notification?: NotificationPayload;
162
    fcm_options?: { [key: string]: any };
163
}
164

165
// Notification payload interface
166
interface NotificationPayload {
167
    title?: string;
168
    body?: string;
169
    icon?: string;
170
    sound?: string;
171
    badge?: string;
172
    tag?: string;
173
    color?: string;
174
    click_action?: string;
175
    body_loc_key?: string;
176
    body_loc_args?: string[];
177
    title_loc_key?: string;
178
    title_loc_args?: string[];
179
}
180

181
// Recipient types
182
type Recipient = string | string[] | RecipientObject;
183

184
interface RecipientObject {
185
    to?: string;
186
    topic?: string;
187
    condition?: string;
188
    notificationKey?: string;
189
    registrationIds?: string[];  // deprecated
190
    registrationTokens?: string[];
191
}
192

193
// Response interface
194
interface FCMResponse {
195
    multicast_id?: number;
196
    success: number;
197
    failure: number;
198
    canonical_ids: number;
199
    results: MessageResult[];
200
}
201

202
interface MessageResult {
203
    message_id?: string;
204
    registration_id?: string;
205
    error?: string;
206
}
207

208
// Send options interface
209
interface SendOptions {
210
    retries?: number;
211
    backoff?: number;
212
}
213
```