fcm 1.0.8 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16615f79f5432e2a352dc3c26e42d48efed7727a86f04f2b9d2bf93cca47aae6
-  data.tar.gz: d2fe30204d7ef51288014fbcc2df5f211ea8d8b4dbbc28cb9af0d9fadc54d6c7
+  metadata.gz: 72a9acc9e72359d421c740b5ac8ce3c9547a587a1e08672931a51355523b27a0
+  data.tar.gz: 250eb8a97008cc4affc39a512695c5cf9339baa35de77854169746ed80fcf7c3
 SHA512:
-  metadata.gz: 06c32340bae1ab25e1d66c06d63fa5d7276214604902218a1a9f5cf06774a60a08ab4bc700616f63ed5563a8b106227ef073168fcbfa29798348fadec2480767
-  data.tar.gz: ffa28e382feba7728e496318ea546237c9c5070ccc175d71a2dc83e9adf0a58efa932336a729549599978b6a2406ec01e80bd060997f779631d3a53122660b59
+  metadata.gz: 0beb8691a1a5dc0090ce92cb584c1f44aa97545de9f45d649a65b2ac4cd2196db8178ace4675a7f39deca00bcb8650fb4a9e71569b609f24aa6942fa88e08c2c
+  data.tar.gz: e079ef26d913c7e418e89943cedc980034f03d49cc749c681ee8e4e237fe6a2a059342f012c235a84d2ba227fa8941671e9834350beea5ce93e6ee7341f2aa49

data/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby: ['2.7', '3.0', '3.1']
+        ruby: ['2.7', '3.0', '3.1', '3.3']
 
     steps:
       - uses: actions/checkout@master

data/.gitignore

@@ -49,3 +49,4 @@ Gemfile.lock
 .rvmrc
 spec/reports
 *.gem
+.env

data/README.md

@@ -22,6 +22,38 @@ For Android you will need a device running 2.3 (or newer) that also have the Goo
 A version of supported Ruby, currently:
 `ruby >= 2.4`
 
+## Getting Started
+To use this gem, you need to instantiate a client with your firebase credentials:
+
+```ruby
+fcm = FCM.new(
+  GOOGLE_APPLICATION_CREDENTIALS_PATH,
+  FIREBASE_PROJECT_ID
+)
+```
+
+## About the `GOOGLE_APPLICATION_CREDENTIALS_PATH`
+The `GOOGLE_APPLICATION_CREDENTIALS_PATH` is meant to contain your firebase credentials.
+
+The easiest way to provide them is to pass here an absolute path to a file with your credentials:
+
+```ruby
+fcm = FCM.new(
+  '/path/to/credentials.json',
+  FIREBASE_PROJECT_ID
+)
+```
+
+As 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:
+
+```ruby
+fcm = FCM.new(
+  StringIO.new(ENV.fetch('FIREBASE_CREDENTIALS')),
+  FIREBASE_PROJECT_ID
+)
+
+```
+
 ## Usage
 
 ## HTTP v1 API
@@ -30,13 +62,13 @@ To migrate to HTTP v1 see: https://firebase.google.com/docs/cloud-messaging/migr
 
 ```ruby
 fcm = FCM.new(
-  API_TOKEN,
   GOOGLE_APPLICATION_CREDENTIALS_PATH,
   FIREBASE_PROJECT_ID
 )
 message = {
-  'topic': "89023", # OR token if you want to send to a specific device
-  # 'token': "000iddqd",
+  'token': "000iddqd", # send to a specific device
+  # 'topic': "yourTopic",
+  # 'condition': "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)",
   'data': {
     payload: {
       data: {
@@ -62,58 +94,42 @@ message = {
   }
 }
 
-fcm.send_v1(message)
-```
-
-## HTTP Legacy Version
-
-To migrate to HTTP v1 see: https://firebase.google.com/docs/cloud-messaging/migrate-v1
-
-For your server to send a message to one or more devices, you must first initialise a new `FCM` class with your Firebase Cloud Messaging server key, and then call the `send` method on this and give it 1 or more (up to 1000) registration tokens as an array of strings. You can also optionally send further [HTTP message parameters](https://firebase.google.com/docs/cloud-messaging/http-server-ref) like `data` or `time_to_live` etc. as a hash via the second optional argument to `send`.
-
-Example sending notifications:
-
-```ruby
-require 'fcm'
-
-fcm = FCM.new("my_server_key")
-
-registration_ids= ["12", "13"] # an array of one or more client registration tokens
-
-# See https://firebase.google.com/docs/cloud-messaging/http-server-ref for all available options.
-options = { "notification": {
-              "title": "Portugal vs. Denmark",
-              "body": "5 to 1"
-          }
-}
-response = fcm.send(registration_ids, options)
+fcm.send_v1(message) # or fcm.send_notification_v1(message)
 ```
 
-Currently `response` is just a hash containing the response `body`, `headers` and `status_code`. Check [here](https://firebase.google.com/docs/cloud-messaging/server#response) to see how to interpret the responses.
-
 ## Device Group Messaging
 
 With [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.
 
+The maximum number of members allowed for a notification key is 20.
+https://firebase.google.com/docs/cloud-messaging/android/device-group#managing_device_groups
+
 ### Generate a Notification Key for device group
 
 Then 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:
 
+`project_id` is the SENDER_ID in your cloud settings.
+https://firebase.google.com/docs/cloud-messaging/concept-options#senderid
+
 ```ruby
-params = {key_name: "appUser-Chris",
+params = { key_name: "appUser-Chris",
                 project_id: "my_project_id",
-                registration_ids: ["4", "8", "15", "16", "23", "42"]}
+                registration_ids: ["4", "8", "15", "16", "23", "42"] }
 response = fcm.create(*params.values)
 ```
 
-### Send to Notification Key
+### Send to Notification device group
 
-Now you can send a message to a particular `notification_key` via the `send_with_notification_key` method. This allows the server to send a single [data](https://firebase.google.com/docs/cloud-messaging/concept-options#data_messages) payload or/and [notification](https://firebase.google.com/docs/cloud-messaging/concept-options#notifications) payload to multiple app instances (typically on multiple devices) owned by a single user (instead of sending to some registration tokens). Note: the maximum number of members allowed for a `notification_key` is 20.
+To send messages to device groups, use the HTTP v1 API,
+Sending 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
 
 ```ruby
-response = fcm.send_with_notification_key("notification_key",
-            data: {score: "3x1"},
-            collapse_key: "updated_score")
+message = {
+  'token': "NOTIFICATION_KEY", # send to a device group
+  # ...data
+}
+
+fcm.send_v1(message)
 ```
 
 ### Add/Remove Registration Tokens
@@ -136,23 +152,51 @@ response = fcm.remove(*params.values)
 
 ## Send Messages to Topics
 
-FCM [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, topic messaging supports unlimited subscriptions per app. 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_with_notification_key()` method where the `notification_key` matches the regular expression `"/topics/[a-zA-Z0-9-_.~%]+"`:
+FCM [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-_.~%]+"`:
 
 ```ruby
-response = fcm.send_with_notification_key("/topics/yourTopic",
-            notification: {body: "This is a FCM Topic Message!"})
+message = {
+  'topic': "yourTopic", # send to a device group
+  # ...data
+}
+
+fcm.send_v1(message)
 ```
 
-Or you can use the helper:
+Or you can use the `fcm.send_to_topic` helper:
 
 ```ruby
 response = fcm.send_to_topic("yourTopic",
-            notification: {body: "This is a FCM Topic Message!"})
+            notification: { body: "This is a FCM Topic Message!"} )
+```
+
+## Send Messages to Topics with Conditions
+
+FCM [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.
+
+```ruby
+message = {
+  'condition': "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)", # send to topic condition
+  # ...data
+}
+
+fcm.send_v1(message)
+```
+
+Or you can use the `fcm.send_to_topic_condition` helper:
+
+```ruby
+response = fcm.send_to_topic_condition(
+  "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)",
+  notification: {
+    body: "This is an FCM Topic Message sent to a condition!"
+  }
+)
 ```
 
 ### Sending to Multiple Topics
 
-To send to combinations of multiple topics, the FCM [docs](https://firebase.google.com/docs/cloud-messaging/send-message#send_messages_to_topics_2) require that you set a **condition** key (instead of the `to:` 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_:
+To 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_:
 
 ```
 'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)
@@ -188,18 +232,38 @@ Given a registration token and a topic name, you can add the token to the topic
 
 ```ruby
 topic = "YourTopic"
-registration_id= "12" # a client registration tokens
-response = fcm.topic_subscription(topic, registration_id)
+registration_token= "12" # a client registration token
+response = fcm.topic_subscription(topic, registration_token)
+# or unsubscription
+response = fcm.topic_unsubscription(topic, registration_token)
 ```
 
 Or 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)
 
 ```ruby
 topic = "YourTopic"
-registration_ids= ["4", "8", "15", "16", "23", "42"] # an array of one or more client registration tokens
-response = fcm.batch_topic_subscription(topic, registration_ids)
+registration_tokens= ["4", "8", "15", "16", "23", "42"] # an array of one or more client registration tokens
+response = fcm.batch_topic_subscription(topic, registration_tokens)
 # or unsubscription
-response = fcm.batch_topic_unsubscription(topic, registration_ids)
+response = fcm.batch_topic_unsubscription(topic, registration_tokens)
+```
+
+## Get Information about the Instance ID
+
+Given 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).
+
+```ruby
+registration_token= "12" # a client registration token
+response = fcm.get_instance_id_info(registration_token)
+```
+
+To get detailed information about the instance ID, you can pass an optional
+`options` hash to the `get_instance_id_info` method:
+
+```ruby
+registration_token= "12" # a client registration token
+options = { "details" => true }
+response = fcm.get_instance_id_info(registration_token, options)
 ```
 
 ## Mobile Clients
@@ -210,6 +274,20 @@ The guide to set up an iOS app to get notifications is here: [Setting up a FCM C
 
 ## ChangeLog
 
+### 2.0.0
+#### Breaking Changes
+- Remove deprecated `API_KEY`
+- Remove deprecated `send` method
+- Remove deprecated `send_with_notification_key` method
+- Remove `subscribe_instance_id_to_topic` method
+- Remove `unsubscribe_instance_id_from_topic` method
+- Remove `batch_subscribe_instance_ids_to_topic` method
+- Remove `batch_unsubscribe_instance_ids_from_topic` method
+
+#### Supported Features
+- Add HTTP v1 API support for `send_to_topic_condition` method
+- Add HTTP v1 API support for `send_to_topic` method
+
 ### 1.0.8
 - caches calls to `Google::Auth::ServiceAccountCredentials` #103
 - Allow `faraday` versions from 1 up to 2  #101

data/fcm.gemspec

@@ -3,7 +3,7 @@ $:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
   s.name = "fcm"
-  s.version = "1.0.8"
+  s.version = "2.0.0"
   s.platform = Gem::Platform::RUBY
   s.authors = ["Kashif Rasul", "Shoaib Burq"]
   s.email = ["kashif@decision-labs.com", "shoaib@decision-labs.com"]

data/lib/fcm.rb

@@ -7,20 +7,14 @@ class FCM
   BASE_URI = "https://fcm.googleapis.com"
   BASE_URI_V1 = "https://fcm.googleapis.com/v1/projects/"
   DEFAULT_TIMEOUT = 30
-  FORMAT = :json
 
-  # constants
   GROUP_NOTIFICATION_BASE_URI = "https://android.googleapis.com"
   INSTANCE_ID_API = "https://iid.googleapis.com"
   TOPIC_REGEX = /[a-zA-Z0-9\-_.~%]+/
 
-  attr_accessor :timeout, :api_key, :json_key_path, :project_base_uri
-
-  def initialize(api_key, json_key_path = "", project_name = "", client_options = {})
-    @api_key = api_key
-    @client_options = client_options
+  def initialize(json_key_path = "", project_name = "")
     @json_key_path = json_key_path
-    @project_base_uri = BASE_URI_V1 + project_name.to_s
+    @project_name = project_name
   end
 
   # See https://firebase.google.com/docs/cloud-messaging/send-message
@@ -47,48 +41,24 @@ class FCM
   #     }
   #   }
   # }
-  # fcm = FCM.new(api_key, json_key_path, project_name)
-  # fcm.send(
+  # fcm = FCM.new(json_key_path, project_name)
+  # fcm.send_v1(
   #    { "token": "4sdsx",, "to" : "notification": {}.. }
   # )
   def send_notification_v1(message)
-    return if @project_base_uri.empty?
+    return if @project_name.empty?
 
     post_body = { 'message': message }
-
-    response = Faraday.post("#{@project_base_uri}/messages:send") do |req|
-      req.headers["Content-Type"] = "application/json"
-      req.headers["Authorization"] = "Bearer #{jwt_token}"
-      req.body = post_body.to_json
+    for_uri(BASE_URI_V1) do |connection|
+      response = connection.post(
+        "#{@project_name}/messages:send", post_body.to_json
+      )
+      build_response(response)
     end
-    build_response(response)
   end
 
   alias send_v1 send_notification_v1
 
-  # See https://developers.google.com/cloud-messaging/http for more details.
-  # { "notification": {
-  #  "title": "Portugal vs. Denmark",
-  #  "text": "5 to 1"
-  # },
-  # "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1..."
-  # }
-  # fcm = FCM.new("API_KEY")
-  # fcm.send(
-  #    ["4sdsx", "8sdsd"], # registration_ids
-  #    { "notification": { "title": "Portugal vs. Denmark", "text": "5 to 1" }, "to" : "bk3RNwTe3HdFQ3P1..." }
-  # )
-  def send_notification(registration_ids, options = {})
-    post_body = build_post_body(registration_ids, options)
-
-    for_uri(BASE_URI) do |connection|
-      response = connection.post("/fcm/send", post_body.to_json)
-      build_response(response, registration_ids)
-    end
-  end
-
-  alias send send_notification
-
   def create_notification_key(key_name, project_id, registration_ids = [])
     post_body = build_post_body(registration_ids, operation: "create",
                                                   notification_key_name: key_name)
@@ -152,28 +122,29 @@ class FCM
     end
   end
 
-  def send_with_notification_key(notification_key, options = {})
-    body = { to: notification_key }.merge(options)
-    execute_notification(body)
-  end
-
-  def topic_subscription(topic, registration_id)
+  def topic_subscription(topic, registration_token)
     for_uri(INSTANCE_ID_API) do |connection|
-      response = connection.post("/iid/v1/#{registration_id}/rel/topics/#{topic}")
+      response = connection.post(
+        "/iid/v1/#{registration_token}/rel/topics/#{topic}"
+      )
       build_response(response)
     end
   end
 
-  def batch_topic_subscription(topic, registration_ids)
-    manage_topics_relationship(topic, registration_ids, "Add")
+  def topic_unsubscription(topic, registration_token)
+    batch_topic_unsubscription(topic, [registration_token])
+  end
+
+  def batch_topic_subscription(topic, registration_tokens)
+    manage_topics_relationship(topic, registration_tokens, 'Add')
   end
 
-  def batch_topic_unsubscription(topic, registration_ids)
-    manage_topics_relationship(topic, registration_ids, "Remove")
+  def batch_topic_unsubscription(topic, registration_tokens)
+    manage_topics_relationship(topic, registration_tokens, 'Remove')
   end
 
-  def manage_topics_relationship(topic, registration_ids, action)
-    body = { to: "/topics/#{topic}", registration_tokens: registration_ids }
+  def manage_topics_relationship(topic, registration_tokens, action)
+    body = { to: "/topics/#{topic}", registration_tokens: registration_tokens }
 
     for_uri(INSTANCE_ID_API) do |connection|
       response = connection.post("/iid/v1:batch#{action}", body.to_json)
@@ -181,41 +152,38 @@ class FCM
     end
   end
 
-  def send_to_topic(topic, options = {})
-    if topic.gsub(TOPIC_REGEX, "").length == 0
-      send_with_notification_key("/topics/" + topic, options)
-    end
-  end
-
   def get_instance_id_info(iid_token, options = {})
     params = options
 
     for_uri(INSTANCE_ID_API) do |connection|
-      response = connection.get("/iid/info/" + iid_token, params)
+      response = connection.get("/iid/info/#{iid_token}", params)
       build_response(response)
     end
   end
 
-  def subscribe_instance_id_to_topic(iid_token, topic_name)
-    batch_subscribe_instance_ids_to_topic([iid_token], topic_name)
-  end
-
-  def unsubscribe_instance_id_from_topic(iid_token, topic_name)
-    batch_unsubscribe_instance_ids_from_topic([iid_token], topic_name)
-  end
-
-  def batch_subscribe_instance_ids_to_topic(instance_ids, topic_name)
-    manage_topics_relationship(topic_name, instance_ids, "Add")
-  end
-
-  def batch_unsubscribe_instance_ids_from_topic(instance_ids, topic_name)
-    manage_topics_relationship(topic_name, instance_ids, "Remove")
+  def send_to_topic(topic, options = {})
+    if topic.gsub(TOPIC_REGEX, '').length.zero?
+      body = { 'message': { 'topic': topic }.merge(options) }
+
+      for_uri(BASE_URI_V1) do |connection|
+        response = connection.post(
+          "#{@project_name}/messages:send", body.to_json
+        )
+        build_response(response)
+      end
+    end
   end
 
   def send_to_topic_condition(condition, options = {})
     if validate_condition?(condition)
-      body = { condition: condition }.merge(options)
-      execute_notification(body)
+      body = { 'message': { 'condition': condition }.merge(options) }
+
+      for_uri(BASE_URI_V1) do |connection|
+        response = connection.post(
+          "#{@project_name}/messages:send", body.to_json
+        )
+        build_response(response)
+      end
     end
   end
 
@@ -228,7 +196,8 @@ class FCM
     ) do |faraday|
       faraday.adapter Faraday.default_adapter
       faraday.headers["Content-Type"] = "application/json"
-      faraday.headers["Authorization"] = "key=#{api_key}"
+      faraday.headers["Authorization"] = "Bearer #{jwt_token}"
+      faraday.headers["access_token_auth"]= "true"
       extra_headers.each do |key, value|
         faraday.headers[key] = value
       end
@@ -286,13 +255,6 @@ class FCM
     not_registered_ids
   end
 
-  def execute_notification(body)
-    for_uri(BASE_URI) do |connection|
-      response = connection.post("/fcm/send", body.to_json)
-      build_response(response)
-    end
-  end
-
   def has_canonical_id?(result)
     !result["registration_id"].nil?
   end