Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
A gem that helps developers send data from servers to their Android applications on Android devices via Google Cloud Messaging (GCM).
Ruby
branch: master

added changelog

fixes #17
latest commit 508039cc13
Dr. Kashif Rasul kashif authored

README.md

Google Cloud Messaging for Android (GCM)

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

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

0.0.5

MIT License

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

Many thanks to all the contributors

Donations

We accept tips through Gratipay.

Gratipay

Something went wrong with that request. Please try again.