Android Live Progress Demo - Orderly

A demonstration of Android 16's new Progress-Centric Notifications using Expo, React Native, and Firebase Cloud Messaging. This project showcases how to implement real-time, server-driven progress notifications for food delivery workflows.

🚀 What Are Progress-Centric Notifications?

Introduced in Android 16, progress-centric notifications are promoted Live Update notifications that provide users with seamless, glanceable tracking of start-to-end journeys like food delivery, ride-share, or long-running uploads.

Key Features:

• Prominent Display: Appears at the top of notification drawer, on lock screen, and as status chips in system bar
• Real-time Updates: Live progress tracking without constantly reopening the app
• Contextual Information: Rich status updates with progress indicators and critical text
• System Integration: Deep integration with Android's notification system

📱 Project Overview

Orderly is a food delivery demo app that simulates the complete order lifecycle with live progress notifications. Users can place orders and receive real-time updates as their food progresses through different stages.

Order Status Flow:

1. INITIALIZING (0%) - Order received, kitchen preparation
2. FOOD_PREPARATION (25%) - Cooking in progress
3. FOOD_ENROUTE (50%) - Out for delivery
4. FOOD_ARRIVING (75%) - Almost at your location
5. ORDER_COMPLETE (100%) - Delivered and ready

🏗️ Architecture

Core Components

1. Custom Expo Module (modules/progress-centric-notifications/)

• Native Android Implementation: Custom Kotlin module for Android 16 progress-centric notifications
• React Native Interface: TypeScript module providing clean APIs for notification management
• Key Methods:
  • start() - Initialize progress notification
  • update() - Update progress, status, and contextual information
  • cancel() - Dismiss the notification
  • getPermissionsAsync() / requestPermissionsAsync() - Permission management

2. Firebase Integration (firebase/)

• Server-side: Firebase Admin SDK for sending structured FCM messages
• Client-side: React Native Firebase for receiving and processing notifications
• Token Management: Automatic FCM token registration and refresh handling

3. API Routes (app/api/)

• Order Management:
  • POST /api/order - Create new orders
  • GET /api/order/[id] - Fetch order details
  • PATCH /api/order/[id] - Update order status
• FCM Token Registration: POST /api/fcm/token - Register device tokens

4. Notification Handler (notifications/)

• FCM Processing: Parse incoming Firebase messages and trigger native module updates
• Status Mapping: Convert order statuses to user-friendly notifications with progress indicators

🛠️ Technical Stack

Frontend

• Expo SDK 54 with React Native 0.81.1
• Expo Router for file-based routing and API routes
• React Native Firebase for FCM integration

Backend

• Firebase Admin SDK for server-side messaging
• Expo API Routes for local server endpoints
• In-memory storage for demo purposes (orders and FCM tokens)

Native Development

• Expo Modules API for custom native module development
• Kotlin for Android native implementation
• Swift for iOS module structure (placeholder)

📁 Project Structure

├── app/                          # Expo Router app directory
│   ├── api/                      # API routes
│   │   ├── fcm/token+api.ts     # FCM token registration
│   │   └── order/               # Order management endpoints
│   ├── _layout.tsx              # Root layout with FCM setup
│   └── index.tsx                # Main checkout interface
├── modules/                      # Custom Expo modules
│   └── progress-centric-notifications/
│       ├── android/             # Android native implementation
│       ├── ios/                 # iOS module structure
│       ├── src/                 # TypeScript module interface
│       └── expo-module.config.json
├── firebase/                     # Firebase configuration
│   └── index.ts                 # Admin SDK setup and messaging
├── notifications/               # FCM handling
│   └── fcmHandler.ts           # Message processing and parsing
├── services/                    # API service functions
├── types/                       # TypeScript type definitions
├── utils/                       # Utility functions for status mapping
└── android/                     # Android project files

🚀 Getting Started

Prerequisites

• Android Studio Meerkat | 2024.3.1 (or later) - Required for Android 16 QPR2 preview support
• Android 16 QPR2 SDK with "Baklava" system image
• Firebase project with Cloud Messaging (FCM) enabled
• Android 16+ device or emulator for testing progress-centric notifications

Note: Android 16 QPR2 is currently in Beta. Follow the official setup guide to configure your development environment.

Installation

1. Clone and Install Dependencies

   git clone https://github.com/akshayjadhav4/rn-progress-centric-notifications.git
   cd rn-progress-centric-notifications
   npm install

2. Firebase Setup

   • Create a Firebase project and enable Cloud Messaging
   • Download google-services.json and place in project root
   • Set up Firebase Admin SDK service account
   • Add FIREBASE_SERVICE_ACCOUNT_JSON environment variable

3. Android Permissions The app requires these permissions (already configured in app.json):

   • android.permission.POST_NOTIFICATIONS
   • android.permission.POST_PROMOTED_NOTIFICATIONS

4. Set Up Android Project

   npx expo prebuild --platform android --clean

5. Configure Android 16 QPR2 SDK

   Update android/app/build.gradle to use Android 16 QPR2 APIs:

   android {
       compileSdkPreview = "Baklava"
       
       defaultConfig {
           targetSdkPreview = "Baklava"
       }
   }

6. Run the Application

   # Run on Android
   npm run android

Important: Make sure you have the Android 16 QPR2 "Baklava" system image installed in Android Studio's SDK Manager. See the official emulator setup guide for detailed instructions.

🔄 Demo Flow

1. Launch App: Open Orderly and view the checkout interface
2. Place Order: Tap "Checkout" to create a new order
3. Permission Request: Grant notification permissions if prompted
4. Initial Notification: Watch as the first progress notification appears
5. Manual Status Updates: Use the API endpoint to trigger status transitions and observe real-time progress updates

Testing Status Transitions

To test the complete order lifecycle, manually update the order status using the PATCH endpoint:

# Update to Food Preparation (25% progress)
curl --location --request PATCH 'http://localhost:8081/api/order/ord_tcs52t' \
--header 'Content-Type: application/json' \
--data '{
    "status": "FOOD_PREPARATION"
}'

# Update to En Route (50% progress)
curl --location --request PATCH 'http://localhost:8081/api/order/ord_tcs52t' \
--header 'Content-Type: application/json' \
--data '{
    "status": "FOOD_ENROUTE"
}'

# Update to Arriving (75% progress)
curl --location --request PATCH 'http://localhost:8081/api/order/ord_tcs52t' \
--header 'Content-Type: application/json' \
--data '{
    "status": "FOOD_ARRIVING"
}'

# Complete the order (100% progress)
curl --location --request PATCH 'http://localhost:8081/api/order/ord_tcs52t' \
--header 'Content-Type: application/json' \
--data '{
    "status": "ORDER_COMPLETE"
}'

Note: Replace ord_tcs52t with your actual order ID from the checkout response.

📋 API Reference

Order Management

• POST /api/order - Create order with items
• GET /api/order/[id] - Retrieve order details
• PATCH /api/order/[id] - Update order status

FCM Token Management

• POST /api/fcm/token - Register device FCM token

Native Module Methods

• ProgressCentricNotifications.start(title, message, criticalText?)
• ProgressCentricNotifications.update(title, message, status, estimatedTime, progress, criticalText?)
• ProgressCentricNotifications.cancel()
• ProgressCentricNotifications.getPermissionsAsync()
• ProgressCentricNotifications.requestPermissionsAsync()

Note: This project requires Android 16+ for full progress-centric notification functionality. On older Android versions, notifications will fall back to standard notification behavior.

Demo Screenshots