{"id":31910261,"url":"https://github.com/decision-labs/fcm","last_synced_at":"2025-10-13T16:20:53.078Z","repository":{"id":40307636,"uuid":"59186261","full_name":"decision-labs/fcm","owner":"decision-labs","description":"Ruby bindings to Firebase Cloud Messaging (FCM) for Android, iOS or Web","archived":false,"fork":false,"pushed_at":"2024-10-22T00:04:58.000Z","size":116,"stargazers_count":533,"open_issues_count":18,"forks_count":157,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-10-07T17:25:36.027Z","etag":null,"topics":["fcm","firebase-cloud-messaging","ruby"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/decision-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2016-05-19T08:02:46.000Z","updated_at":"2025-09-11T02:57:06.000Z","dependencies_parsed_at":"2022-08-09T16:52:55.599Z","dependency_job_id":"1e2f9c25-b8ec-4641-bc81-4407ce8c6ebb","html_url":"https://github.com/decision-labs/fcm","commit_stats":{"total_commits":80,"total_committers":37,"mean_commits":"2.1621621621621623","dds":0.75,"last_synced_commit":"40eb6efa191e5d092ad40fe81da81a4c1cbf39fe"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/decision-labs/fcm","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decision-labs%2Ffcm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decision-labs%2Ffcm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decision-labs%2Ffcm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decision-labs%2Ffcm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/decision-labs","download_url":"https://codeload.github.com/decision-labs/fcm/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/decision-labs%2Ffcm/sbom","scorecard":{"id":331455,"data":{"date":"2025-08-11","repo":{"name":"github.com/decision-labs/fcm","commit":"ec489fa22dd11185d487f781c009bca782144d17"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.7,"checks":[{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Code-Review","score":6,"reason":"Found 4/6 approved changesets -- score normalized to 6","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/ci.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/ci.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/decision-labs/fcm/ci.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/ci.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/decision-labs/fcm/ci.yml/master?enable=pin","Info:   0 out of   1 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE.txt:0","Info: FSF or OSI recognized license: MIT License: LICENSE.txt:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":0,"reason":"Project has not signed or included provenance with any releases.","details":["Warn: release artifact v1.0.6 not signed: https://api.github.com/repos/decision-labs/fcm/releases/54108408","Warn: release artifact v1.0.3 not signed: https://api.github.com/repos/decision-labs/fcm/releases/44062235","Warn: release artifact v1.0.6 does not have provenance: https://api.github.com/repos/decision-labs/fcm/releases/54108408","Warn: release artifact v1.0.3 does not have provenance: https://api.github.com/repos/decision-labs/fcm/releases/44062235"],"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T03:45:12.439Z","repository_id":40307636,"created_at":"2025-08-18T03:45:12.439Z","updated_at":"2025-08-18T03:45:12.439Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279011452,"owners_count":26084947,"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","status":"online","status_checked_at":"2025-10-12T02:00:06.719Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["fcm","firebase-cloud-messaging","ruby"],"created_at":"2025-10-13T16:20:51.083Z","updated_at":"2025-10-13T16:20:53.070Z","avatar_url":"https://github.com/decision-labs.png","language":"Ruby","readme":"# Firebase Cloud Messaging (FCM) for Android and iOS\n\n[![Gem Version](https://badge.fury.io/rb/fcm.svg)](http://badge.fury.io/rb/fcm) [![Build Status](https://github.com/decision-labs/fcm/workflows/Tests/badge.svg)](https://github.com/decision-labs/fcm/actions)\n\nThe FCM gem lets your ruby backend send notifications to Android and iOS devices via [\nFirebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging/).\n\n## Installation\n\n    $ gem install fcm\n\nor in your `Gemfile` just include it:\n\n```ruby\ngem 'fcm'\n```\n\n## Requirements\n\nFor Android you will need a device running 2.3 (or newer) that also have the Google Play Store app installed, or an emulator running Android 2.3 with Google APIs. iOS devices are also supported.\n\nA version of supported Ruby, currently:\n`ruby \u003e= 2.4`\n\n## Getting Started\nTo use this gem, you need to instantiate a client with your firebase credentials:\n\n```ruby\nfcm = FCM.new(\n  GOOGLE_APPLICATION_CREDENTIALS_PATH,\n  FIREBASE_PROJECT_ID\n)\n```\n\n## About the `GOOGLE_APPLICATION_CREDENTIALS_PATH`\nThe `GOOGLE_APPLICATION_CREDENTIALS_PATH` is meant to contain your firebase credentials.\n\nThe easiest way to provide them is to pass here an absolute path to a file with your credentials:\n\n```ruby\nfcm = FCM.new(\n  '/path/to/credentials.json',\n  FIREBASE_PROJECT_ID\n)\n```\n\nAs per their secret nature, you might not want to have them in your repository. In that case, another supported solution is to pass a `StringIO` that contains your credentials:\n\n```ruby\nfcm = FCM.new(\n  StringIO.new(ENV.fetch('FIREBASE_CREDENTIALS')),\n  FIREBASE_PROJECT_ID\n)\n\n```\n\n## Usage\n\n## HTTP v1 API\n\nTo migrate to HTTP v1 see: https://firebase.google.com/docs/cloud-messaging/migrate-v1\n\n```ruby\nfcm = FCM.new(\n  GOOGLE_APPLICATION_CREDENTIALS_PATH,\n  FIREBASE_PROJECT_ID\n)\nmessage = {\n  'token': \"000iddqd\", # send to a specific device\n  # 'topic': \"yourTopic\",\n  # 'condition': \"'TopicA' in topics \u0026\u0026 ('TopicB' in topics || 'TopicC' in topics)\",\n  'data': {\n    payload: {\n      data: {\n        id: 1\n      }\n    }.to_json\n  },\n  'notification': {\n    title: notification.title_th,\n    body: notification.body_th,\n  },\n  'android': {},\n  'apns': {\n    payload: {\n      aps: {\n        sound: \"default\",\n        category: \"#{Time.zone.now.to_i}\"\n      }\n    }\n  },\n  'fcm_options': {\n    analytics_label: 'Label'\n  }\n}\n\nfcm.send_v1(message) # or fcm.send_notification_v1(message)\n```\n\n## Device Group Messaging\n\nWith [device group messaging](https://firebase.google.com/docs/cloud-messaging/notifications), you can send a single message to multiple instance of an app running on devices belonging to a group. Typically, \"group\" refers a set of different devices that belong to a single user. However, a group could also represent a set of devices where the app instance functions in a highly correlated manner. To use this feature, you will first need an initialised `FCM` class.\n\nThe maximum number of members allowed for a notification key is 20.\nhttps://firebase.google.com/docs/cloud-messaging/android/device-group#managing_device_groups\n\n### Generate a Notification Key for device group\n\nThen you will need a notification key which you can create for a particular `key_name` which needs to be uniquely named per app in case you have multiple apps for the same `project_id`. This ensures that notifications only go to the intended target app. The `create` method will do this and return the token `notification_key`, that represents the device group, in the response:\n\n`project_id` is the SENDER_ID in your cloud settings.\nhttps://firebase.google.com/docs/cloud-messaging/concept-options#senderid\n\n```ruby\nparams = { key_name: \"appUser-Chris\",\n                project_id: \"my_project_id\",\n                registration_ids: [\"4\", \"8\", \"15\", \"16\", \"23\", \"42\"] }\nresponse = fcm.create(*params.values)\n```\n\n### Send to Notification device group\n\nTo send messages to device groups, use the HTTP v1 API,\nSending messages to a device group is very similar to sending messages to an individual device, using the same method to authorize send requests. Set the token field to the group notification key\n\n```ruby\nmessage = {\n  'token': \"NOTIFICATION_KEY\", # send to a device group\n  # ...data\n}\n\nfcm.send_v1(message)\n```\n\n### Add/Remove Registration Tokens\n\nYou can also add/remove registration Tokens to/from a particular `notification_key` of some `project_id`. For example:\n\n```ruby\nparams = { key_name: \"appUser-Chris\",\n                project_id: \"my_project_id\",\n                notification_key:\"appUser-Chris-key\",\n                registration_ids:[\"7\", \"3\"] }\nresponse = fcm.add(*params.values)\n\nparams = { key_name: \"appUser-Chris\",\n                project_id: \"my_project_id\",\n                notification_key:\"appUser-Chris-key\",\n                registration_ids:[\"8\", \"15\"] }\nresponse = fcm.remove(*params.values)\n```\n\n## Send Messages to Topics\n\nFCM [topic messaging](https://firebase.google.com/docs/cloud-messaging/topic-messaging) allows your app server to send a message to multiple devices that have opted in to a particular topic. Based on the publish/subscribe model, one app instance can be subscribed to no more than 2000 topics. Sending to a topic is very similar to sending to an individual device or to a user group, in the sense that you can use the `fcm.send_v1` method where the `topic` matches the regular expression `\"/topics/[a-zA-Z0-9-_.~%]+\"`:\n\n```ruby\nmessage = {\n  'topic': \"yourTopic\", # send to a device group\n  # ...data\n}\n\nfcm.send_v1(message)\n```\n\nOr you can use the `fcm.send_to_topic` helper:\n\n```ruby\nresponse = fcm.send_to_topic(\"yourTopic\",\n            notification: { body: \"This is a FCM Topic Message!\"} )\n```\n\n## Send Messages to Topics with Conditions\n\nFCM [topic condition messaging](https://firebase.google.com/docs/cloud-messaging/android/topic-messaging#build_send_requests) to send a message to a combination of topics, specify a condition, which is a boolean expression that specifies the target topics.\n\n```ruby\nmessage = {\n  'condition': \"'TopicA' in topics \u0026\u0026 ('TopicB' in topics || 'TopicC' in topics)\", # send to topic condition\n  # ...data\n}\n\nfcm.send_v1(message)\n```\n\nOr you can use the `fcm.send_to_topic_condition` helper:\n\n```ruby\nresponse = fcm.send_to_topic_condition(\n  \"'TopicA' in topics \u0026\u0026 ('TopicB' in topics || 'TopicC' in topics)\",\n  notification: {\n    body: \"This is an FCM Topic Message sent to a condition!\"\n  }\n)\n```\n\n### Sending to Multiple Topics\n\nTo send to combinations of multiple topics, require that you set a **condition** key to a boolean condition that specifies the target topics. For example, to send messages to devices that subscribed to _TopicA_ and either _TopicB_ or _TopicC_:\n\n```\n'TopicA' in topics \u0026\u0026 ('TopicB' in topics || 'TopicC' in topics)\n```\n\nFCM first evaluates any conditions in parentheses, and then evaluates the expression from left to right. In the above expression, a user subscribed to any single topic does not receive the message. Likewise, a user who does not subscribe to TopicA does not receive the message. These combinations do receive it:\n\n- TopicA and TopicB\n- TopicA and TopicC\n\nYou can include up to five topics in your conditional expression, and parentheses are supported. Supported operators: `\u0026\u0026`, `||`, `!`. Note the usage for !:\n\n```\n!('TopicA' in topics)\n```\n\nWith this expression, any app instances that are not subscribed to TopicA, including app instances that are not subscribed to any topic, receive the message.\n\nThe `send_to_topic_condition` method within this library allows you to specicy a condition of multiple topics to which to send to the data payload.\n\n```ruby\nresponse = fcm.send_to_topic_condition(\n  \"'TopicA' in topics \u0026\u0026 ('TopicB' in topics || 'TopicC' in topics)\",\n  notification: {\n    body: \"This is an FCM Topic Message sent to a condition!\"\n  }\n)\n```\n\n## Subscribe the client app to a topic\n\nGiven a registration token and a topic name, you can add the token to the topic using the [Google Instance ID server API](https://developers.google.com/instance-id/reference/server).\n\n```ruby\ntopic = \"YourTopic\"\nregistration_token= \"12\" # a client registration token\nresponse = fcm.topic_subscription(topic, registration_token)\n# or unsubscription\nresponse = fcm.topic_unsubscription(topic, registration_token)\n```\n\nOr you can manage relationship maps for multiple app instances [Google Instance ID server API. Manage relationship](https://developers.google.com/instance-id/reference/server#manage_relationship_maps_for_multiple_app_instances)\n\n```ruby\ntopic = \"YourTopic\"\nregistration_tokens= [\"4\", \"8\", \"15\", \"16\", \"23\", \"42\"] # an array of one or more client registration tokens\nresponse = fcm.batch_topic_subscription(topic, registration_tokens)\n# or unsubscription\nresponse = fcm.batch_topic_unsubscription(topic, registration_tokens)\n```\n\n## Get Information about the Instance ID\n\nGiven a registration token, you can retrieve information about the token using the [Google Instance ID server API](https://developers.google.com/instance-id/reference/server).\n\n```ruby\nregistration_token= \"12\" # a client registration token\nresponse = fcm.get_instance_id_info(registration_token)\n```\n\nTo get detailed information about the instance ID, you can pass an optional\n`options` hash to the `get_instance_id_info` method:\n\n```ruby\nregistration_token= \"12\" # a client registration token\noptions = { \"details\" =\u003e true }\nresponse = fcm.get_instance_id_info(registration_token, options)\n```\n\n## Mobile Clients\n\nYou can find a guide to implement an Android Client app to receive notifications here: [Set up a FCM Client App on Android](https://firebase.google.com/docs/cloud-messaging/android/client).\n\nThe guide to set up an iOS app to get notifications is here: [Setting up a FCM Client App on iOS](https://firebase.google.com/docs/cloud-messaging/ios/client).\n\n## ChangeLog\n\n### 2.0.1\n- Add `http_options` to `initialize` method and whitelist `timeout` option\n\n### 2.0.0\n#### Breaking Changes\n- Remove deprecated `API_KEY`\n- Remove deprecated `send` method\n- Remove deprecated `send_with_notification_key` method\n- Remove `subscribe_instance_id_to_topic` method\n- Remove `unsubscribe_instance_id_from_topic` method\n- Remove `batch_subscribe_instance_ids_to_topic` method\n- Remove `batch_unsubscribe_instance_ids_from_topic` method\n\n#### Supported Features\n- Add HTTP v1 API support for `send_to_topic_condition` method\n- Add HTTP v1 API support for `send_to_topic` method\n\n### 1.0.8\n- caches calls to `Google::Auth::ServiceAccountCredentials` #103\n- Allow `faraday` versions from 1 up to 2  #101\n\n### 1.0.7\n\n- Fix passing `DEFAULT_TIMEOUT` to `faraday` [#96](https://github.com/decision-labs/fcm/pull/96)\n- Fix issue with `get_instance_id_info` option params [#98](https://github.com/decision-labs/fcm/pull/98)\n- Accept any IO object for credentials [#95](https://github.com/decision-labs/fcm/pull/94)\n\nHuge thanks to @excid3 @jsparling @jensljungblad\n\n### 1.0.3\n\n- Fix overly strict faraday dependency\n\n### 1.0.2\n\n- Bug fix: retrieve notification key\" params: https://github.com/spacialdb/fcm/commit/b328a75c11d779a06d0ceda83527e26aa0495774\n\n### 1.0.0\n\n- Bumped supported ruby to `\u003e= 2.4`\n- Fix deprecation warnings from `faraday` by changing dependency version to `faraday 1.0.0`\n\n### 0.0.7\n\n- replace `httparty` with `faraday`\n\n### 0.0.2\n\n- Fixed group messaging url.\n- Added API to `recover_notification_key`.\n\n\n### 0.0.1\n\n- Initial version.\n\n## MIT License\n\n- Copyright (c) 2016 Kashif Rasul and Shoaib Burq. See LICENSE.txt for details.\n\n## Many thanks to all the contributors\n\n- [Contributors](https://github.com/spacialdb/fcm/contributors)\n\n## Cutting a release\n\nUpdate version in `fcm.gemspec` with `VERSION` and update `README.md` `## ChangeLog` section.\n\n```bash\n# set the version\n# VERSION=\"1.0.7\"\ngem build fcm.gemspec\ngit tag -a v${VERSION} -m \"Releasing version v${VERSION}\"\ngit push origin --tags\ngem push fcm-${VERSION}.gem\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecision-labs%2Ffcm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdecision-labs%2Ffcm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdecision-labs%2Ffcm/lists"}