Smart Fleet – iPhone App Documentation

Overview

Smart Fleet Mobile Apps are two iPhone apps for the Smart Fleet SaaS vehicle rental and tracking website: Smart Fleet Customer for the people who rent from your owners and Smart Fleet Driver for your drivers. 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

Smart Fleet Customer

Smart Fleet Driver

Common to both

• Sign-in with email and password.
• App code or QR code sign-in with the owner's name, logo and colours.
• Before sign-in the app shows the Smart Fleet (system) logo and name; after sign-in it shows the owner's.
• Update-required and maintenance screens controlled from the website.

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 Fleet 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:

   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 Fleet SaaS v2.0 or newer and run php artisan migrate. This adds the tables the apps need (device tokens, app settings).
2. Make sure the site opens on HTTPS and APP_URL in .env is the real address.
3. As super admin, open Mobile App Console: set the latest and minimum app version, the four store links (customer and driver, Google Play and App Store), maintenance mode, the features that are on and the Firebase key for push. You can also switch the apps off completely.
4. As owner, open Mobile Web App (menu): your app code, logo, colours, welcome text, contact buttons, which tabs customers see, and the QR code to print or share. The same code and QR also appear on your public website.
5. For photos: set upload_max_filesize = 12M and post_max_size = 40M in php.ini (a driver request can carry several 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 the app folder:

cd iphone_app
flutter pub get

The identifiers are com.smartfleet.customerApp (customer) and com.smartfleet.driverApp (driver). Change them to your own before you publish:

• Xcode → Runner → Signing & Capabilities → Bundle Identifier (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. The address ends with /api/v2:

flutter run --dart-define=API_BASE=https://your-domain.com/api/v2

To build an app for one owner only (the code screen is skipped), add that owner's app code:

flutter run --dart-define=API_BASE=https://your-domain.com/api/v2 --dart-define=COMPANY=AB12CD

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 (driver app: also Location updates).

Simulator

open -a Simulator
flutter run --dart-define=API_BASE=https://your-domain.com/api/v2

Camera and push notifications do not work 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 when the 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.
• Logo and mark before sign-in: assets/logo.png and assets/mark.png.
• Default colours: lib/theme.dart (used until an owner is chosen).
• App name under the icon: CFBundleDisplayName in Info.plist.

Push notifications (Firebase + APNs)

Optional. Without it everything works; only the phone pop-ups are missing.

1. Create a project in the Firebase console and add two iOS apps with the bundle identifiers of the Customer and Driver apps.
2. Download each GoogleService-Info.plist and add it to ios/Runner/ in Xcode (tick Copy items if needed and the Runner target).
3. In Apple Developer create an APNs Auth Key (.p8) and upload it in Firebase → Project settings → Cloud Messaging → Apple app configuration.
4. On the website: Firebase console → Project settings → Service accounts → Generate new private key. As super admin open Mobile App Console and paste the whole JSON file into Firebase service-account JSON.
5. In Xcode add Push Notifications and Background Modes → Remote notifications, build again and sign in once.

When users are notified

A push is sent for booking request updates, confirmations, trip start and finish (customers) and for trips assigned or changed by the office (drivers).

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. Also set the same number in lib/config.dart (appVersion) and raise Latest version in Mobile App Console.

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 (Smart Fleet Customer / Smart Fleet Driver or your own), language and a SKU.

Build & upload

flutter build ipa --release --dart-define=API_BASE=https://your-domain.com/api/v2

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 (Travel or 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; tool/screenshots.sh makes sample pictures) and select the uploaded build.
4. App Review information: give a demo account (a client for the Customer app, a driver for the Driver app) and the app 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 app code.
• Missing privacy text: every permission has a description in Info.plist; keep them accurate.
• Payments: rentals are a real-world service paid on the owner's secure web page, which Apple allows.
• Background location (driver app): explain in the review notes that the position is shared only during a running trip.

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 owner to delete their data.

iPhone permissions used

Code structure

lib/
  main.dart, config.dart      start-up, server address and app version
  api.dart                    the API client (token, errors, uploads)
  push.dart                   Firebase push (does nothing until Firebase is set up)
  theme.dart, widgets.dart    colours and shared pieces
  format.dart                 dates and money
  screens/                    every screen (sign-in, home tabs, trip, vehicles, expenses ...)
  tracking.dart, offline_queue.dart   driver app only: GPS sharing and the no-signal queue
test/         unit and screen tests (run offline with a fake server)
tool/         screenshots for the stores (tool/screenshots.sh)
docs/         API list (openapi.yaml) and screenshots

Run the tests with flutter test and the checks with flutter analyze.

Updating to a new version

1. Update the website first (apps work 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, bundle identifier, GoogleService-Info.plist).
3. Run flutter pub get, raise the build number and build again.

Troubleshooting

FAQ

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

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

Can the apps work without the website?

No. They are companions to the Smart Fleet 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. Apple only allows iPhone apps to be built with Xcode on a Mac.

Is a payment taken inside the app?

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

Is there a version without the Smart Fleet logo?

The logo shown before sign-in comes from assets/logo.png and assets/mark.png and the system logo of your website. Replace them with your own.

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