Cloud Messaging¶
Firebase Cloud Messaging (FCM) sends notifications and data to the app: to one device (by its registration token), to everyone subscribed to a topic, or to audiences built in the console. On iOS, FCM delivers through Apple's push service (APNs).
from pyios_firebase.messaging import Messaging
messaging = Messaging.messaging()
messaging.add_token_listener(lambda token: send_to_my_server(token))
messaging.subscribe_to_topic("news")
To ask permission and handle what arrives, see Notifications.
Installation¶
- Add the
FirebaseMessagingSwift package product (Installation). - Give the app the Push Notifications capability
(
aps-environmententitlement). For background data, add Background Modes > Remote notifications too. - Create an APNs authentication key in your Apple Developer account (Keys > +, Apple Push Notifications service), and upload it in the console: Project settings > Cloud Messaging > Apple app configuration.
- In the app: ask permission and register with APNs.
sequenceDiagram
participant App
participant APNs
participant FCM
participant Server as Your server
App->>APNs: register for remote notifications
APNs-->>App: APNs device token
App->>FCM: the APNs token (Firebase does it for you)
FCM-->>App: FCM registration token
App->>Server: the FCM token
Server->>FCM: send(token, message)
FCM->>APNs: deliver
APNs->>App: notification
The Simulator
FCM cannot deliver to the iOS Simulator. xcrun simctl push delivers a
test payload instead (Notifications).
App configuration¶
What the app's build needs for this product. To combine several products, list
them all in one products; see App configuration.
[[tool.kivy.ios.include_files]]
dest = "."
sources = ["GoogleService-Info.plist"]
[tool.kivy.ios.native.swift_packages.Firebase]
url = "https://github.com/firebase/firebase-ios-sdk.git"
requirement = { from = "13.1.1" }
products = ["FirebaseMessaging"]
[tool.kivy.ios.xcode.build_settings]
OTHER_LDFLAGS = "$(inherited) -ObjC"
# Push Notifications ("production" for TestFlight and the App Store)
[tool.kivy.ios.entitlements]
"aps-environment" = "development"
[tool.kivy.ios.info_plist]
# background data with notifications
UIBackgroundModes = ["remote-notification"]
# optional: no token until you ask; register with the installation ID
# FirebaseMessagingAutoInitEnabled = false
# FirebaseMessagingInstallationIdEnabled = true
# Kivy: the tap that launches a closed app reaches on_open (optional)
[tool.kivy.ios.native.swift_packages.PyiosFirebaseNotificationsHook]
url = "https://github.com/PySimpleObjC/pyios-firebase-notifications-hook.git"
requirement = { from = "0.1.0" }
products = ["PyiosFirebaseNotificationsHook"]
- File > Add Package Dependencies...,
https://github.com/firebase/firebase-ios-sdk.git, and pickFirebaseMessaging. - Build Settings > Other Linker Flags: add
-ObjC. - Add
GoogleService-Info.plistto the app target. - Signing & Capabilities: Push Notifications, and Background Modes > Remote notifications.
- Optional, in Info:
FirebaseMessagingAutoInitEnabled=NO,FirebaseMessagingInstallationIdEnabled=YES. - Kivy (kivy-ios), optional: add the
https://github.com/PySimpleObjC/pyios-firebase-notifications-hook.gitpackage (productPyiosFirebaseNotificationsHook), so a tap that launches the closed app reacheson_open(Notifications).
Note
Upload an APNs authentication key in the console (Project settings > Cloud Messaging).
Kivy: taps that launch the app
Without the PyiosFirebaseNotificationsHook package, a Kivy app still
opens when a notification is tapped while it is closed, but on_open does
not get that tap. See When the app is closed.
The registration token¶
The FCM registration token identifies this app install. Send it to your server, which sends messages to it with the Admin SDK.
def on_token(token):
save_token_for(Auth.auth().current_user.uid, token)
remove = messaging.add_token_listener(on_token) # at start-up, and on every change
The listener runs when the token is made (at start-up, once the APNs token is
known) and whenever it changes: after a restore to a new device, a reinstall,
or delete_token. Keep the server's copy up to date from it.
messaging.token(lambda token, error: print(token or error.description)) # ask now
messaging.fcm_token # the current one, or None
messaging.delete_token(lambda error: ...) # stop getting messages
Auto-init¶
The token is made at start-up by default. To wait for the user's consent:
FirebaseMessagingAutoInitEnabled = NO in Info.plist, then
messaging.auto_init_enabled = True when they agree (kept across launches).
Topics¶
messaging.subscribe_to_topic("news", lambda error: print("Subscribed" if error is None else error.name))
messaging.unsubscribe_from_topic("news")
Topic names are 1 to 900 letters, digits and - _ . ~ %; an invalid one
raises ValueError. Subscribing needs the token, so it waits until FCM has
one. Send to a topic from the server: messaging.Message(topic="news", ...).
The APNs token¶
Firebase forwards the APNs token to FCM by itself (app delegate swizzling).
With FirebaseAppDelegateProxyEnabled = NO, set it yourself:
from pyios_firebase.messaging import APNSTokenType
messaging.apns_token = device_token # bytes
messaging.set_apns_token(device_token, APNSTokenType.PROD) # with its environment
Registration with the installation ID¶
A newer mode: the app registers with FCM through its Firebase installation
ID instead of a token. Turn it on with
FirebaseMessagingInstallationIdEnabled = YES in Info.plist; the token
methods then fail, and you use:
messaging.installation_id_enabled # True
messaging.add_registration_listener(lambda fid: send_to_my_server(fid))
messaging.register(lambda error: ...)
messaging.unregister(lambda error: ...)
messaging.add_unregistration_listener(lambda fid: tell_my_server(fid))
Several senders¶
To get messages from another Firebase project too:
messaging.retrieve_fcm_token("other-sender-id", lambda token, error: ...)
messaging.delete_fcm_token("other-sender-id")
Delete everything¶
The installation ID stays; turn auto-init off so nothing is registered again at the next start-up.
Errors¶
Errors are MessagingErrors (name from MessagingErrorCode):
MessagingErrorCode |
Means |
|---|---|
NETWORK |
No network |
TIMEOUT |
The server took too long |
AUTHENTICATION |
The project rejected the app (check GoogleService-Info.plist and the API key) |
INVALID_REQUEST |
A bad request (for example no APNs token yet on a device) |
INVALID_TOPIC_NAME |
Not a valid topic |
OPERATION_IN_PROGRESS |
The same operation is already running |