Overview
ClubLink Mobile App is the Android app for the ClubLink SaaS membership website. One app serves everyone: members get their digital card, plans, payments, events, bookings and rewards, while club owners and staff get a dashboard, members, a QR scanner, enquiries, payments and messaging. The app talks only to your website, so all data stays on your server.
What is in the package
| App | Folder | Package name | For |
|---|---|---|---|
| ClubLink | mobile_app/clublink_app/android_app/ | com.clublink.clublink_app | Members, club owners and staff |
Inside the folder:
| Folder / file | What it is |
|---|---|
lib/ | The app's source code (Flutter / Dart): api/, state/, util/, screens/, widgets/, plus main.dart, config.dart and core.dart. |
android/ | The Android project (build files, permissions, icons). |
test/ | Unit and screen tests that run without a server (flutter test). |
tool/ | Makes the store screenshots from sample data (tool/screenshots.sh). |
docs/ | The API contract (openapi.yaml) and screenshots. |
assets/ | The app icon (replace it with your own). |
Features
Members
- Home: membership status and days left, amount due, quick actions, coming events and club news.
- My card: QR code for the door and events, saved on the phone so it works offline; replace the code if it is lost.
- Membership: plans with full details, automatic renewal switch, pause requests, ask the club about a plan change.
- Payments: invoices with instalments and late fees, pay by card, receipt PDF, pay with reward points.
- Events: sign up with guests, waiting list, QR tickets, cancel, rate an event with a photo.
- Book: facilities with day and time slots, my bookings, cancel.
- Rewards: points, share your referral code, history. Family: add, edit and remove family members.
- Messages inbox with push notifications, club news, contact and opening hours, documents upload, notification choices, AI assistant, data export and delete my account.
Owners and staff
- Dashboard: revenue, active memberships, expiring, unpaid, overdue payments and members at risk.
- Members: search, details with call / WhatsApp / email, add and edit members.
- Scan: member card and ticket scanner for the door and event check-in, works offline.
- Enquiries: new / contacted / closed, notes, call and WhatsApp.
- More: record desk payments, create and edit events and facilities, event feedback, message members (email / SMS / WhatsApp), notice board, AI assistant.
Common to everyone
- Sign in with email and password, two-factor code, fingerprint lock, forgot password, change password, sign out of all devices.
- The club's name and colour, dark mode, deep links (
clublink://plan/7...) and push notifications that open the right screen.
Requirements
Your computer (to build the app)
| Item | Needed |
|---|---|
| System | Windows 10/11, macOS or Linux |
| Flutter SDK | Stable channel, Dart 3.13 or newer (sdk: ^3.13.7 in pubspec.yaml) |
| Android Studio | With the Android SDK, platform tools and a recent JDK |
| Free disk space | About 10 GB |
Phones that can run the app
Android 6.0 (API 23) or newer.
Accounts
- Google Play Console developer account (one-time fee) to publish.
- Firebase project (free) if you want push notifications.
- Stripe account if members should pay by card.
Website
ClubLink SaaS v2.0 or newer on HTTPS, with the migrations run (php artisan migrate).
Install Flutter & Android Studio
- Install Flutter from docs.flutter.dev/get-started/install and add it to your PATH.
- Install Android Studio and, in SDK Manager, the latest Android SDK, platform tools and command-line tools.
- Accept the licences and check everything:
Every line for Flutter and Android should have a green tick.flutter doctor --android-licenses flutter doctor
Prepare the website
- Update the website to ClubLink SaaS v2.0 or newer and run
php artisan migrate. This adds the tables the app needs (push devices, event feedback and enquiry notes). - Make sure the site opens on HTTPS and
APP_URLin.envis the real address. - As owner, open Settings & brand under My Website and set the club colour, logo, phone, email, address and opening hours. The app shows them.
- For card payments: under Settings → Payment switch Stripe on and enter the keys.
- For push: see Push notifications, and keep the queue running (see the website documentation, Background work).
- For photos and documents: members can upload documents up to 5 MB and event photos up to 4 MB, so
upload_max_filesize = 8Mandpost_max_size = 16Minphp.iniare enough.
Open the project
The Android project is already included, so there is no setup script. In the app folder:
cd mobile_app/clublink_app/android_app
flutter pub get
The package name is com.clublink.clublink_app. Change it to your own before you publish:
android/app/build.gradle.kts:namespaceandapplicationId- the folder
android/app/src/main/kotlin/…and thepackageline inMainActivity.kt
Change the app name (shown under the icon) in android/app/src/main/AndroidManifest.xml (android:label).
Point the app at your website
Nothing has to be set: the first screen of the app asks for the club's company code (or a scan of its QR code), and the website address comes with the QR code or invite link. Run it like this:
flutter run
To fix the server at build time (so the address is never asked), add --dart-define=API_BASE=https://your-club.example.com/api/v1 --dart-define=WEB_BASE=https://your-club.example.com. For a single-club build that skips the first screen add --dart-define=COMPANY_CODE=<code>. These are read in lib/util/app_config.dart.
Run on a phone or emulator
On a real phone
- Turn on Developer options and USB debugging on the phone and connect it by USB.
- Check
flutter deviceslists it, then run the command above.
On the emulator
Create a virtual device in Android Studio (Device Manager), start it and run the command above. From the emulator your own computer is 10.0.2.2, which is what the default addresses use.
Testing against a local website (http)
Debug builds accept plain http://: on the first screen enter your computer's address, for example http://192.168.1.20/clublink-saas (or http://10.0.2.2/clublink-saas from the emulator). A real phone must be on the same Wi-Fi. Release builds need https.
A test APK to share
flutter build apk --release
The file is build/app/outputs/flutter-apk/app-release.apk. Send it to testers; they must allow installs from unknown sources.
Company code & branding
The app is published once for every club. It starts by asking which club:
- The member scans the club's QR code or pastes its invite link, or types the company code (and the website address if the app has not been given it).
- The app calls
GET /api/v1/company/{code}and shows the club's title, logo, colour and welcome text on the sign-in screen, and keeps showing them after sign-in. - The member signs in with the email and password used on the website. The app sends the company code too, so only that club's accounts get in.
Where the code and look come from (on the website)
- Owner: Communication → Mobile App shows the QR code, company code, invite link and a print-ready poster, and sets the title, logo, colour, welcome text, support contacts and company code. The QR code and store buttons are also on the club's website and on
/join/<code>. - Super admin: Mobile Apps sets the Google Play and App Store links, the minimum app version, a maintenance message and the default look, and switches the app on or off for each club.
Changes appear the next time the app opens. Switch club (More) forgets the club and returns to the first screen.
The app asks to update, or says it is paused
The app sends its version with every request. Below the minimum version the server answers 426 update_required and the app shows an update page with the store link; during maintenance it shows the message (503 maintenance); when the club's app is switched off it says so (403 app_disabled).
Changes in the code (then build again)
- The app icon: replace
assets/icon.pngandassets/icon_foreground.png, then rundart run flutter_launcher_icons. - The default app name and the optional fixed server:
lib/util/app_config.dartand the platform name files described above. - Fonts, screens and wording:
lib/screens/andlib/util/theme.dart.
Card payments
A member taps Pay by card on an unpaid invoice. The server creates a Stripe Checkout page with the club's own Stripe keys, the app opens it, and when the member taps I have paid the server asks Stripe whether it really happened. It only settles the invoice if the payment belongs to that invoice, is paid, covers the amount (late fee included) and has not been used before. Card details are typed on Stripe's page, never in the app.
- Switch Stripe on under Settings → Payment on the website; without it the button explains that card payment is not available.
- Only the newest unpaid invoice for a plan or event can be paid first.
- Other gateways (PayPal, bank transfer ...) stay on the website: the Pay online button opens it.
Push notifications (Firebase)
- Create a project at console.firebase.google.com and add an Android app with your package name.
- Download
google-services.jsonand put it inandroid/app/. - Add the Google services Gradle plugin as described at firebase.google.com/docs/flutter/setup.
- In Firebase open Project settings → Service accounts, generate a private key (a JSON file) and upload it to your server outside the web root.
- In the website's
.envsetFCM_CREDENTIALS=/full/path/to/that-file.json, and keep the queue worker running.
When users are notified
- Members: every message in their inbox (renewal, payment and event reminders, waiting-list offers, payments received, broadcasts).
- Staff: new website enquiries and requests from members.
Tapping a notification opens the right screen. Without these files the app works normally and simply does not push.
AI features
The AI assistant (Ask AI on the member home, the sparkle button on the staff dashboard) uses the AI service the club chose under Settings → AI on the website. Members ask about their own membership, dues and events; owners and staff ask about the club (revenue, overdue payments, members at risk). The assistant only reads data. If AI is off for the club, or the plan does not include it, the app shows a short message instead. The conversation is kept on the phone and can be cleared.
Version numbers
In pubspec.yaml: version: 1.0.0+1. The part before + is the version people see; the number after it is the build number and must go up with every upload to the store. You can also pass them when building: --build-name=1.0.1 --build-number=2.
Signing key (keystore)
Google Play needs every release signed with your own key. Create it once and keep it safe: if you lose it you cannot update the app.
keytool -genkey -v -keystore ~/clublink-upload.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload
Tell the build where the key is
Create android/key.properties (it is git-ignored and must never be shared):
storePassword=YOUR_STORE_PASSWORD
keyPassword=YOUR_KEY_PASSWORD
keyAlias=upload
storeFile=/home/you/clublink-upload.jks
The project already reads this file. Without it a release build is signed with the debug key, which Google Play refuses.
Build the release
flutter build appbundle --release
The file to upload is build/app/outputs/bundle/release/app-release.aab.
Publish on Google Play
- In the Google Play Console create the app (name, language, free or paid).
- Fill in the store listing: short and full description, the icon, a feature graphic and phone screenshots (
docs/screenshots/has ready ones;tool/screenshots.shmakes new ones). - Complete App content: privacy policy address, data safety (see Privacy), content rating, target audience, and the account deletion information (the app has Delete my account under Profile).
- Create a release in Internal testing first, upload the
.aaband test it. - Promote to Production, add release notes and submit for review.
Updates
Raise the build number in pubspec.yaml, build a new bundle and upload it as a new release.
Privacy & data safety
| Data | Why | Where it goes |
|---|---|---|
| Name, email, phone, address, date of birth | The member's profile and login | Your ClubLink server only |
| Photos and documents the user picks | Documents the club asks for, event photos | Your server |
| Card payments | Paying invoices | Card details are typed on Stripe's page; your server stores only the result |
| Push token | Notifications | Your server and Firebase |
The app has no ads and no analytics, and does not track users across apps. Data is encrypted in transit (HTTPS). Members can export their data and delete their account from inside the app.
Android permissions used
| Permission | Used for |
|---|---|
INTERNET | Talking to your website |
CAMERA | Scanning member cards and tickets, taking document and event photos (optional) |
USE_BIOMETRIC | Fingerprint / face lock (optional) |
POST_NOTIFICATIONS | Push notifications (Android 13+) |
Code structure
lib/
main.dart, config.dart, core.dart start-up, app settings, one import for the shared code
api/ API client (token, offline cache), errors, JSON helpers
state/ sign-in session, offline scan queue, push notifications, deep links
util/ theme, formatting, app config (server address)
screens/ member screens, staff screens, login, lock, assistant
widgets/ reusable pieces (buttons, cards, chips, loading and error views)
test/ unit and screen tests (fake server)
tool/ store screenshots
docs/ openapi.yaml and screenshots
android_app and iphone_app share the same lib/. After changing one, run mobile_app/check-sync.sh to be sure the other still matches.
Updating to a new version
- Back up your changes (compare with a git history or copy the folder).
- Copy your own settings (
lib/util/app_config.dart, the icon, the package or bundle id) into the new version. - Run
flutter pub get,flutter testandflutter analyze. - Raise the build number and release as described above.
Troubleshooting
| Problem | What to do |
|---|---|
| "Cannot reach <address>" | The first screen needs the club's website address, which comes with the QR code or invite link. Open the club's Mobile App page using the address members will use (not localhost), and check https://your-site/api/v1/platform opens in the phone's browser. From the Android emulator your computer is 10.0.2.2; a real phone needs your computer's address on the same Wi-Fi. Release builds need https. |
| "We could not find that club" | Check the company code (it is on the owner's Mobile App page) and that the app is switched on for the club under Mobile Apps (super admin). |
| Sign-in says invalid credentials | Use the member or staff login from the website. Super admins cannot use the app. |
| A staff tab is missing | The account lacks the permission. Edit its role on the website. |
| Pay by card says it is not available | Switch Stripe on under Settings → Payment on the website. |
| Push does not arrive | Check the Firebase files, FCM_CREDENTIALS, the queue worker and the phone's notification permission. |
| The scanner shows a black screen | Allow the camera permission. |
| Gradle or SDK errors | Run flutter doctor, accept the licences and update the Android SDK. |
FAQ
Do members and staff need separate apps?
No. It is one app; the account decides which screens appear.
Can the app work without the website?
No. It uses the website's API, so the website must be reachable. The card and recent screens stay available offline.
Can I publish it under my own name?
Yes. Change the package name, the app name and the icon, then publish with your own developer account.
Is a payment taken inside the app?
Yes, by card through Stripe Checkout when the club has switched Stripe on; the server confirms every payment.
Can I give testers the app before it is in the store?
Yes: send a release APK (see Run) or use an Internal testing track.
Support & changelog
Open a ticket at support.smartwebinfotech.com with your purchase code, the app version, what you expected and what happened.
Changelog
Version 1.0.0 – first release: member and staff screens, digital card, payments with card and receipts, events and tickets, facility booking, rewards, family, enquiries, QR scanner with offline queue, push notifications, AI assistant and deep links.