CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-node-gcm

Easy interface for Google's Cloud Messaging service (now Firebase Cloud Messaging)

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

node-gcm

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.

Package Information

  • Package Name: node-gcm
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install node-gcm
  • Node.js Requirements: Node.js 12+

Core Imports

const gcm = require('node-gcm');
const { Sender, Message, Constants } = require('node-gcm');

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

import gcm from 'node-gcm';
import { Sender, Message, Constants } from 'node-gcm';

Basic Usage

const gcm = require('node-gcm');

// Create a message with data payload
const message = new gcm.Message({
    data: { 
        key1: 'message1',
        key2: 'message2' 
    },
    notification: {
        title: 'Hello, World',
        body: 'This is a notification message'
    }
});

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

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

sender.send(message, { registrationTokens: registrationTokens }, function (err, response) {
    if (err) {
        console.error('Error sending message:', err);
    } else {
        console.log('Message sent successfully:', response);
    }
});

Architecture

node-gcm is built around several key components:

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

Capabilities

Message Creation

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

const Message = require('node-gcm').Message;

// Constructor
new Message(options);

// Instance methods
message.addData(key, value);
message.addData(dataObject);
message.addNotification(key, value);  
message.addNotification(notificationObject);
message.toJson();

Message Creation

Message Sending

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

const Sender = require('node-gcm').Sender;

// Constructor
new Sender(apiKey, options);

// Instance methods
sender.send(message, recipient, options, callback);
sender.send(message, recipient, callback);
sender.send(message, recipient, retries, callback);
sender.sendNoRetry(message, recipient, callback);

Message Sending

Constants and Configuration

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

const Constants = require('node-gcm').Constants;

// FCM service endpoints and configuration
Constants.GCM_SEND_URI;
Constants.SOCKET_TIMEOUT;
Constants.BACKOFF_INITIAL_DELAY;
Constants.MAX_BACKOFF_DELAY;

// Error constants
Constants.ERROR_NOT_REGISTERED;
Constants.ERROR_INVALID_REGISTRATION;
// ... additional error constants

Constants and Configuration

Deprecated Classes

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

const { Result, MulitcastResult } = require('node-gcm');

// Note: Export name has intentional typo "MulitcastResult"
const result = new Result();
const multiResult = new MulitcastResult();

Result (Deprecated): Individual message result representation MulitcastResult (Deprecated): Batch message result representation

These classes are deprecated in favor of direct response object handling. See Message Sending for modern response handling patterns.

Types

// Message options interface
interface MessageOptions {
    collapseKey?: string;
    priority?: 'normal' | 'high';
    contentAvailable?: boolean;
    mutableContent?: boolean;
    delayWhileIdle?: boolean;
    timeToLive?: number;
    restrictedPackageName?: string;
    dryRun?: boolean;
    data?: { [key: string]: string };
    notification?: NotificationPayload;
    fcm_options?: { [key: string]: any };
}

// Notification payload interface
interface NotificationPayload {
    title?: string;
    body?: string;
    icon?: string;
    sound?: string;
    badge?: string;
    tag?: string;
    color?: string;
    click_action?: string;
    body_loc_key?: string;
    body_loc_args?: string[];
    title_loc_key?: string;
    title_loc_args?: string[];
}

// Recipient types
type Recipient = string | string[] | RecipientObject;

interface RecipientObject {
    to?: string;
    topic?: string;
    condition?: string;
    notificationKey?: string;
    registrationIds?: string[];  // deprecated
    registrationTokens?: string[];
}

// Response interface
interface FCMResponse {
    multicast_id?: number;
    success: number;
    failure: number;
    canonical_ids: number;
    results: MessageResult[];
}

interface MessageResult {
    message_id?: string;
    registration_id?: string;
    error?: string;
}

// Send options interface
interface SendOptions {
    retries?: number;
    backoff?: number;
}

Install with Tessl CLI

npx tessl i tessl/npm-node-gcm
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/node-gcm@1.1.x
Publish Source
CLI
Badge
tessl/npm-node-gcm badge