Android

ClubLink – Android App Documentation

App v1.0.0 · needs website v2.0+

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.

One app, role-based screensAfter sign-in the account decides what is shown: members see the member screens, owners and staff the staff screens (each tab only when the account has the permission).
Same rules as the websiteEvery action runs the website's own code: permissions, plan limits, family limits, payment checks and notifications are identical.
Works offline where it mattersThe membership card is saved on the phone, recent screens are cached and gate scans taken without a connection are sent when it returns.
Pay by cardMembers pay unpaid invoices with Stripe Checkout and get a receipt PDF. The server confirms every payment with Stripe before it settles an invoice.
Push notificationsThrough Firebase, configured on the website. Messages also stay in the in-app inbox.
SecureThe login token lives in the phone's secure storage; HTTPS only in release builds; two-factor and fingerprint lock are supported.

What is in the package

AppFolderPackage nameFor
ClubLinkmobile_app/clublink_app/android_app/com.clublink.clublink_appMembers, club owners and staff

Inside the folder:

Folder / fileWhat 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

Owners and staff

Common to everyone

Requirements

Your computer (to build the app)

ItemNeeded
SystemWindows 10/11, macOS or Linux
Flutter SDKStable channel, Dart 3.13 or newer (sdk: ^3.13.7 in pubspec.yaml)
Android StudioWith the Android SDK, platform tools and a recent JDK
Free disk spaceAbout 10 GB

Phones that can run the app

Android 6.0 (API 23) or newer.

Accounts

Website

ClubLink SaaS v2.0 or newer on HTTPS, with the migrations run (php artisan migrate).

Install Flutter & Android Studio

  1. Install Flutter from docs.flutter.dev/get-started/install and add it to your PATH.
  2. Install Android Studio and, in SDK Manager, the latest Android SDK, platform tools and command-line tools.
  3. Accept the licences and check everything:
    flutter doctor --android-licenses
    flutter doctor
    Every line for Flutter and Android should have a green tick.

Prepare the website

  1. 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).
  2. Make sure the site opens on HTTPS and APP_URL in .env is the real address.
  3. As owner, open Settings & brand under My Website and set the club colour, logo, phone, email, address and opening hours. The app shows them.
  4. For card payments: under Settings → Payment switch Stripe on and enter the keys.
  5. For push: see Push notifications, and keep the queue running (see the website documentation, Background work).
  6. For photos and documents: members can upload documents up to 5 MB and event photos up to 4 MB, so upload_max_filesize = 8M and post_max_size = 16M in php.ini are enough.
Members and staff sign in with the same email and password they use on the website. Super admins cannot use the app.

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:

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

  1. Turn on Developer options and USB debugging on the phone and connect it by USB.
  2. Check flutter devices lists 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:

  1. 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).
  2. 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.
  3. 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)

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)

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.

Push notifications (Firebase)

  1. Create a project at console.firebase.google.com and add an Android app with your package name.
  2. Download google-services.json and put it in android/app/.
  3. Add the Google services Gradle plugin as described at firebase.google.com/docs/flutter/setup.
  4. In Firebase open Project settings → Service accounts, generate a private key (a JSON file) and upload it to your server outside the web root.
  5. In the website's .env set FCM_CREDENTIALS=/full/path/to/that-file.json, and keep the queue worker running.

When users are notified

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

  1. In the Google Play Console create the app (name, language, free or paid).
  2. Fill in the store listing: short and full description, the icon, a feature graphic and phone screenshots (docs/screenshots/ has ready ones; tool/screenshots.sh makes new ones).
  3. 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).
  4. Create a release in Internal testing first, upload the .aab and test it.
  5. 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

DataWhyWhere it goes
Name, email, phone, address, date of birthThe member's profile and loginYour ClubLink server only
Photos and documents the user picksDocuments the club asks for, event photosYour server
Card paymentsPaying invoicesCard details are typed on Stripe's page; your server stores only the result
Push tokenNotificationsYour 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

PermissionUsed for
INTERNETTalking to your website
CAMERAScanning member cards and tickets, taking document and event photos (optional)
USE_BIOMETRICFingerprint / face lock (optional)
POST_NOTIFICATIONSPush 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

  1. Back up your changes (compare with a git history or copy the folder).
  2. Copy your own settings (lib/util/app_config.dart, the icon, the package or bundle id) into the new version.
  3. Run flutter pub get, flutter test and flutter analyze.
  4. Raise the build number and release as described above.

Troubleshooting

ProblemWhat 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 credentialsUse the member or staff login from the website. Super admins cannot use the app.
A staff tab is missingThe account lacks the permission. Edit its role on the website.
Pay by card says it is not availableSwitch Stripe on under Settings → Payment on the website.
Push does not arriveCheck the Firebase files, FCM_CREDENTIALS, the queue worker and the phone's notification permission.
The scanner shows a black screenAllow the camera permission.
Gradle or SDK errorsRun 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.