Flet OneSignal

OneSignal SDK integration for Flet applications.

Flet OneSignal is an extension that integrates the OneSignal Flutter SDK with Flet applications. It provides a complete Python API for:

Push Notifications — send and receive on iOS and Android (OneSignal Docs)
In-App Messages — targeted messages within your app (OneSignal Docs)
User Management — identity, tags, aliases, email, SMS (OneSignal Docs)
Location — geo-targeted messaging (OneSignal Docs)
Outcomes — track actions and conversions (OneSignal Docs)
Live Activities — iOS real-time updates (iOS 16.1+) (OneSignal Docs)
Privacy & Consent — GDPR compliance (OneSignal Docs)
Debugging — log levels and error handling

Requirements#

Component	Minimum Version
Python	3.10+
Flet	0.80.x+

Platform	Minimum Version	Notes
iOS	12.0+	Requires Xcode 14+
Android	API 24 (Android 7.0)+	Requires `compileSdkVersion 33+`

Installation#

Step 1: Install the Package#

# Using UV (Recommended)
uv add flet-onesignal

# Using pip
pip install flet-onesignal

# Using Poetry
poetry add flet-onesignal

Step 2: Configure pyproject.toml#

[project]
name = "my-flet-app"
version = "1.0.0"
requires-python = ">=3.10"

dependencies = [
    "flet>=0.80.5",
    "flet-onesignal>=0.4.0",
]

[tool.flet.app]
path = "src"

Step 3: OneSignal Dashboard Setup (Android)#

Create an account at OneSignal.com, then click + Create > New App.
Enter your App Name, select the organization, choose Google Android (FCM) as the channel, and click Next: Configure Your Platform.
Upload your Service Account JSON file. To generate it, go to the Firebase Console > Project Settings > Service accounts > Generate new private key. See the OneSignal Android credentials guide for detailed instructions. Click Save & Continue.
Select Flutter as the target SDK, then click Save & Continue.
Copy the App ID displayed on the screen and click Done. You will use this ID in your Flet app.

Step 4: iOS Configuration#

Enable Push Notifications capability in Xcode
Enable Background Modes > Remote notifications
Add your APNs certificate to the OneSignal dashboard

Quick Start#

import flet as ft
import flet_onesignal as fos

ONESIGNAL_APP_ID = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"


async def main(page: ft.Page):
    page.title = "My App"

    # Initialize OneSignal
    onesignal = fos.OneSignal(
        app_id=ONESIGNAL_APP_ID,
        log_level=fos.OSLogLevel.DEBUG,
    )

    # Add to page services (required for Flet 0.80.x)
    page.services.append(onesignal)

    # Request notification permission
    permission_granted = await onesignal.notifications.request_permission()
    print(f"Notification permission: {permission_granted}")

    # Identify the user
    await onesignal.login("user_12345")

    page.add(ft.Text("OneSignal is ready!"))


if __name__ == "__main__":
    ft.run(main)

Note

OneSignal is a service, not a visual control. You must add it using page.services.append(onesignal) — not page.overlay.append(onesignal).

Architecture#

The SDK follows a modular architecture that mirrors the official OneSignal SDK:

fos.OneSignal
│
├── .debug              # Logging and debugging
├── .user               # User identity, tags, aliases, email, SMS
├── .notifications      # Push notification management
├── .in_app_messages    # In-app message triggers and lifecycle
├── .location           # Location sharing (optional)
├── .session            # Outcomes and analytics
└── .live_activities    # iOS Live Activities (iOS 16.1+)

Each module provides focused functionality and can be accessed as a property of the main OneSignal instance.

Examples#

Two complete examples are available in the examples directory:

Example App#

Interactive demo with pages for each module — login, notifications, tags, aliases, in-app messages, location, session outcomes and more — built with Flet's declarative UI.

cd examples/flet_onesignal_example
uv sync
uv run python src/main.py

Test Runner#

Automated test app that exercises every SDK method with a single tap and displays real-time results in a checklist + log panel. Useful for validating the integration on a real device after building with fos-build or flet build.

cd examples/flet_onesignal_test
uv sync
fos-build apk          # recommended (injects location module)
# or: uv run python src/main.py   # desktop preview (no location)

Contributing#

Contributions and feedback are welcome!

Fork the repository
Create a feature branch
Submit a pull request with a detailed explanation

For bugs or suggestions, open an issue. Join the community on Discord.

Support the Project#

If you find this project useful, consider giving it a star on GitHub and supporting its development:

GitHub · X · LinkedIn

Try flet-onesignal today and enhance your Flet apps with push notifications!#

Proverbs 16:3

Commit your work to the LORD, and your plans will succeed. Proverbs 16:3