Skip to content

Home

Jump to bottom
Fabian edited this page Jan 30, 2025 · 8 revisions

Android-Notify Wiki

Welcome to the Android-Notify Wiki! This documentation serves as a comprehensive guide to help you understand, configure, and utilize the library effectively.

📚 Table of Contents

  1. Introduction
  2. Getting Started
  3. Notification Styles
  4. Advanced Features
  5. Permission Management
  6. Error Handling
  7. Best Practices
  8. Contribution Guide
  9. FAQs
  10. Troubleshooting

📖 Introduction

Android-Notify is a Python library for creating and managing Android notifications in Kivy Android applications. It simplifies the process of sending customized notifications with various styles while handling Android-specific nuances.

Key Features:

  • Easy to integrate and configure.
  • Multiple notification styles.
  • Handles notification permissions automatically.
  • Suitable for both small and large-scale apps.

🚀 Getting Started

Installation

Ensure you have the following in your buildozer.spec file:

requirements = python3, kivy, pyjnius, android-notify
android.permissions = POST_NOTIFICATIONS
android.gradle_dependencies = androidx.core:core:1.6.0, androidx.core:core-ktx:1.15.0
android.enable_androidx = True

Install via pip:

pip install android-notify

Basic Usage

from android_notify import Notification

notification = Notification(
    title='Hello',
    message='This is a basic notification.'
)
notification.send()

Sample Image:
basic notification img sample

🎨 Notification Styles

Supported Styles

  1. Simple: Basic notification with title and message.
  2. Progress: Display progress updates.
  3. Big Text: Expandable notification for long text.
  4. Inbox: Multiple-line notifications.
  5. Big Picture: Notifications with images.
  6. Large Icon: Custom icons in notifications.
  7. Both Imgs - Combines big picture and large icon.
  • Use from android_notify import NotificationStyles to safely get style names.

Progress-Bar Style

A Notification with moving progress-bar.

notification = Notification(
    title='Downloading...',
    message='0% complete',
    style=NotificationStyles.PROGRESS, # progress
    progress_max_value=100,
    progress_current_value=0
)
notification.send()

Sample Image: progress img sample

Big Text Style

A Notification that acts as a email having a title and main message, When dropdown button clicked then main message replaces title

notification = Notification(
    title="Article",
    subject="Histroy of Loerm Ipsuim"
    message="Lorem Ipsum is simply dummy text of the printing and ...",
    style=NotificationStyles.BIG_TEXT # big_text
)

big_text img sample

Inbox Style

A Notification with multipule-lines, use the newline-escape to indicate \n

notification = Notification(
    title='Inbox Notification',
    message='Line 1\nLine 2\nLine 3',
    style=NotificationStyles.INBOX # inbox
)
notification.send()

Sample Image: Inbox Notification sample

Images

  • You can Use Local Or Online
  1. Online Images
    • Make Sure you have permission to use INTERNET, In your buildozer.spec set android.permissions = POST_NOTIFICATIONS, INTERNET
    • All Online Images should inputted with full URL (start with https:// or http://)
  2. Local Images
    • All local Images should be sub relative to your main.py (images should be in App's Folder)

Large-Icon Style

A Notification with a large icon at the right side.

notification = Notification(
    title="FabianDev_",
    message="A twitter about some programming stuff",
    style=NotificationStyles.LARGE_ICON, # large_icon
    large_icon_path="assets/imgs/profile.png"
)
notification.send()

Sample Image:
large_icon img sample

Big-Picture Style

A Notification with a large icon at the right side.

notification = Notification(
    title='Picture Alert!',
    message='This notification includes an image.',
    style=NotificationStyles.BIG_PICTURE, # big_picture
    big_picture_path="assets/imgs/photo.png"
)
notification.send()

Sample Image: big_picture img sample

For Both Imgs Style

A Notification with a large icon and big picture.

notification = Notification(
    title='MovieUpdates_007',
    message='Movie Update: SANDMAN just got renewed',
    style=NotificationStyles.BOTH_IMGS, # both_imgs
    large_icon_path="assets/imgs/profile.png",
    big_picture_path="assets/imgs/photo.png"
)
notification.send()

⚙️ Advanced Features

  • Update Notifications: Dynamically change the title or message.
  • Silent Notifications: Notifications without sound or alerts.
  • Channel Management: Organize notifications into channels.

Updating Notifications

notification = Notification(title="Initial Title")
notification.send()

# Update title
notification.updateTitle("New Title")

# Update message
notification.updateMessage("New Message")

Progress Bar Management

notification = Notification(
    title="Download..",
    style="progress"
)

# Update progress
notification.updateProgressBar(30, "30% downloaded")

# Remove progress bar
notification.removeProgressBar("Download Complete")

Example: Silent Notification

This won't show up before entering notification Tray.

notification = Notification(
    title='Background Update',
    silent=True
)
notification.send()

Channel Management

Notifications are organized into channels, Custom Channel Name's Gives User ability to turn on/off. You can customize the channel name and ID:

  • Try to constitent in Channel name strings, Don't input channel_id to avoid Human Error.
  • Custom Channel Name's Gives User ability to turn on/off specific
notification = Notification(
    title="Download finished",
    message="How to Catch a Fish.mp4",
    channel_name="Download Notifications",  # Will create User-visible name "Download Notifications"
    channel_id="downloads_notifications"  # Optional: specify custom channel ID
)

Sample Image:
channels img sample

🔑 Permission Management

  • Ensure android.permissions = POST_NOTIFICATIONS permission is declared.
  • Ensure android.permissions = INTERNET permission is declared, For Online Images in Notification.
  • Verify notification settings in the Android system UI.

🛠️ Error Handling

  • Missing image files will print all visible files.
  • Invalid style names suggest alternatives.
  • Invalid arguments display valid options.

🌟 Best Practices

  • Use from android_notify import NotificationStyles to get style names.
  • Use meaningful channel names.
  • Test across multiple Android versions.
  • Avoid frequent updates for progress notifications.

🤝 Contribution Guide

We welcome contributions! Follow these steps:

  1. Fork the repository.
  2. Create a new branch.
  3. Make your changes.
  4. Submit a pull request.

❓ FAQs

  • Q: Does it work on non-Android devices?
    • A: No, it’s designed specifically for Android.
  • Q: How do I debug notifications?
    • A: Enable logs with Notification.logs = True.

🐞 Troubleshooting

  • Enable logs for debugging.
  • Verify paths to image files.
  • Check Android notification settings.

📬 Support

For further assistance, feel free to open an issue on our GitHub Issues page.

Happy coding! 🚀

Clone this wiki locally