Overview
ClubLink Mobile App is the iPhone 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 | Bundle id | For |
|---|---|---|---|
| ClubLink | mobile_app/clublink_app/iphone_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. |
ios/ | The iPhone 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, Face ID / 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 | A Mac (iPhone apps can only be built with Xcode) |
| Xcode | Recent version from the Mac App Store (includes the iOS SDK and Simulator) |
| Flutter SDK | Stable channel, Dart 3.13 or newer |
| CocoaPods | sudo gem install cocoapods (or brew install cocoapods) |
| Free disk space | About 25 GB |
Phones that can run the app
iOS 15.0 or newer (the deployment target in the project).
Accounts
- Apple Developer Program membership (yearly fee) to run on a device for longer, use TestFlight and publish.
- Firebase project (free) if you want push notifications, and an APNs key from Apple.
- 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 Xcode & Flutter
- Install Xcode from the Mac App Store, open it once and accept the licence. Then run
sudo xcode-select --switch /Applications/Xcode.app/Contents/Developerandsudo xcodebuild -runFirstLaunch. - Install Flutter from docs.flutter.dev/get-started/install and add it to your PATH.
- Install CocoaPods, then check everything:
The lines for Flutter and Xcode should have a green tick.sudo gem install cocoapods 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 iPhone project is already included. In the app folder:
cd mobile_app/clublink_app/iphone_app
flutter pub get
cd ios && pod install && cd ..
The bundle id is com.clublink.clublink_app. Change it to your own in Xcode: open ios/Runner.xcworkspace, select Runner → Signing & Capabilities and edit Bundle Identifier. Change the name shown under the icon with Display Name in ios/Runner/Info.plist (CFBundleDisplayName).
Point the app at your website
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 an iPhone or simulator
Xcode signing
- Open
ios/Runner.xcworkspacein Xcode. - Select Runner → Signing & Capabilities, tick Automatically manage signing and choose your Team.
Simulator
open -a Simulator
flutter run
The simulator has no camera, so the QR scanner and photo capture need a real iPhone. On the simulator your computer is localhost.
Your iPhone
Connect it, trust the computer, turn on Developer Mode (Settings → Privacy & Security) and run flutter run with the same options.
Testing against a local website (http)
Apple blocks plain http:// unless you add an exception to Info.plist. For testing use an https address (a tunnel such as ngrok works) or add an NSAppTransportSecurity exception for your test host and remove it before release.
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 + APNs)
A. Apple: APNs key
- In your Apple Developer account open Certificates, Identifiers & Profiles → Keys, create a key with Apple Push Notifications service (APNs) enabled and download the
.p8file. Note the Key ID and your Team ID. - In Xcode (Signing & Capabilities) add Push Notifications and Background Modes → Remote notifications.
B. Firebase
- Create a project at console.firebase.google.com and add an iOS app with your bundle id.
- Download
GoogleService-Info.plistand add it toios/Runnerin Xcode (drag it into the Runner group, tick "Copy items"). - In Project settings → Cloud Messaging upload the
.p8key with its Key ID and Team ID.
C. Website
- 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 (reminders, waiting-list offers, payments received, broadcasts).
- Staff: new website enquiries and requests from members.
Push does not work on the simulator; test on a real iPhone.
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.
Create the app in App Store Connect
- In App Store Connect choose My Apps → New App, pick iOS, a name, the language, your bundle id and an SKU.
- Fill in the listing: description, keywords, support and privacy policy addresses, the category and phone screenshots (
docs/screenshots/has ready ones). - Fill in App Privacy (see Privacy) and the age rating.
- Give App Review a demo login (a member and an owner or staff account on a demo club).
Build & upload
flutter build ipa --release
Then upload build/ios/ipa/*.ipa with the Transporter app (from the Mac App Store), or choose Product → Archive → Distribute App in Xcode. The build appears in App Store Connect after a few minutes. The build number must go up with every upload.
TestFlight & App Store
TestFlight (beta testing)
In App Store Connect open TestFlight, add internal testers (your team) or external testers by email or public link. External testing needs a short Beta App Review.
Publish on the App Store
- Pick the processed build under the app version and add the release notes.
- Submit for review (usually 1 to 2 days).
Common rejection reasons and how to avoid them
- Demo login missing: give App Review working accounts.
- Account deletion: the app has Delete my account under Profile; mention it in your review notes.
- Permission texts: the camera, photo library and Face ID descriptions are in
Info.plist; keep them honest and specific. - Payments: the app only pays real-world club fees through Stripe, which Apple allows; do not sell digital content inside the app.
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.
iPhone permissions used
| Key in Info.plist | Used for |
|---|---|
NSCameraUsageDescription | Scanning member cards and tickets, taking document and event photos |
NSFaceIDUsageDescription | Face ID lock |
NSPhotoLibraryUsageDescription | Choosing photos and documents to upload |
CFBundleURLTypes | The clublink:// links |
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; the simulator has no camera. |
| Pod or signing errors | Run pod repo update in ios/, then pod install, and choose a Team under Signing & Capabilities. |
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 bundle id, 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: use TestFlight.
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.