Smart FSM – iPhone App Documentation

Overview

Smart FSM Mobile Apps are two iPhone apps for the Smart FSM SaaS field service website: FSM Technician for your field team and FSM Client for your customers. Owners, managers and the super admin keep using the website. The apps talk only to your website, so all data stays on your server.

What is in the package

Inside each folder:

Features

FSM Technician

FSM Client

Common to both

• Sign-in with email and password, two-factor code, and biometric lock.
• Company code, QR code and invite-link sign-in with the company's branding.
• Inbox, profile, password change, offline queue.

Requirements

Your computer (to build the app)

Phones that can run the app

iPhone with iOS 15 or newer.

Accounts

• Apple Developer Program membership (yearly fee) to run on a real iPhone for more than a week and to publish.
• Firebase project (free) for push notifications, and an APNs key from Apple.

Website

Smart FSM SaaS v2.0 or newer on HTTPS, with the migrations run.

Install Xcode & Flutter

1. Install Xcode from the Mac App Store, open it once and accept the licence. Then:

   sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -runFirstLaunch

2. Install Flutter from docs.flutter.dev and CocoaPods.
3. Check everything:

   flutter doctor

   Flutter and Xcode should show green ticks.

Prepare the website

1. Update the website to Smart FSM SaaS v2.0 or newer and run php artisan migrate. This adds the tables the apps need (tokens, devices, job notes, request photos).
2. Make sure the site opens on HTTPS and APP_URL in .env is the real address.
3. As super admin, open Mobile Apps and fill in the store links and the minimum app version. You can also switch the apps off for one company or for maintenance.
4. As owner, open Settings → Branding & Mobile App: set the company code, logo and colour. Your invite link, QR code and store buttons appear on your public website.
5. For photos: set upload_max_filesize = 12M and post_max_size = 40M in php.ini (a request can carry 5 photos).

Open the project

Unlike a bare Flutter source package, the iPhone project is already included, so there is no setup script. Unzip, then in each app folder:

cd technician_app/iphone_app      # or client_app/iphone_app
flutter pub get

The identifiers are com.smartfsm.fsmTechnician and com.smartfsm.fsmClient. Change them to your own before you publish (Xcode → Runner → Signing & Capabilities → Bundle Identifier):

• Xcode: Runner target and RunnerTests target
• The app name under the icon: CFBundleDisplayName in ios/Runner/Info.plist

Point the app at your website

Give the website address when you build; it is then fixed in the app:

flutter run --dart-define=API_BASE_URL=https://your-company.example

If you leave it out, the sign-in screen asks for the server address, which is handy while testing.

Run on an iPhone or simulator

Xcode signing

1. Run flutter pub get, then cd ios && pod install.
2. Open ios/Runner.xcworkspace (not the .xcodeproj) in Xcode.
3. Select Runner → Signing & Capabilities, tick Automatically manage signing, choose your Team and set your own Bundle Identifier.
4. Add the capabilities Push Notifications and Background Modes → Remote notifications.

Simulator

open -a Simulator
flutter run --dart-define=API_BASE_URL=https://your-company.example

Camera, push notifications and Face ID do not work fully in the simulator.

Your iPhone

Connect it, trust the computer, turn on Developer Mode (Settings → Privacy & Security) and run flutter run. The first time, trust your developer certificate under Settings → General → VPN & Device Management.

Testing against a local website (http)

Debug builds accept plain http:// (use your Mac's address, for example http://192.168.1.20/…). Release builds require HTTPS.

Company code & branding

Changes that need no new build (from the website)

The app sends X-App-Version; the website answers 426 update_required below the minimum version, 503 maintenance during maintenance and 403 app_disabled when the company's apps are switched off.

Changes in the code (then build again)

• App icon: replace assets/icon.png and assets/icon_foreground.png, then dart run flutter_launcher_icons.
• App name under the icon: CFBundleDisplayName in ios/Runner/Info.plist.
• Default brand colour: defaultBrandColor in lib/util/theme.dart (used until a company is chosen).
• Invite links that open the app: fsmtech://join/<code> and fsmclient://join/<code> work out of the box. To make normal https://your-server/join/<code> links open the app too, add the Associated Domains capability (applinks:your-server) and an apple-app-site-association file at /.well-known/.

Push notifications (Firebase + APNs)

Optional. Without it everything works and the in-app inbox still fills up; only the phone pop-ups are missing.

A. Apple: APNs key

Apple Developer → Certificates, Identifiers & Profiles → Keys → create a key with Apple Push Notifications service (APNs). Download the .p8 file and note the Key ID and Team ID.

B. Firebase

1. In the Firebase console add two iOS apps with the bundle identifiers of the Technician and Client apps.
2. Download each GoogleService-Info.plist and add it to ios/Runner in Xcode (tick Copy items if needed).
3. Project settings → Cloud Messaging → upload your APNs key (.p8) with Key ID and Team ID.

C. Website

Firebase console → Project settings → Service accounts → Generate new private key. Save the JSON on the server and set in .env:

FCM_CREDENTIALS=/full/path/to/service-account.json

When users are notified

A push is sent for every inbox item: job assigned or changed, estimate or invoice created, technician arrived, job completed. Phones that no longer exist are removed automatically.

AI features

The AI features in the apps (AI plan for the day, tidy up notes, photo check) use the AI service the owner connects on the website under Settings → AI (OpenAI, Anthropic Claude, Google Gemini or any compatible service). The key is stored encrypted on the server; the app never sees it.

• AI follows the subscription plan: if the plan has no AI, the AI buttons are hidden.
• There is a daily request limit per company.
• The photo check needs an AI service that can read pictures.

Version numbers

Set the version in pubspec.yaml: version: 1.0.0+1. 1.0.0 is the version people see; +1 is the build number. Increase the build number for every upload to App Store Connect.

Create the app in App Store Connect

1. Apple Developer → Identifiers: register your bundle identifiers (or let Xcode do it).
2. App Store Connect → Apps → + → New App. Choose the bundle identifier, name (FSM Technician / FSM Client), language and a SKU.

Build & upload

flutter build ipa --release --dart-define=API_BASE_URL=https://your-company.example

Then open build/ios/archive/Runner.xcarchive in Xcode (Window → Organizer) and choose Distribute App → App Store Connect → Upload, or use the Transporter app with the .ipa. Do this for both apps.

TestFlight (beta testing)

After processing, the build appears in App Store Connect → TestFlight. Add internal testers (up to 100, no review) or external testers (short Apple review).

Publish on the App Store

1. App information & pricing: category (Business), privacy policy URL, price (free).
2. App Privacy: describe the data the app collects (see Privacy & data safety).
3. Version page: description, keywords, support URL, screenshots (6.9" and 6.5" sizes; the tool/screenshots.sh script makes sample pictures) and select the uploaded build.
4. App Review information: give a demo account (employee for the Technician app, client for the Client app) and the company code, so the reviewer can sign in.
5. Submit for review.

Common rejection reasons and how to avoid them

• Reviewer cannot sign in: always provide a working demo account and company code.
• Missing privacy text: every permission has a description in Info.plist; keep them accurate.
• Payments: invoices are paid for a real-world service on the company's secure web page, which Apple allows.

Privacy & data safety

You publish the apps, so you are responsible for the store forms. What the apps handle:

All data is sent to your website over HTTPS. The apps contain no ads and no third-party analytics. Users can ask the company to delete their data.

iPhone permissions used

Code structure

lib/
  main.dart, config.dart, core.dart   start-up, app settings, one import for the shared code
  api/        API client, repositories and models (jobs, invoices, users ...)
  state/      sign-in, offline queue, cache, connectivity, push, local database
  util/       theme, formatting, GPS helper, app config
  screens/    every screen (home, jobs, billing ... plus login, lock, inbox and More)
  widgets/    reusable pieces (shell with bottom bar, cards, signature pad, media picker)
test/         unit and screen tests (run offline with a fake server)
tool/         screenshots for the stores (tool/screenshots.sh)
docs/         API contract (openapi.yaml) and screenshots

The Android and iPhone projects of the same app share the same lib/. If you change one, make the same change in the other. mobile_app/check-sync.sh tells you if they drifted apart. Run the tests with flutter test and the checks with flutter analyze.

Updating to a new version

1. Update the website first (apps are only compatible with a website of the same or a newer version).
2. Back up your own changes, unzip the new package and copy your changes back (lib/, icon, package name, GoogleService-Info.plist, signing settings).
3. Run flutter pub get, raise the build number and build again.

Troubleshooting

FAQ

Do I need to publish a separate app for each company?

No. One build of each app serves every company; people choose theirs with the company code.

Can the apps work without the website?

No. They are companions to the Smart FSM SaaS website and use its API.

Can I publish the apps under my own name?

Yes: your package name, app name, icon and store account.

Do I need a Mac?

Yes, iPhone apps can only be built with Xcode on a Mac (or a cloud Mac service).

Can I give testers the app before it is in the store?

Yes: TestFlight.

Is a payment taken inside the app?

No. The app opens the company's secure payment page in the browser; card data never passes through the app.

Support & changelog

Before contacting support, check Troubleshooting and run flutter doctor -v.

When you contact support, include: your purchase code, the app version (pubspec.yaml) and website version, the output of flutter doctor -v, the exact error message or a screenshot, and what you did just before the problem.

Support covers installation questions, bugs and help with the steps in this guide. Customisations (new features, design changes) are not included but can be ordered separately.

Changelog