iPhone

ClubLink – iPhone App Documentation

App v1.0.0 · needs website v2.0+

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.

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 and Apple Push (APNs), 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 Face ID / fingerprint lock are supported.

What is in the package

AppFolderBundle idFor
ClubLinkmobile_app/clublink_app/iphone_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.
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

Owners and staff

Common to everyone

Requirements

Your computer (to build the app)

ItemNeeded
SystemA Mac (iPhone apps can only be built with Xcode)
XcodeRecent version from the Mac App Store (includes the iOS SDK and Simulator)
Flutter SDKStable channel, Dart 3.13 or newer
CocoaPodssudo gem install cocoapods (or brew install cocoapods)
Free disk spaceAbout 25 GB

Phones that can run the app

iOS 15.0 or newer (the deployment target in the project).

Accounts

Website

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

Install Xcode & Flutter

  1. Install Xcode from the Mac App Store, open it once and accept the licence. Then run sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer and sudo xcodebuild -runFirstLaunch.
  2. Install Flutter from docs.flutter.dev/get-started/install and add it to your PATH.
  3. Install CocoaPods, then check everything:
    sudo gem install cocoapods
    flutter doctor
    The lines for Flutter and Xcode 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 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

  1. Open ios/Runner.xcworkspace in Xcode.
  2. 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:

  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 + APNs)

A. Apple: APNs key

  1. In your Apple Developer account open Certificates, Identifiers & Profiles → Keys, create a key with Apple Push Notifications service (APNs) enabled and download the .p8 file. Note the Key ID and your Team ID.
  2. In Xcode (Signing & Capabilities) add Push Notifications and Background Modes → Remote notifications.

B. Firebase

  1. Create a project at console.firebase.google.com and add an iOS app with your bundle id.
  2. Download GoogleService-Info.plist and add it to ios/Runner in Xcode (drag it into the Runner group, tick "Copy items").
  3. In Project settings → Cloud Messaging upload the .p8 key with its Key ID and Team ID.

C. Website

  1. In Firebase open Project settings → Service accounts, generate a private key (a JSON file) and upload it to your server outside the web root.
  2. In the website's .env set FCM_CREDENTIALS=/full/path/to/that-file.json, and keep the queue worker running.

When users are notified

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

  1. In App Store Connect choose My Apps → New App, pick iOS, a name, the language, your bundle id and an SKU.
  2. Fill in the listing: description, keywords, support and privacy policy addresses, the category and phone screenshots (docs/screenshots/ has ready ones).
  3. Fill in App Privacy (see Privacy) and the age rating.
  4. 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

  1. Pick the processed build under the app version and add the release notes.
  2. Submit for review (usually 1 to 2 days).

Common rejection reasons and how to avoid them

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.

iPhone permissions used

Key in Info.plistUsed for
NSCameraUsageDescriptionScanning member cards and tickets, taking document and event photos
NSFaceIDUsageDescriptionFace ID lock
NSPhotoLibraryUsageDescriptionChoosing photos and documents to upload
CFBundleURLTypesThe 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

  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; the simulator has no camera.
Pod or signing errorsRun 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.