diff --git a/backend/feature/notifications/README.md b/backend/feature/notifications/README.md index 96bc5f57a..8c3d8ae12 100644 --- a/backend/feature/notifications/README.md +++ b/backend/feature/notifications/README.md @@ -1,6 +1,6 @@ # Notifications Module -This module provides functionality for sending notifications using Firebase Cloud Messaging (FCM). +This module provides functionality for sending notifications using Firebase Cloud Messaging (FCM) and managing kiosk mode for tablet devices. ## Features @@ -9,6 +9,9 @@ This module provides functionality for sending notifications using Firebase Clou - Send notifications about user modifications - Send notifications about booking modifications - Receive Google Calendar push notifications +- Remote kiosk mode management for tablet devices +- Bulk device operations for kiosk mode control +- Device registration and management ## Setup @@ -26,6 +29,11 @@ To use this module, you need to configure Firebase credentials. There are two wa A sample file is provided, but you should replace it with your actual Firebase credentials. +### Kiosk Mode Configuration + +The kiosk mode functionality uses the existing Firebase configuration from the calendar subscription module. +The kiosk commands are sent to the `kiosk-commands` FCM topic with message type `KIOSK_TOGGLE`. + ## Usage ### Sending Notifications @@ -44,19 +52,127 @@ class YourService( } ``` +### Kiosk Mode Management + +The module provides REST endpoints for managing kiosk mode on tablet devices. The easiest way to use these endpoints is through Swagger UI: + +1. **Access Swagger UI**: Navigate to `https://.../api/swagger-ui.html` +2. **Authenticate**: Click "Authorize" and enter your JWT token +3. **Find Kiosk API**: Look for the "Kiosk" section in the API documentation +4. **Execute Commands**: Use the interactive interface to enable/disable kiosk mode on devices + +#### Available Endpoints + +- `POST /api/v1/kiosk/device/enable` - Enable kiosk mode for specific device +- `POST /api/v1/kiosk/device/disable` - Disable kiosk mode for specific device +- `POST /api/v1/kiosk/all/enable` - Enable kiosk mode for all devices +- `POST /api/v1/kiosk/all/disable` - Disable kiosk mode for all devices +- `GET /api/v1/kiosk/devices` - Get list of all registered devices + ### Receiving Google Calendar Notifications The module provides an endpoint at `/api/notifications` that can be configured as a webhook URL for Google Calendar push notifications. When a notification is received, it will: + 1. Log the notification payload 2. Send an empty message with the topic "booking" +## Kiosk Mode Architecture + +The kiosk mode system consists of several key components: + +### Backend Components + +- **KioskController**: REST API endpoints for kiosk management +- **DeviceService**: Device registration and management +- **INotificationSender**: FCM message sending interface + +### Client Components (Tablet App) + +- **KioskManager**: Android Device Owner kiosk operations +- **KioskCommandBus**: Command flow management +- **KioskLifecycleObserver**: Lifecycle-aware command processing +- **ServerMessagingService**: FCM message reception and processing + +### Command Flow + +1. Administrator sends kiosk command via REST API +2. Backend validates request and sends FCM message +3. Tablet receives FCM message and validates command +4. Device executes kiosk mode operation +5. Command result is logged and processed + +## API Reference + +### Kiosk Management Endpoints + +| Method | Endpoint | Description | Authentication | +| ------ | ------------------------------ | -------------------------------------- | -------------- | +| POST | `/api/v1/kiosk/device/enable` | Enable kiosk mode for specific device | Required | +| POST | `/api/v1/kiosk/device/disable` | Disable kiosk mode for specific device | Required | +| POST | `/api/v1/kiosk/all/enable` | Enable kiosk mode for all devices | Required | +| POST | `/api/v1/kiosk/all/disable` | Disable kiosk mode for all devices | Required | +| GET | `/api/v1/kiosk/devices` | Get list of all registered devices | Required | + +### Request/Response Models + +#### KioskToggleRequest + +```kotlin +data class KioskToggleRequest( + val deviceId: String // Unique Android device ID +) +``` + +#### KioskMessageDto + +```kotlin +data class KioskMessageDto( + val message: String // Success message +) +``` + ## Integration with Other Modules This module depends on: + - User module - Booking module - Workspace module -Make sure these modules are properly configured in your application. \ No newline at end of file +Make sure these modules are properly configured in your application. + +## Troubleshooting + +### Common Issues + +1. **Kiosk Commands Not Working** + + - Verify Device Owner status on target devices + - Check FCM token registration + - Ensure proper Firebase configuration + - **For Android 9+**: Ensure devices were set up as Device Owner immediately after factory reset + - **For modern devices**: Check if manufacturer has additional restrictions or requirements + +2. **Device Not Found Errors** + + - Verify device registration in database + - Check device ID format and validity + - Ensure device has sent registration information + +3. **FCM Messages Not Received** + - Verify Firebase project configuration + - Check network connectivity + - Validate FCM token and topic subscriptions + +### Debugging + +Enable debug logging for notifications and kiosk functionality: + +## Security Considerations + +- All kiosk management endpoints require JWT authentication +- Device commands are validated before processing +- FCM messages are encrypted in transit +- Device Owner privileges are required for kiosk operations diff --git a/clients/README.md b/clients/README.md index 63b3feda4..86a6304ac 100644 --- a/clients/README.md +++ b/clients/README.md @@ -108,3 +108,39 @@ tablet/ ## Responsive Design The applications are designed to work on: - Tablets + +## Kiosk Mode Management + +The tablet application includes comprehensive kiosk mode functionality for remote device management: + +### Features + +- **Remote Control**: Enable/disable kiosk mode via Firebase push notifications +- **Device Targeting**: Support for single device or bulk device operations +- **Android Device Owner**: Full kiosk mode control using Android Device Owner privileges + +### Setup Requirements + +To enable kiosk mode functionality, the tablet must be configured as a Device Owner: + +#### Basic Setup Steps + +1. **Enable Developer Options** on the Android device +2. **Enable USB Debugging** +3. **Connect device via ADB** and run: + ```bash + adb shell dpm set-device-owner band.effective.office.tablet/.AdminReceiver + ``` +4. **Verify Device Owner status**: + ```bash + adb shell dpm list-owners + ``` +#### Troubleshooting Device Owner Setup + +If the basic setup fails: + +1. **Check device compatibility**: Ensure your device supports Device Owner mode +2. **Try factory reset**: Reset the device and try setup immediately after first boot +3. **Remove accounts**: Ensure no Google or other accounts are configured +4. **Check manufacturer documentation**: Some devices have specific setup procedures +5. **Consider enterprise solutions**: For production deployments, consider using Android Enterprise or manufacturer-specific kiosk solutions