Push

Push registers for remote push and reports tokens and messages. It needs the notifications capability too, so use use = ["notifications", "push"] under [plugins], with notifications = true and remote_notifications = true under [permissions]. See the Push guide.

Remote push: the device token your server needs, and the messages it sends.

Requires the notifications capability, which presents pushes and reports taps. iOS uses APNs. Android uses Firebase Cloud Messaging and needs your project's google-services.json:

[plugins]
use = ["notifications", "push"]

[permissions]
notifications = true
remote_notifications = true

[plugins.push]
google_services_file = "google-services.json"

Without that file an Android app still builds and launches, and get_device_token raises NativeModuleError with the code not_configured.

Example

from pythonnative.push import Push, PushMessage

def handle(message: PushMessage) -> None:
    print(message.title, message.data)

Push.on_message(handle)
Push.on_token(send_token_to_server)

async def register() -> None:
    send_token_to_server(await Push.get_device_token())

Subscribe at the top of your entry module to hear a message that starts the app with no screen, as Python's startup imports that module first.

Classes:

Name	Description
PushMessage	A remote message the app received.
Push	Remote push interface.

PushMessage dataclass

PushMessage(
    title: Optional[str] = None,
    body: Optional[str] = None,
    data: Dict[str, Any] = dict(),
)

A remote message the app received.

Attributes:

Name	Type	Description
title	Optional[str]	The visible title, when it has one.
body	Optional[str]	The visible body, when it has one.
data	Dict[str, Any]	The server's custom keys. FCM delivers every value as a string.

Push

Remote push interface.

Raises:

Type	Description
NativeModuleError	If the native module fails, or with the code plugin_not_enabled when push isn't in the build.

Methods:

Name	Description
get_device_token	Register for remote push and return this device's token.
on_token	Call callback with each new token, so your server stays current.
on_message	Call callback for each remote message the app gets to process.

get_device_token async staticmethod

get_device_token() -> Optional[str]

Register for remote push and return this device's token.

On iOS it's a lowercase hex APNs token, and on Android an FCM registration token. A simulator without APNs access can't get one.

Returns:

Type	Description
Optional[str]	The token, or None off device.

Raises:

Type	Description
NativeModuleError	With the code not_configured on Android when no google_services_file was built in, apns when APNs registration fails or doesn't answer within 30 seconds, or fcm when FCM can't issue a token.

on_token staticmethod

on_token(
    callback: Callable[[str], None],
) -> Callable[[], None]

Call callback with each new token, so your server stays current.

Subscribing registers for remote push on iOS. A token issued before the first subscriber is delivered to it.

Parameters:

Name	Type	Description	Default
callback	Callable[[str], None]	Receives the token string.	required

Returns:

Type	Description
Callable[[], None]	A zero-argument function that unsubscribes.

on_message staticmethod

on_message(
    callback: Callable[[PushMessage], None],
) -> Callable[[], None]

Call callback for each remote message the app gets to process.

• In the foreground, every push.
• In the background, or with no process running, a silent push: one with content-available on iOS, or a data message on Android. The OS shows a visible push by itself and tells the app only if it's tapped, through Notifications.on_response.

A message from before the first subscriber is delivered to it.

Parameters:

Name	Type	Description	Default
callback	Callable[[PushMessage], None]	Receives a PushMessage.	required

Returns:

Type	Description
Callable[[], None]	A zero-argument function that unsubscribes.