Smart DMS – Android app

Install, connect to your website, set up push messages and publish.

1. What you need

Flutter 3.27 or newer (flutter --version) – install guide
Android Studio (Android SDK and a phone or emulator); Windows, macOS or Linux
Your Smart DMS website on HTTPS (plain http works in test builds only)
For the Play Store: a Google Play developer account (one-time fee)

2. First-time set-up

cd android_app
./setup.sh com.yourcompany "Your App Name"

The script creates the android/ folder with your package name and app name, and applies what the app needs: internet, fingerprint and notification permissions, Firebase and release-signing hooks, notification icon and launcher icon. Run flutter doctor if something is missing. Then try it:

flutter run --dart-define=API_BASE=https://dms.yourcompany.com

3. Connect it to your website

The app talks to your Smart DMS website through its mobile API (/api/mobile/v1, described in docs/API.md). Nothing has to be switched on in the website.

One company: give the address when you build: --dart-define=API_BASE=https://dms.yourcompany.com. It is pre-filled on the sign-in screen.
Several websites: leave API_BASE out; people type their website address once.
If the website is in a sub-folder, include it: https://example.com/dms/main_file.

Everyone signs in with the same email and password as on the website (two-factor codes are asked for when switched on). Owners and staff see documents, scanning, approvals and signatures; clients see their documents, uploads and signatures. The super admin uses the website only.

Screen	What it does
Home	What needs attention (approvals, signatures, expiring documents, messages), latest documents, next reminders
Documents	Search, filter by category / expiring, open PDFs and pictures, comments, keep a file on the phone, share it. "+" scans paper, turns photos into a PDF or uploads a file
Tasks	Approve or reject, sign with a finger (choose page and position), decline with a reason
Inbox	Messages from the website; tapping a push message opens the right tab
More	Notification settings, fingerprint / face lock, files saved on the phone, signed-in devices, sign out

4. Push messages (optional)

Create a project at console.firebase.google.com and add an Android app with your package name.
Download google-services.json and put it in android/app/. Rebuild the app.
In Firebase: Project settings → Service accounts → Generate new private key. Store the file on the website's server outside the public folder and set FCM_CREDENTIALS=/path/to/key.json in the website's .env.

Without these files the app still works; messages simply show up in its Inbox instead of as phone alerts.

5. Publish on Google Play

keytool -genkey -v -keystore upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload
cp android/key.properties.example android/key.properties     # fill in passwords; storeFile points at the .jks
flutter build appbundle --release --dart-define=API_BASE=https://dms.yourcompany.com

Upload build/app/outputs/bundle/release/app-release.aab in Play Console (start with Internal testing). Keep the keystore and passwords safe – without them you cannot update the app. Raise the number after + in pubspec.yaml (version: 1.0.0+1) for every upload.

Play asks for: a privacy-policy address (your website's privacy page), screenshots, descriptions, and the data the app handles (account details, documents the person opens or uploads, camera for scanning, push tokens). Give reviewers a demo login. Change the icon by replacing assets/icon.png and assets/icon_fg.png, then dart run flutter_launcher_icons.

6. Problems

Symptom	Try
"The server address does not look right" / "No connection"	Open the address in the phone's browser first. Release builds need https and a valid certificate.
Sign-in says too many attempts	Wait 5 minutes; five wrong passwords lock the sign-in briefly.
Everything fails with a server error	On the website server the web user must be able to write to `storage/` (and the same for the user that runs cron).
No push messages	Check `google-services.json`, `FCM_CREDENTIALS`, the phone's notification permission, and that the person did not switch the message type off under More → Notification settings.
Scanner does not open	The app falls back to the plain camera; update Google Play services.
Gradle download errors	Run the command again; it resumes. Check your internet or proxy.