Google Cloud Messaging for Android (GCM)

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.7
2.2.3

##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.

User Notifications

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.

Generate a Notification Key

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"])

Send to Notification Key

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

Add/Remove Registration IDs

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"])

Blog Posts

Android Client

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

ChangeLog

0.1.0

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

0.0.9

Check for NotRegistered error and return unregistered ids if this occurs

0.0.8

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

0.0.7

All responses now have a body and header hashes

0.0.6

You can initialise GCM class with HTTParty Options

0.0.5

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

##Many thanks to all the contributors

Contributors

Donations

We accept tips through Gratipay.

StevenYCChou/gcm