fcmclient Package¶
Firebase Cloud Messaging client built on top of requests library.
fcmclient
Package¶
-
fcmclient.api.
FCM_URL
= 'https://fcm.googleapis.com/fcm/send'¶ Default URL to FCM service.
-
class
fcmclient.api.
FCM
(api_key, url='https://fcm.googleapis.com/fcm/send', backoff=1000, **options)¶ Create new connection.
Parameters: - api_key – (str) Google API key
- url – (str) FCM server URL.
- backoff – (int) initial backoff in milliseconds.
- options – (kwargs) options for `requests
-
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 aValueError
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 FCM request or response is rejected.FCMAuthenticationError
your API key is invalid.
-
class
fcmclient.api.
JSONMessage
(registration_ids, data=None, message_title=None, message_body=None, payload=None, **options)¶ Multicast message, uses JSON format.
Arguments: - registration_ids (list): registration ID’s of target
- devices.
- data (dict): key-value pairs, payload of this message.
- message_title (str): a title for the notification
- message_body (str): the message body of the alert.
- options (dict): FCM options.
Refer to FCM 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.
-
__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
fcmclient.api.
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, thenretry()
will provide you with new message. You have to waitdelay()
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 FCM. 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:
Unavailable
– look forretry()
instead.NotRegistered
– look fornot_registered
instead.
Read more about possible error codes.
-
not_registered
¶ List all registration ID’s that FCM 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
fcmclient.api.
FCMAuthenticationError
¶ Raised if your Google API key is rejected.