Firebase Cloud Messaging (FCM) 适用于 Android 和 iOS

FCM gem 可让您的 Ruby 后端通过 Firebase Cloud Messaging 向 Android 和 iOS 设备发送通知。

安装

$ gem install fcm

或者在您的 Gemfile 中直接添加：

gem 'fcm'

要求

对于 Android，您需要一台运行 2.3（或更高版本）且安装了 Google Play 商店应用的设备，或者一台运行带有 Google APIs 的 Android 2.3 模拟器。iOS 设备同样受支持。

支持的 Ruby 版本，当前为： ruby >= 2.4

快速开始

要使用此 gem，您需要使用您的 firebase 凭据实例化一个客户端：

fcm = FCM.new(
  GOOGLE_APPLICATION_CREDENTIALS_PATH,
  FIREBASE_PROJECT_ID
)

关于 GOOGLE_APPLICATION_CREDENTIALS_PATH

GOOGLE_APPLICATION_CREDENTIALS_PATH 用于存放您的 firebase 凭据。

提供凭据最简单的方法是在此处传入凭据文件的绝对路径：

fcm = FCM.new(
  '/path/to/credentials.json',
  FIREBASE_PROJECT_ID
)

考虑到这些信息的保密性，您可能不希望将它们存放在代码仓库中。这种情况下，另一种受支持的解决方案是传递一个包含您凭证的 StringIO：

fcm = FCM.new(
  StringIO.new(ENV.fetch('FIREBASE_CREDENTIALS')),
  FIREBASE_PROJECT_ID
)

请求超时

读取超时和 TCP 连接超时均可通过 http_options 进行配置。两者的默认值均为 DEFAULT_TIMEOUT（30 秒）：

fcm = FCM.new(
  GOOGLE_APPLICATION_CREDENTIALS_PATH,
  FIREBASE_PROJECT_ID,
  timeout: 10,      # response read timeout
  open_timeout: 5   # TCP connect timeout — fail fast on stuck handshakes
)

使用方法

HTTP v1 API

如需迁移至 HTTP v1，请参阅：https://firebase.google.com/docs/cloud-messaging/migrate-v1

fcm = FCM.new(
  GOOGLE_APPLICATION_CREDENTIALS_PATH,
  FIREBASE_PROJECT_ID
)
message = {
  'token': "000iddqd", # send to a specific device
  # 'topic': "yourTopic",
  # 'condition': "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)",
  'data': {
    payload: {
      data: {
        id: 1
      }
    }.to_json
  },
  'notification': {
    title: notification.title_th,
    body: notification.body_th,
  },
  'android': {},
  'apns': {
    payload: {
      aps: {
        sound: "default",
        category: "#{Time.zone.now.to_i}"
      }
    }
  },
  'fcm_options': {
    analytics_label: 'Label'
  }
}

fcm.send_v1(message) # or fcm.send_notification_v1(message)

设备组消息传递

借助设备组消息传递，您可以向运行在属于同一组的设备上的多个应用实例发送单条消息。通常，“组”指的是属于单个用户的一组不同设备。不过，组也可以表示应用实例以高度关联方式运行的一组设备。要使用此功能，您首先需要一个已初始化的 FCM 类。

通知密钥允许的最大成员数为 20。 https://firebase.google.com/docs/cloud-messaging/android/device-group#managing_device_groups

为设备组生成通知密钥

然后，您需要一个通知密钥，您可以为特定的 key_name 创建该密钥。如果您的同一 project_id 下有多个应用，则 key_name 需要按应用唯一命名。这样可以确保通知仅发送到目标应用。create 方法将执行此操作，并在响应中返回表示设备组的令牌 notification_key：

project_id 是您云设置中的 SENDER_ID。 https://firebase.google.com/docs/cloud-messaging/concept-options#senderid

params = { key_name: "appUser-Chris",
                project_id: "my_project_id",
                registration_ids: ["4", "8", "15", "16", "23", "42"] }
response = fcm.create(*params.values)

发送至通知设备组

要向设备组发送消息，请使用 HTTP v1 API。 向设备组发送消息与向单个设备发送消息非常相似，均使用相同的方法来授权发送请求。将 token 字段设置为组通知密钥。

message = {
  'token': "NOTIFICATION_KEY", # send to a device group
  # ...data
}

fcm.send_v1(message)

添加/移除注册令牌

您还可以向某个 project_id 的特定 notification_key 添加注册令牌，或从中移除注册令牌。例如：

params = { key_name: "appUser-Chris",
                project_id: "my_project_id",
                notification_key:"appUser-Chris-key",
                registration_ids:["7", "3"] }
response = fcm.add(*params.values)

params = { key_name: "appUser-Chris",
                project_id: "my_project_id",
                notification_key:"appUser-Chris-key",
                registration_ids:["8", "15"] }
response = fcm.remove(*params.values)

向主题发送消息

FCM 主题消息传递 允许您的应用服务器向已选择加入特定主题的多台设备发送消息。基于发布/订阅模型，一个应用实例最多可订阅 2000 个主题。向主题发送消息与向单个设备或用户组发送消息非常相似，您可以使用 fcm.send_v1 方法，其中 topic 需匹配正则表达式 "/topics/[a-zA-Z0-9-_.~%]+"：

message = {
  'topic': "yourTopic", # send to a device group
  # ...data
}

fcm.send_v1(message)

或者您可以使用 fcm.send_to_topic 辅助方法：

response = fcm.send_to_topic("yourTopic",
            notification: { body: "This is a FCM Topic Message!"} )

按条件向主题发送消息

FCM 的主题条件消息传递功能可向多个主题的组合发送消息。发送时需指定一个条件，该条件是用于指定目标主题的布尔表达式。

message = {
  'condition': "'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)", # send to topic condition
  # ...data
}

fcm.send_v1(message)

或者你可以使用 fcm.send_to_topic_condition 辅助方法：

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!"
  }
)

发送到多个主题

要向多个主题的组合发送消息，需要将 condition 键设置为一个布尔条件，用于指定目标主题。例如，要向订阅了 TopicA 且同时订阅了 TopicB 或 TopicC 的设备发送消息：

'TopicA' in topics && ('TopicB' in topics || 'TopicC' in topics)

FCM 首先计算括号中的所有条件，然后从左到右计算表达式。在上述表达式中，仅订阅单个主题的用户不会收到消息。同样，未订阅 TopicA 的用户也不会收到消息。以下组合会收到消息：

• TopicA 和 TopicB
• TopicA 和 TopicC

条件表达式中最多可包含五个主题，且支持使用括号。支持的运算符：&&、||、!。请注意 ! 的用法：

!('TopicA' in topics)

使用此表达式，所有未订阅 TopicA 的应用实例（包括未订阅任何主题的应用实例）都将收到消息。

本库中的 send_to_topic_condition 方法允许您指定发送数据负载的多个主题条件。

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!"
  }
)

订阅客户端应用到主题

给定注册令牌和主题名称，您可以使用 Google Instance ID 服务器 API 将令牌添加到主题。

topic = "YourTopic"
registration_token= "12" # a client registration token
response = fcm.topic_subscription(topic, registration_token)
# or unsubscription
response = fcm.topic_unsubscription(topic, registration_token)

或者，您可以为多个应用实例管理关系映射 Google 实例 ID 服务器 API：管理关系

topic = "YourTopic"
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_tokens)

获取实例 ID 相关信息

给定一个注册令牌，您可以使用 Google Instance ID 服务器 API 检索该令牌的相关信息。

registration_token= "12" # a client registration token
response = fcm.get_instance_id_info(registration_token)

要获取实例 ID 的详细信息，您可以向 get_instance_id_info 方法传递一个可选的 options 哈希：

registration_token= "12" # a client registration token
options = { "details" => true }
response = fcm.get_instance_id_info(registration_token, options)

移动客户端

您可以在此处找到实现 Android 客户端应用以接收通知的指南：Set up a FCM Client App on Android。

设置 iOS 应用以接收通知的指南在此处：Setting up a FCM Client App on iOS。

更新日志

2.0.2

• 在打开 JSON 密钥路径前，确保其是实际文件或 IO 对象 #134

2.0.1

• 向 initialize 方法添加 http_options 并将 timeout 选项加入白名单

2.0.0

重大变更

• 移除已弃用的 API_KEY
• 移除已弃用的 send 方法
• 移除已弃用的 send_with_notification_key 方法
• 移除 subscribe_instance_id_to_topic 方法
• 移除 unsubscribe_instance_id_from_topic 方法
• 移除 batch_subscribe_instance_ids_to_topic 方法
• 移除 batch_unsubscribe_instance_ids_from_topic 方法

支持的功能

• 为 send_to_topic_condition 方法添加 HTTP v1 API 支持
• 为 send_to_topic 方法添加 HTTP v1 API 支持

1.0.8

• 缓存对 Google::Auth::ServiceAccountCredentials 的调用 #103
• 允许 faraday 版本从 1 到 2 #101

1.0.7

• 修复向 faraday 传递 DEFAULT_TIMEOUT 的问题 #96
• 修复 get_instance_id_info 选项参数的问题 #98
• 接受任何 IO 对象作为凭据 #95

特别感谢 @excid3 @jsparling @jensljungblad

1.0.3

• 修复过于严格的 faraday 依赖项

1.0.2

• 错误修复：检索通知密钥参数：https://github.com/spacialdb/fcm/commit/b328a75c11d779a06d0ceda83527e26aa0495774

1.0.0

• 将支持的 Ruby 版本提升至 >= 2.4
• 通过将依赖版本更改为 faraday 1.0.0，修复来自 faraday 的弃用警告

0.0.7

• 用 faraday 替换 httparty

0.0.2

• 修复群组消息 URL。
• 添加 recover_notification_key API。

0.0.1

• 初始版本。

MIT 许可证

• 版权所有 (c) 2016 Kashif Rasul 和 Shoaib Burq。详情参见 LICENSE.txt。

非常感谢所有贡献者

• 贡献者

发布版本

在 fcm.gemspec 中使用 VERSION 更新版本号，并更新 README.md 中的 ## ChangeLog 部分。

# set the version
# VERSION="1.0.7"
gem build fcm.gemspec
git tag -a v${VERSION} -m "Releasing version v${VERSION}"
git push origin --tags
gem push fcm-${VERSION}.gem