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
```