{"id":15038488,"url":"https://github.com/toothlessgear/node-gcm","last_synced_at":"2025-05-12T11:15:22.987Z","repository":{"id":3769844,"uuid":"4846607","full_name":"ToothlessGear/node-gcm","owner":"ToothlessGear","description":"A NodeJS wrapper library port to send data to Android devices via Google Cloud Messaging","archived":false,"fork":false,"pushed_at":"2025-03-24T08:52:14.000Z","size":505,"stargazers_count":1301,"open_issues_count":34,"forks_count":205,"subscribers_count":59,"default_branch":"master","last_synced_at":"2025-05-11T11:03:25.194Z","etag":null,"topics":["android","firebase-cloud-messaging","gcm","javascript","node-gcm","nodejs","notifications","push-notifications"],"latest_commit_sha":null,"homepage":"https://github.com/ToothlessGear/node-gcm","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ToothlessGear.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2012-07-01T00:04:03.000Z","updated_at":"2025-02-18T16:51:52.000Z","dependencies_parsed_at":"2024-09-14T20:46:17.559Z","dependency_job_id":"8dbb3a48-66d7-4ee0-b0a8-9c48a4147f4c","html_url":"https://github.com/ToothlessGear/node-gcm","commit_stats":{"total_commits":487,"total_committers":56,"mean_commits":8.696428571428571,"dds":0.6837782340862423,"last_synced_commit":"44694d57052d70b9bd65e8ae9b8e59a37e1e7f37"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToothlessGear%2Fnode-gcm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToothlessGear%2Fnode-gcm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToothlessGear%2Fnode-gcm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ToothlessGear%2Fnode-gcm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ToothlessGear","download_url":"https://codeload.github.com/ToothlessGear/node-gcm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253554080,"owners_count":21926611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","firebase-cloud-messaging","gcm","javascript","node-gcm","nodejs","notifications","push-notifications"],"created_at":"2024-09-24T20:38:39.777Z","updated_at":"2025-05-11T11:03:44.571Z","avatar_url":"https://github.com/ToothlessGear.png","language":"JavaScript","readme":"# node-gcm\n\n[![Join the chat at https://gitter.im/ToothlessGear/node-gcm](https://badges.gitter.im/ToothlessGear/node-gcm.svg)](https://gitter.im/ToothlessGear/node-gcm?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n[![npm](https://badge.fury.io/js/node-gcm.svg)](https://www.npmjs.com/package/node-gcm)\n\n**Note:** This package will stop working on June 21st, 2024, as it depends on the [Legacy FCM API](https://firebase.google.com/docs/cloud-messaging/migrate-v1). We urge you to migrate to another library that supports the FCM HTTP v1 API before the June 20th deadline, such as:\n1. [firebase-admin](https://www.npmjs.com/package/firebase-admin) (official library)\n2. [fcm-v1-http2](https://www.npmjs.com/package/fcm-v1-http2) (if scale and throughput are important to your sending requirements)\n\n----\n\nThe goal of this project is providing the best and most easily used interface for Firebase Cloud Messaging. (The name `gcm` comes from the older name for the service, Google Cloud Messaging.)\n\n**By April 11, 2019 users must have [migrated from GCM to FCM](https://developers.google.com/cloud-messaging/android/android-migrate-fcm).**\nIf you are using this library, we've already got you covered on the server side (since version 0.14.1) --- just update to the most recent version and you are good.\n\nWe appreciate all the help we can get!\nIf you want to help out, check out the [Guidelines for Contributing](CONTRIBUTING.md) section.\n\nIf you are developing an open-source project with a broader scope (like a full Firebase suite), we would love for you to use node-gcm internally.\n\nSee the [official FCM documentation](https://firebase.google.com/docs/cloud-messaging/) for more information.\n\nWe are currently working on version 2.0.0 of the project, and it is available in an early alpha version.\nFollow [PR #238](https://github.com/ToothlessGear/node-gcm/pull/238) to see current status.\n\n## Installation\n\n```bash\n$ npm install node-gcm --save\n```\n\n**Note:** This package requires Node v12.0 and newer.\n\n## Requirements\n\nThis library provides the server-side implementation of FCM.\nYou need to generate a [Legacy API Server Key](https://console.firebase.google.com/u/0/) (Click the gear next to FCM project name) \u003e Project Settings \u003e Cloud Messaging -\u003e **Cloud Messaging API (Legacy)** -\u003e Click the 3 dots -\u003e Manage API in Google Cloud Console -\u003e **Enable** -\u003e Go back and refresh Firebase Cloud Messaging project settings page to view your **Server key**.\n\nFCM notifications can be sent to both [Android](https://firebase.google.com/docs/cloud-messaging/android/client) and [iOS](https://firebase.google.com/docs/cloud-messaging/ios/client).\nIf you are new to FCM you should probably look into the [documentation](https://firebase.google.com/docs/cloud-messaging).\n\n## Example application\n\nAccording to below **Usage** reference, we could create such application:\n\n```js\nvar gcm = require('node-gcm');\n\n// Set up the sender with your GCM/FCM API key (declare this once for multiple messages)\nvar sender = new gcm.Sender('YOUR_API_KEY_HERE');\n\n// Prepare a message to be sent\nvar message = new gcm.Message({\n    data: { key1: 'msg1' }\n});\n\n// Specify which registration IDs to deliver the message to\nvar regTokens = ['YOUR_REG_TOKEN_HERE'];\n\n// Actually send the message\nsender.send(message, { registrationTokens: regTokens }, function (err, response) {\n\tif (err) console.error(err);\n\telse console.log(response);\n});\n```\n\n## Usage\n\n```js\nvar gcm = require('node-gcm');\n\n// Create a message\n// ... with default values\nvar message = new gcm.Message();\n\n// ... or some given values\nvar message = new gcm.Message({\n\tcollapseKey: 'demo',\n\tpriority: 'high',\n\tcontentAvailable: true,\n\tdelayWhileIdle: true,\n\ttimeToLive: 3,\n\trestrictedPackageName: \"somePackageName\",\n\tdryRun: true,\n\tdata: {\n\t\tkey1: 'message1',\n\t\tkey2: 'message2'\n\t},\n\tnotification: {\n\t\ttitle: \"Hello, World\",\n\t\ticon: \"ic_launcher\",\n\t\tbody: \"This is a notification that will be displayed if your app is in the background.\"\n\t}\n});\n\n// Change the message data\n// ... as key-value\nmessage.addData('key1','message1');\nmessage.addData('key2','message2');\n\n// ... or as a data object (overwrites previous data object)\nmessage.addData({\n\tkey1: 'message1',\n\tkey2: 'message2'\n});\n\n// Set up the sender with you API key\nvar sender = new gcm.Sender('insert Google Server API Key here');\n\n// Add the registration tokens of the devices you want to send to\nvar registrationTokens = [];\nregistrationTokens.push('regToken1');\nregistrationTokens.push('regToken2');\n\n// Send the message\n// ... trying only once\nsender.sendNoRetry(message, { registrationTokens: registrationTokens }, function(err, response) {\n  if(err) console.error(err);\n  else    console.log(response);\n});\n\n// ... or retrying\nsender.send(message, { registrationTokens: registrationTokens }, function (err, response) {\n  if(err) console.error(err);\n  else    console.log(response);\n});\n\n// ... or retrying a specific number of times (10)\nsender.send(message, { registrationTokens: registrationTokens }, 10, function (err, response) {\n  if(err) console.error(err);\n  else    console.log(response);\n});\n\n// Q: I need to remove all expired / unregistered tokens from my database, how do I do that?\n//    The results-array does not contain any tokens!\n// A: The array of tokens used for sending will match the array of results, so you can cross-check them.\nsender.send(message, { registrationTokens: registrationTokens }, function (err, response) {\n  var failed_tokens = registrationTokens.filter((token, i) =\u003e response.results[i].error === 'NotRegistered');\n  console.log('These tokens are no longer registered:', failed_tokens);\n});\n```\n## Recipients\n\nYou can send push notifications to various recipient types by providing one of the following recipient keys:\n\n\n|Key|Type|Description|\n|---|---|---|\n|to|String|A single [registration token](https://firebase.google.com/docs/cloud-messaging/android/client#sample-register), [notification key](https://firebase.google.com/docs/cloud-messaging/android/device-group), or [topic](https://firebase.google.com/docs/cloud-messaging/android/topic-messaging).\n|topic|String|A single publish/subscribe topic.\n|condition|String|Multiple topics using the [condition](https://firebase.google.com/docs/cloud-messaging/topic-messaging) parameter.\n|notificationKey|String|Deprecated. A key that groups multiple registration tokens linked to the same user.\n|registrationIds|String[]|Deprecated. Use registrationTokens instead.|\n|registrationTokens|String[]|A list of registration tokens. Must contain at least 1 and at most 1000 registration tokens.|\n\nIf you provide an incorrect recipient key or object type, an `Error` object will be returned to your callback.\n\nNotice that [you can *at most* send notifications to 1000 registration tokens at a time](https://github.com/ToothlessGear/node-gcm/issues/42).\nThis is due to [a restriction](https://firebase.google.com/docs/cloud-messaging/http-server-ref#downstream-http-messages-json) on the side of the FCM API.\n\n\n### Additional message options\n\n|Parameter|Usage|Description|\n|---|---|---|\n|collapseKey|Optional, string|This parameter identifies a group of messages that can be collapsed, so that only the last message gets sent when delivery can be resumed.|\n|priority|Optional, string|Sets the priority of the message. Valid values are \"normal\" and \"high.\"|\n|contentAvailable|Optional, JSON boolean|On iOS, when a notification or message is sent and this is set to true, an inactive client app is awoken.|\n|mutableContent|Optional, JSON boolean|On iOS, Currently for iOS 10+ devices only. On iOS, use this field to represent mutable-content in the APNs payload. When a notification is sent and this is set to true, the content of the notification can be modified before it is displayed, using a Notification Service app extension.|\n|timeToLive|Optional, JSON number|This parameter specifies how long (in seconds) the message should be kept in FCM storage if the device is offline. The maximum time to live supported is 4 weeks, and the default value is 4 weeks.|\n|restrictedPackageName|Optional, string|This parameter specifies the package name of the application where the registration tokens must match in order to receive the message.|\n|dryRun|Optional, JSON boolean|This parameter, when set to true, allows developers to test a request without actually sending a message.|\n|data|Optional, JSON object|This parameter specifies the custom key-value pairs of the message's payload.|\n|notification|Optional, JSON object|This parameter specifies the predefined, user-visible key-value pairs of the notification payload. See \"Notification payload option table\" below for more details.|\n|fcm_options|Optional, JSON object|This parameter is used to pass FCM specific options, as outlined [here](https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages#FcmOptions).\n\n## Notification usage\n\n```js\n\nvar message = new gcm.Message();\n\n// Add notification payload as key value\nmessage.addNotification('title', 'Alert!!!');\nmessage.addNotification('body', 'Abnormal data access');\nmessage.addNotification('icon', 'ic_launcher');\n\n// as object\nmessage.addNotification({\n  title: 'Alert!!!',\n  body: 'Abnormal data access',\n  icon: 'ic_launcher'\n});\n\n```\n\n**Note:** Notifications sent using `message.addNotification` are only displayed when your app is in the background. Consider sending the notification parameters using `message.addData` and manually building and displaying a notification in your push receiver logic.\n\n### Notification payload option table\n\n|Parameter|Platform|Usage|Description|\n|---|---|---|---|\n|title|Android, iOS (Watch)|Required (Android), Optional (iOS), string|Indicates notification title. This field is not visible on iOS phones and tablets.|\n|body|Android, iOS|Optional, string|Indicates notification body text.|\n|icon|Android|Required, string|Indicates notification icon. On Android: sets value to myicon for drawable resource myicon.png.|\n|sound|Android, iOS|Optional, string|Indicates sound to be played. Supports only default currently.|\n|badge|iOS|Optional, string|Indicates the badge on client app home icon.|\n|tag|Android|Optional, string|Indicates whether each notification message results in a new entry on the notification center on Android. If not set, each request creates a new notification. If set, and a notification with the same tag is already being shown, the new notification replaces the existing one in notification center.|\n|color|Android|Optional, string|Indicates color of the icon, expressed in #rrggbb format|\n|click_action|Android, iOS|Optional, string|The action associated with a user click on the notification. On Android, if this is set, an activity with a matching intent filter is launched when user clicks the notification. For example, if one of your Activities includes the intent filter: (Appendix:1)Set click_action to OPEN_ACTIVITY_1 to open it. If set, corresponds to category in APNS payload.|\n|body_loc_key|iOS|Optional, string|Indicates the key to the body string for localization. On iOS, this corresponds to \"loc-key\" in APNS payload.|\n|body_loc_args|iOS|Optional, JSON array as string|Indicates the string value to replace format specifiers in body string for localization. On iOS, this corresponds to \"loc-args\" in APNS payload.|\n|title_loc_args|iOS|Optional, JSON array as string|Indicates the string value to replace format specifiers in title string for localization. On iOS, this corresponds to \"title-loc-args\" in APNS payload.|\n|title_loc_key|iOS|Optional, string|Indicates the key to the title string for localization. On iOS, this corresponds to \"title-loc-key\" in APNS payload.|\n\nNotice notification payload defined in [FCM Connection Server Reference](https://firebase.google.com/docs/cloud-messaging/http-server-ref#downstream-http-messages-json)\n\n## Custom HTTP request options\n\nYou can provide custom `request` options such as `proxy` and `timeout` for the HTTP request to the FCM API. For more information, refer to [the complete list of request options](https://github.com/request/request#requestoptions-callback). Note that the following options cannot be overriden: `method`, `uri`, `body`, as well as the following headers: `Authorization`, `Content-Type`, and `Content-Length`.\n\n```js\n// Set custom request options\nvar requestOptions = {\n\tproxy: 'http://127.0.0.1:8888',\n\ttimeout: 5000\n};\n\n// Set up the sender with your API key and request options\nvar sender = new gcm.Sender('YOUR_API_KEY_HERE', requestOptions);\n\n// Prepare a GCM message...\n\n// Send it to GCM endpoint with modified request options\nsender.send(message, { registrationTokens: regTokens }, function (err, response) {\n    if(err) console.error(err);\n    else     console.log(response);\n});\n```\n\n## FCM client compatibility\n\nAs of January 9th, 2016, there are a few known compatibility issues with 3rd-party FCM client libraries:\n\n### phonegap-plugin-push\n\n* [No support for subscribing to PubSub topics](https://github.com/phonegap/phonegap-plugin-push/issues/79)\n* [Requirement for `data` payload object when sending a `notification` object](https://github.com/phonegap/phonegap-plugin-push/issues/387)\n* [Requirement for all 3 `notification` fields when sending a `notification` object (title, icon, message)](https://github.com/ToothlessGear/node-gcm/issues/180)\n\nThese issues are out of this project's context and can only be fixed by the respective 3rd-party project maintainers.\n\n## Debug\n\nTo enable debug mode (print requests and responses to and from FCM),\nset the `DEBUG` environment flag when running your app (assuming you use `node app.js` to run your app):\n\n```bash\nDEBUG=node-gcm node app.js\n```\n\n## Donate\n\n Bitcoin: [13iTQf7tDhrKgibw2Y3U5SyPJa7R8sQmHQ](https://blockchain.info/address/13iTQf7tDhrKgibw2Y3U5SyPJa7R8sQmHQ)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoothlessgear%2Fnode-gcm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftoothlessgear%2Fnode-gcm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftoothlessgear%2Fnode-gcm/lists"}