gcmclient Package

Google Cloud Messaging client built on top of requests library.

gcmclient Package

gcmclient.gcm.GCM_URL = 'https://android.googleapis.com/gcm/send'

Default URL to GCM service.

class gcmclient.gcm.GCM(api_key, url='https://android.googleapis.com/gcm/send', backoff=1000, **options)

Create new connection.

Arguments:
  • api_key (str): Google API key.
  • url (str): GCM server URL.
  • backoff (int): initial backoff in milliseconds.
  • options (kwargs): options for requests such as proxies.
send(message)

Send message.

The message may contain various options, such as time_to_live. Your request might be rejected, because some of your options might be invalid. In this case a ValueError with explanation will be raised.

Arguments:

message (Message): plain text or JSON message.
Returns:

Result interpreting the results.
Raises:
  • requests.exceptions.RequestException on any network problem.
  • ValueError if your GCM request or response is rejected.
  • GCMAuthenticationError your API key is invalid.
class gcmclient.gcm.JSONMessage(registration_ids, data=None, **options)

Multicast message, uses JSON format.

Arguments:
  • registration_ids (list): registration ID’s of target devices.
  • data (dict): key-value pairs of message payload.
  • options (kwargs): GCM options, see Message for more info.
__getstate__()

Returns dict with __init__ arguments.

If you use pickle, then simply pickle/unpickle the message object. If you use something else, like JSON, then:

# obtain state dict from message
state = message.__getstate__()
# send/store the state
# recover state and restore message. you have to pick the right class
message_copy = JSONMessage(**state)
Returns:kwargs for JSONMessage constructor.
registration_ids

Target registration ID’s.

class gcmclient.gcm.PlainTextMessage(registration_id, data=None, **options)

Unicast message, uses plain text format. All values in the data payload must be URL encodable scalars.

Arguments:
  • registration_id (str): registration ID of target device.
  • data (dict): key-value pairs of message payload.
  • options (kwargs): GCM options, see Message for more info.
__getstate__()

Returns dict with __init__ arguments.

If you use pickle, then simply pickle/unpickle the message object. If you use something else, like JSON, then:

# obtain state dict from message
state = message.__getstate__()
# send/store the state
# recover state and restore message. you have to pick the right class
message_copy = PlainTextMessage(**state)
Returns:kwargs for PlainTextMessage constructor.
registration_id

Target registration ID.

class gcmclient.gcm.Message(data=None, options=None)

Abstract message.

Arguments:
  • data (dict): key-value pairs, payload of this message.
  • options (dict): GCM options.

Refer to GCM for more explanation on available options.

Options:
  • collapse_key (str): collapse key/bucket.
  • time_to_live (int): message TTL in seconds.
  • delay_while_idle (bool): hold message if device is off-line.
  • restricted_package_name (str): declare package name.
  • dry_run (bool): pretend sending message to devices.
class gcmclient.gcm.Result(message, response, backoff)

Result of send operation.

You should check canonical() for any registration ID’s that should be updated. If the whole message or some registration ID’s have recoverably failed, then retry() will provide you with new message. You have to wait delay() seconds before attempting a new request.

backoff(retry=0)

Computes exponential backoff for given retry number.

canonical

New registration ID’s as mapping {registration_id: canonical_id}.

You have to update registration ID’s of your subscribers by replacing them with corresponding canonical ID. Read more here.

delay(retry=0)

Time to wait in seconds before attempting a retry as a float number.

This method will return value of Retry-After header if it is provided by GCM. Otherwise, it will return (backoff * 2^retry) with some random shift. Google may black list your server if you do not honor Retry-After hint and do not use exponential backoff.

failed

Unrecoverably failed regisration ID’s as mapping {registration_id: error code}.

This method lists devices, that have failed with something else than:

Read more about possible error codes.

needs_retry()

True if retry() will return message.

not_registered

List all registration ID’s that GCM reports as NotRegistered. You should remove them from your database.

retry()

Construct new message that will unicast/multicast to remaining recoverably failed registration ID’s. Method returns None if there is nothing to retry. Do not forget to wait for delay() seconds before new attempt.

success

Successfully processed registration ID’s as mapping {registration_id: message_id}.

class gcmclient.gcm.GCMAuthenticationError

Raised if your Google API key is rejected.