Google Cloud Messaging for Android (GCM)

Gem Version Build Status

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) or an iOS device and an API key as per GCM getting started guide.

One of the following, tested Ruby versions:

  • 2.0.0
  • 2.1.8
  • 2.2.4
  • 2.3.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 tokens 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#L29-L60
#  gcm = GCM.new("my_api_key", timeout: 3)

registration_ids= ["12", "13"] # an array of one or more client registration tokens
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.

Device Group Messaging

With device group messaging, 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 GCM class.

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:

response = gcm.create(key_name: "appUser-Chris",
                project_id: "my_project_id", # https://developers.google.com/cloud-messaging/gcm#senderid
                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 some registration tokens). Note: the maximum number of members allowed for a notification_key is 20.

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

Add/Remove Registration Tokens

You can also add/remove registration Tokens 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"])

Send Messages to Topics

GCM 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 gcm.send_with_notification_key() method where the noticiation_key matches the regular expression "/topics/[a-zA-Z0-9-_.~%]+":

response = gcm.send_with_notification_key("/topics/yourTopic", {
            data: {message: "This is a GCM Topic Message!"})

Or you can use the helper:

response = gcm.send_to_topic("yourTopic", {
            data: {message: "This is a GCM Topic Message!"})

Blog Posts

Mobile Clients

You can find a guide to implement an Android Client app to receive notifications here: Set up a GCM Client App on Android.

The guide to set up an iOS app to get notifications is here: Setting up a GCM Client App on iOS.

ChangeLog

0.1.1

  • Added helper send_to_topic to send messages to topics.
  • Fixed documentation and updated base uri to https://gcm-http.googleapis.com/gcm

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

0.0.5

##MIT License

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

##Many thanks to all the contributors

Donations

We accept tips through Gratipay.

Gratipay