GCM sends notifications to Android devices via GCM.

##Installation

$ gem install gcm

or in your Gemfile just include it:

gem 'gcm'

##Requirements

An Android device running 2.3 or newer and an API key as per GCM getting started guide.

One of the following, tested Ruby versions:

• 1.9.3
• 2.0.0
• 2.1.5
• 2.2.0

##Usage

For your server to send a message to one or more devices, you must first initialise a new GCM class with your api key, and then call the send method on this and give it 1 or more (up to 1000) registration IDs as an array of strings. You can also optionally send further HTTP message parameters like data or time_to_live etc. as a hash via the second optional argument to send.

Example sending notifications:

require 'gcm'

gcm = GCM.new("my_api_key")
# you can set option parameters in here
#  - all options are pass to HTTParty method arguments
#  - ref: https://github.com/jnunemaker/httparty/blob/master/lib/httparty.rb#L40-L68
#  gcm = GCM.new("my_api_key", timeout: 3)

registration_ids= ["12", "13"] # an array of one or more client registration IDs
options = {data: {score: "123"}, collapse_key: "updated_score"}
response = gcm.send(registration_ids, options)

Currently response is just a hash containing the response body, headers and status. Check here to see how to interpret the responses.

With user notifications, you can send a single message to multiple instance of an app running on devices owned by a single user. To use this feature, you will first need an initialised GCM class.

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 in the response:

response = gcm.create(key_name: "appUser-Chris",
                project_id: "my_project_id",
                registration_ids:["4", "8", "15", "16", "23", "42"])

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 to multiple app instances (typically on multiple devices) owned by a single user (instead of sending to registration IDs). Note: the maximum number of members allowed for a notification_key is 10.

response = gcm.send_with_notification_key("notification_key", {
            data: {score: "3x1"},
            collapse_key: "updated_score"})

You can also add/remove registration IDs to/from a particular notification_key of some project_id. For example:

response = gcm.add(key_name: "appUser-Chris",
                project_id: "my_project_id",
                notification_key:"appUser-Chris-key",
                registration_ids:["7", "3"])

response = gcm.remove(key_name: "appUser-Chris",
                project_id: "my_project_id",
                notification_key:"appUser-Chris-key",
                registration_ids:["8", "15"])

• How to send iOS and Android notifications from your Rails backend
• Как отправлять push уведомления из Вашего Rails приложения
• GCM – 서버 만들기
• ruby から gcm を使って android 端末へメッセージを送信する
• titanium alloy android push通知 by ruby

You can find a guide to implement an Android Client app to receive notifications here: Implementing GCM Client.

• Added send_with_notification_key to send message to a notification key since the documented API for it is wrong.

• Check for NotRegistered error and return unregistered ids if this occurs

• Added support for User Notifications API
• Added alias method send for send_notification

• All responses now have a body and header hashes

• You can initialise GCM class with HTTParty Options

• Added support for canonical registration ID
• Only support Ruby versions >= 1.9.3
• Fixed Rspec deprecation warnings for Rspec 3.0.0.beta

##MIT License

• Copyright (c) 2015 Kashif Rasul and Shoaib Burq. See LICENSE.txt for details.

##Many thanks to all the contributors

• Contributors

We accept tips through Gratipay.