Push notifications

Push notifications let a server alert a device about new information, even when the app is not in the foreground. The app registers with a provider, shares its device token with the server, and handles incoming messages or notification taps.

Add to your app

cargo add 'day-part-push@0.*'

Use the Day CLI to stage the native integrations and permission metadata. Configure the app’s Apple capabilities or Firebase client resources as described below. Keep sender credentials on the server.

API reference · Source and demo.

Choose providers

Cargo featureProvider cratePlatform
ios-apns (default)day-part-push-ios-apnsiOS / UIKit
android-fcm (default)day-part-push-android-fcmAndroid / Material with Google Play services
relayOptional client for the demo relayA configured HTTPS relay

Each native provider is restricted to its target OS. Desktop, web, and HarmonyOS do not have native providers in this package.

For an Android application that excludes Google dependencies:

[dependencies]
day-part-push = { version = "0.*", default-features = false, features = ["ios-apns"] }

This excludes the FCM provider, Firebase dependency, messaging service, and Java bridge from Android. Android push remains unsupported until another provider is added. Cargo features are additive: another dependency enabling android-fcm enables it for the app. Inspect the final APK as well as the Cargo graph. The demo’s fdroid flavor demonstrates dependency exclusion; a microG-specific provider is not implemented.

Register and handle events

Subscribe with watch before requesting permission and registering. Keep its returned watch while events are needed.

use day_part_push::{self as push, Event};

async fn register() -> Result<push::Watch, push::Error> {
    let watch = push::watch(|event| match event {
        Event::Token { token } => {
            // Send this token to your app server over HTTPS, including rotations.
            let _ = token;
        }
        Event::Message { payload, opened } => {
            // Hand data to the UI through a Day Setter; opened identifies a tap.
            let _ = (payload, opened);
        }
        Event::Error { message } => { let _ = message; }
    })?;
    push::request_permission().await?;
    push::register().await?;
    Ok(watch)
}

register starts native registration. Token events carry the result and later rotations; a device token can change without the user signing out. Treat tokens as installation-specific delivery addresses, not account identities.

Callbacks run on native delivery threads and must return promptly. Send values through a Setter, then format localized text on the UI thread. Events are serialized for each subscriber. A new subscriber receives the last token and up to 32 recent messages or errors, including taps received before its page opened. Dropping the watch unsubscribes; an executing callback may finish.

unregister stops native registration and clears the cached token. Remove the installation from your server as well.

Native configuration

PlatformSetup and delivery behavior
iOS / UIKitEnable Push Notifications for the app identifier and provision it with that capability. Include aps-environment in signing entitlements. Development tokens use the APNs sandbox; distribution tokens use production.
Android / MaterialRegister the exact application ID in Firebase and provide its client resources. Foreground messages reach the app; background notification payloads are displayed by the OS and returned when tapped.

On iOS, the provider shares Day’s notification delegate with local notifications. Silent-push background execution and notification service extensions are outside this API. See Apple’s remote notification registration guide.

On Android, supply google_app_id, gcm_defaultSenderId, google_api_key, and project_id in Android XML resources under platform/android/res/values/. The provider reads these with Firebase’s resource-based configuration; the Google Services Gradle plugin is not required. These values are client configuration, not the service-account private key. Automatic messaging initialization stays disabled until registration. See Firebase’s Android client setup.

OS background limits, permissions, connectivity, and force-stop affect delivery. Provider acceptance of a send does not establish that the device received or displayed it.

Demos and automated checks

Push Lab exposes registration, token changes, and incoming events. Configure its identifier, dev.daybrite.push.demo, separately from Day-Showcase. The portable walkthrough checks UI controls without requiring a provider account.

The repository also contains a Cloudflare Worker relay for Day-Showcase. Any installation can register its device token and receives a per-device credential; registrations are limited per network and expire after a week without use. Device sends carry a fixed sample notification, and only the relay’s administrator chooses other text. The relay stores registrations in D1 and sends through APNs or FCM. Sender keys stay in Worker secrets; the app stores its device credential in the keychain. See the relay guide.

CI tests the Rust workspace, the relay with synthetic credentials, and both Android flavors. An APK audit checks that the Google-free build contains neither Firebase nor Google Play services. On-device delivery tests remain separate from those checks.