Skip to content

README.md

Latest commit

 

History

History
218 lines (178 loc) · 5.62 KB

README.md

File metadata and controls

218 lines (178 loc) · 5.62 KB

AmaryPay Server - Event-Driven UI with Firebase Cloud Messaging

Backend server for AmaryPay implementing Event-Driven UI using Firebase Cloud Messaging (FCM).

Event-Driven UI Concept

Event-Driven UI is an architectural pattern where the mobile app UI automatically updates its state based on events/notifications sent from the server. This is similar to the Server-Driven UI or Event Bus concept.

Flow:

  1. Mobile app performs action (e.g., transfer money)
  2. Mobile app calls server API to send data
  3. Server processes data and sends FCM notification to mobile app
  4. Mobile app receives notification and updates UI state automatically
  5. UI refreshes without manual pull-to-refresh

Firebase Setup

1. Create Firebase Project

  1. Open Firebase Console
  2. Create new project or use existing project
  3. Add Android app and iOS app to project

2. Download Service Account Key

  1. In Firebase Console, open Project Settings > Service Accounts
  2. Click Generate New Private Key
  3. Download JSON file
  4. Rename file to firebase-service-account.json
  5. Copy file to server/src/main/resources/firebase-service-account.json

IMPORTANT: Do not commit firebase-service-account.json to git! This file is already in .gitignore.

3. Configure .gitignore

Make sure the following file is in .gitignore:

server/src/main/resources/firebase-service-account.json

API Endpoints

1. Send Notification to Single Device

POST /api/notifications/send
Content-Type: application/json

{
  "deviceToken": "FCM_DEVICE_TOKEN",
  "payload": {
    "eventType": "BALANCE_UPDATED",
    "title": "Balance Updated",
    "body": "Your balance has been updated",
    "data": {
      "newBalance": "1000000",
      "currency": "IDR"
    },
    "priority": "HIGH",
    "silent": false
  }
}

2. Send Notification to Multiple Devices

POST /api/notifications/send-bulk
Content-Type: application/json

{
  "deviceTokens": ["TOKEN_1", "TOKEN_2", "TOKEN_3"],
  "payload": {
    "eventType": "PAYMENT_SUCCESS",
    "title": "Payment Successful",
    "body": "Your payment has been processed",
    "data": {
      "transactionId": "TRX123456",
      "amount": "50000"
    },
    "priority": "HIGH",
    "silent": false
  }
}

3. Send Notification to Topic

POST /api/notifications/send-topic
Content-Type: application/json

{
  "topic": "all-users",
  "payload": {
    "eventType": "NEW_PROMOTION",
    "title": "New Promotion!",
    "body": "Get 50% cashback for all transactions",
    "data": {
      "promoCode": "CASHBACK50",
      "validUntil": "2024-12-31"
    },
    "priority": "NORMAL",
    "silent": false
  }
}

4. Trigger Event (Simplified)

POST /api/notifications/trigger-event
Content-Type: application/x-www-form-urlencoded

deviceToken=FCM_DEVICE_TOKEN
&eventType=BALANCE_UPDATED
&title=Balance Updated
&body=Your balance has been updated
&silent=true
&newBalance=1000000
&currency=IDR

Event Types

Available event types for Event-Driven UI:

Payment Events

  • PAYMENT_SUCCESS - Payment successful
  • PAYMENT_FAILED - Payment failed
  • PAYMENT_PENDING - Payment pending
  • PAYMENT_REFUNDED - Payment refunded

Transaction Events

  • TRANSACTION_CREATED - Transaction created
  • TRANSACTION_UPDATED - Transaction updated
  • TRANSACTION_CANCELLED - Transaction cancelled

Account Events

  • BALANCE_UPDATED - Balance updated
  • ACCOUNT_VERIFIED - Account verified
  • ACCOUNT_SUSPENDED - Account suspended

Notification Events

  • NEW_PROMOTION - New promotion
  • SYSTEM_MAINTENANCE - System maintenance
  • SECURITY_ALERT - Security alert

UI State Events

  • REFRESH_HOME - Refresh home screen
  • REFRESH_TRANSACTIONS - Refresh transaction list
  • REFRESH_PROFILE - Refresh profile
  • UPDATE_BADGE_COUNT - Update badge count

Custom Events

  • CUSTOM_EVENT - Custom event

Development

Run Server

./gradlew :server:run

Build Server

./gradlew :server:build

Test Endpoints

# Health check
curl http://localhost:8080/health

# Test notification (replace with valid device token)
curl -X POST http://localhost:8080/api/notifications/trigger-event \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "deviceToken=YOUR_DEVICE_TOKEN&eventType=BALANCE_UPDATED&silent=true&newBalance=1000000"

Mobile App Integration

Mobile app needs to:

  1. Setup Firebase Cloud Messaging
  2. Get FCM device token
  3. Listen for incoming notifications
  4. Parse eventType from notification data
  5. Update UI state based on event type

Example flow in mobile app:

// When receiving FCM notification
onMessageReceived { remoteMessage ->
    val eventType = remoteMessage.data["eventType"]
    val timestamp = remoteMessage.data["timestamp"]

    when (eventType) {
        "BALANCE_UPDATED" -> {
            val newBalance = remoteMessage.data["newBalance"]
            // Update UI state
            viewModel.updateBalance(newBalance)
        }
        "PAYMENT_SUCCESS" -> {
            // Navigate to success screen
            // Refresh transaction list
        }
        // ... handle other events
    }
}

Security Notes

  1. Do not commit firebase-service-account.json to repository
  2. Use environment variables for production
  3. Implement authentication for API endpoints
  4. Validate device tokens before sending notifications
  5. Rate limiting to prevent spam

Resources