Car Booking SaaS – iPhone Apps Documentation

Overview

Car Booking is a pair of iPhone apps for the Car Booking SaaS – Car Rental Management System website: a Driver app for drivers and a Customer app for renters. Rental company owners and staff keep using the website. The apps talk only to your website, so all data stays on your server.

What is in the package

Features

Driver app

Customer app

Not included

• Paying by card inside the app (payment opens the company's own secure page, so card data never passes through the app).
• Saved cards and in-app language packs.

Requirements

Your computer (to build the apps)

Phones that can run the apps

iPhone with iOS 15 or newer.

Accounts

Enrol as an Organization (needs a D-U-N-S number, the seller name shows your company) or as an Individual (shows your personal name).

Website

Car Booking SaaS v1.7 or newer on HTTPS — see Prepare the website.

Install Xcode & Flutter

1. Xcode: install from the Mac App Store, open it once, accept the licence and let it install components. Then in Terminal:

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

2. Homebrew and CocoaPods (Homebrew from brew.sh):

   brew install cocoapods

3. Flutter: follow docs.flutter.dev/get-started/install/macos (iOS). Add Flutter's bin folder to your PATH (e.g. in ~/.zshrc).
4. Check:

   flutter doctor

   It must show ticks for Flutter and Xcode. (Android Studio is not needed for iPhone.)

Prepare the website

Do this once on the website before building the apps.

1. Website on HTTPS. Install Car Booking SaaS v1.7 or newer on your domain with an SSL certificate (Let's Encrypt is free). Release builds of the apps refuse plain http://.
2. Run the update. If you upgraded an existing website, make sure the database update ran (php artisan migrate --force, or the website's update screen). It creates the tables for phones, notifications, customer sign-in codes and photos.
3. Find your API address. It is your website address followed by /api/mobile/v1, for example https://rent.yourdomain.com/api/mobile/v1. Test it in a browser: https://rent.yourdomain.com/api/mobile/v1/companies?q=a should answer with JSON (a list of companies), and …/api/mobile/v1/company/demo shows one company's name, logo and colour.
4. Online booking for each company. The customer app needs the company's online booking switched on (owner → Online Booking). The company code is the web address name of that page: …/book/demo means code demo. Owners also find the code, a QR code and a "copy message" button under Mobile apps in their menu.
5. Customer sign-in. Customers receive a 6-digit code by email, so the company needs working email settings (Settings → Email). The owner can also allow password sign-in and SMS code sign-in (needs the owner's Twilio account). Each method can be switched on or off by the company.
6. Driver accounts. Create each driver under Driver in the owner's menu. Drivers sign in to the app with that email and password. Set the commission rule on the driver's page to see earnings in the app.
7. Store links (optional but recommended). After publishing, add the Google Play / App Store links as super admin → Mobile apps. They appear on every company's public "Get our app" page (/book/<code>/app) together with the QR code.
8. Cron job and queue. The website's cron (php artisan schedule:run every minute) sends the reminders (pick-up, return, payment). For push notifications keep a queue worker running (php artisan queue:work) or set QUEUE_CONNECTION=sync in .env.
9. Upload size. Photos are sent from the phone: set PHP upload_max_filesize and post_max_size to at least 10M.

Set up the projects

The ios/ folder of both apps is already included, with the permission texts, app name, icons and deployment target applied. There is no setup script.

1. Unzip the package. It contains driver_app, customer_app and docs; put them in a path without spaces, for example ~/projects/iphone_app.
2. Download the libraries for each app:

   cd ~/projects/iphone_app/driver_app
   flutter pub get
   cd ../customer_app
   flutter pub get

   Flutter installs the iOS libraries (CocoaPods) the first time you run or build. If that step ever fails, run cd ios && pod install --repo-update.
3. Set your website address. Either edit lib/config.dart in each app:

   static const String apiBase = String.fromEnvironment(
     'API_BASE',
     defaultValue: 'https://your-domain.com/api/mobile/v1',
   );

   or leave the file as it is and add --dart-define=API_BASE=https://your-domain.com/api/mobile/v1 to every flutter run / flutter build command.
4. Choose your bundle identifier. The placeholders are com.carbooking.driverApp and com.carbooking.customerApp. Change them to your own (for example com.acmerentals.driver) in Xcode (next section) before you create the app in App Store Connect.
   The bundle ID cannot change after the app is created in App Store Connect.
5. Open the Xcode project — always the workspace:

   open ios/Runner.xcworkspace

Xcode signing & capabilities

Do this once for each app. In Xcode select Runner (blue icon, left) → target Runner:

1. Signing & Capabilities tab → tick Automatically manage signing → Team: your Apple Developer team (add your Apple ID in Xcode → Settings → Accounts if the list is empty).
2. Bundle Identifier: set your own, e.g. com.acmerentals.driver. It must be unique in the App Store.
3. Click + Capability → Push Notifications.
4. Click + Capability → Background Modes → tick Remote notifications.
5. General tab → Minimum Deployments: iOS 15.0. Display Name: your app name.
6. Optional (saves a question at every upload): in ios/Runner/Info.plist add <key>ITSAppUsesNonExemptEncryption</key><false/> — the apps only use standard HTTPS encryption.

Run on an iPhone or simulator

Simulator

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

Your iPhone

1. Connect the iPhone with a cable, unlock it and tap Trust.
2. On the iPhone: Settings → Privacy & Security → Developer Mode → on (restart when asked).
3. Run flutter run (or press ▶ in Xcode with your iPhone selected). The first time, on the iPhone go to Settings → General → VPN & Device Management and trust your developer certificate.

Testing against a local website (http)

For quick tests against a website on your Mac (simulator only): flutter run --dart-define=API_BASE=http://localhost/car-booking-saas/main_file/api/mobile/v1. iOS blocks plain http:// on real devices unless you add an App Transport Security exception — for real devices, test against an https website.

Which account to sign in with

Branding & customisation

Changes that need no new build (from the website)

Changes in the code (then build again)

Push notifications (Firebase + APNs)

Without this step the apps work and show updates in the inbox, but iPhones do not get notifications. Apple delivers iPhone notifications through APNs; Firebase connects your website to APNs. You need a Firebase project, one file in each app, and one file on the website server.

A. Apple: APNs key

1. developer.apple.com → Certificates, IDs & Profiles → Keys → +.
2. Name it (e.g. "Push"), tick Apple Push Notifications service (APNs) → Continue → Register.
3. Download the .p8 file (you can download it only once) and note the Key ID and your Team ID (top right of the page).
4. Check Identifiers → your bundle ID has Push Notifications enabled (Xcode does this when you add the capability).

B. Firebase

1. console.firebase.google.com → create a project, or use the one for your Android apps.
2. Add app → iOS, once per app: Apple bundle ID exactly as in Xcode (e.g. com.acmerentals.driver) → Register.
3. Download GoogleService-Info.plist, drag it into Xcode into the Runner folder (tick Copy items if needed and the Runner target). Do this for both apps, each with its own file.
4. Project settings → Cloud Messaging → Apple app configuration → APNs Authentication Key → Upload: the .p8 file, Key ID and Team ID.
5. Project settings → Service accounts → Generate new private key (only once per project; skip if you did it for Android).

C. Website server

1. Save the service account JSON on the website server outside the web folder and put its path in the website's .env:

   FCM_CREDENTIALS=/home/youruser/firebase-service-account.json

   Keep the queue running (php artisan queue:work) or use QUEUE_CONNECTION=sync.
2. Rebuild the apps. On a real iPhone (the simulator has limited push support): sign in and tap Allow for notifications.
3. Test: in the admin panel assign the driver a job; the phone should ring within a few seconds. For the customer app confirm a booking of that customer.

When users are notified

Every message to a customer is also saved in the in-app inbox (the bell), even when phone notifications are off. The company switches push messages on or off under Configuration → Email Notification.

Version numbers

The version of each app is in its pubspec.yaml:

version: 1.0.0+1

• 1.0.0 → CFBundleShortVersionString (the version users see).
• +1 → CFBundleVersion (build number). Every upload to App Store Connect needs a higher build number (for the same version) or a new version.

Create the app in App Store Connect

Do this once for each app (driver and customer).

1. appstoreconnect.apple.com → Apps → + → New App.
2. Platform iOS, name (max 30 characters, must be unique in the App Store), primary language, bundle ID (the one from Xcode), SKU (any internal code, e.g. acme-customer-ios), access: Full.

Build & upload

Make sure the apps point to your https website, then in each app folder:

flutter clean
flutter pub get
flutter build ipa --release --dart-define=API_BASE=https://your-domain.com/api/mobile/v1
# file: build/ios/ipa/*.ipa   (archive: build/ios/archive/Runner.xcarchive)

If you set the address in lib/config.dart, the --dart-define part can be left out.

Upload it with one of:

• Transporter app (free on the Mac App Store): drag the .ipa in → Deliver.
• Xcode: open build/ios/archive/Runner.xcarchive → Organizer → Distribute App → App Store Connect → Upload.
• Command line: xcrun altool --upload-app --type ios -f build/ios/ipa/*.ipa --apiKey <key> --apiIssuer <issuer>

After 5–30 minutes the build appears in App Store Connect → your app → TestFlight.

Alternative: in Xcode choose Any iOS Device (arm64) → Product → Archive → Distribute App.

TestFlight (beta testing)

1. App Store Connect → TestFlight → the build → answer Export compliance ("uses only standard encryption / exempt") if asked.
2. Internal testing: add up to 100 people from your App Store Connect team — available at once.
3. External testing: up to 10,000 testers by email or public link; the first build gets a short beta review (about a day). Add the demo login in "Test information".
4. Testers install TestFlight from the App Store and open your invitation.

Publish on the App Store

1. App information & pricing

• Category: Travel or Business (customer), Business (driver); secondary optional
• Content rights: no third-party content
• Age rating: answer the questionnaire (all "None") → 4+
• Price: Free; choose countries

2. App Privacy

Privacy policy URL and the data types — see Privacy & data safety. Data is "linked to the user", "not used for tracking".

3. Version page

4. App Review information

• Sign-in required: for the driver app give a demo driver email and password; for the customer app give the company code, a test email and how the reviewer gets the sign-in code (use a demo company with password sign-in switched on and a customer that has a password, so the reviewer does not need your email inbox). The demo account must have data (bookings, jobs, photos).
• Notes (example): "Car Booking is used by drivers and renters of car rental companies. Driver accounts are created by the rental company on its website. Customers sign in with a one-time code or password; creating an account is part of the first sign-in. Payment opens the rental company's own secure payment page (a real-world service). Customers can delete their account in Profile → Delete my account."
• Contact name, phone and email.

5. Submit

Add for Review → Submit. Review usually takes 1–3 days. Choose automatic or manual release after approval. Afterwards add the App Store links on the website: super admin → Mobile apps.

Common rejection reasons and how to avoid them

Updates

Raise the version/build in pubspec.yaml, build, upload, create a new version in App Store Connect, select the build, submit.

Building without a Mac

• Codemagic (codemagic.io): connect your Git repository, choose the Flutter workflow, add your App Store Connect API key, and it builds and uploads to TestFlight. Has a free monthly build allowance.
• Cloud Mac rental (MacinCloud, AWS EC2 Mac, …): use it like a normal Mac through remote desktop and follow this guide.
• Signing and capabilities can be set up on developer.apple.com in the browser.

Privacy & data safety

Both stores require a privacy policy URL and a description of the data the apps handle. Publish a privacy policy page on your website (the website's own privacy policy page can be used) and use these answers in App Store Connect → App Privacy:

• Data is encrypted in transit (HTTPS).
• Data is not sold or shared with third parties for advertising.

iPhone permissions used

Change the texts (for example to translate them) in ios/Runner/Info.plist of each app.

iPhone settings reference

What is already set in the ios/ folder of the apps, for reference or when you change something by hand.

ios/Runner/Info.plist

<key>CFBundleDisplayName</key>      <string>Car Booking</string>
<key>NSCameraUsageDescription</key>     <string>Take a photo of your driving licence or ID to speed up pick-up.</string>
<key>NSPhotoLibraryUsageDescription</key> <string>Choose a photo of your driving licence or ID.</string>
<key>NSFaceIDUsageDescription</key>     <string>Unlock the app with Face ID.</string>   <!-- customer app -->
<key>LSApplicationQueriesSchemes</key>  <array> ... </array>                     <!-- customer app: opens tel:, mailto:, https: links -->

Capabilities you add in Xcode

• Push Notifications
• Background Modes → Remote notifications

Deployment target

iOS 15.0 (IPHONEOS_DEPLOYMENT_TARGET in the Xcode project).

Firebase

GoogleService-Info.plist in ios/Runner/ (added to the Runner target). Without it the app runs and push stays off.

Code structure

Both apps

Driver app screens (lib/screens/)

login, home, dashboard, jobs, job_detail, agreements, expenses, earnings, more.

Customer app screens (lib/screens/)

company and scan_code (find a company), login, home, dashboard, cars, car_detail, bookings, booking_detail, booking_photos, documents, rewards, profile, contact, assistant (AI helper), notifications, switch_company. Extra files: app_lock.dart (fingerprint / face / PIN), favorites.dart, cars_filter.dart, settings.dart.

Libraries used: Driver — http, flutter_secure_storage, image_picker, url_launcher, intl, firebase_core, firebase_messaging. Customer — the same plus local_auth (app lock) and mobile_scanner (QR codes). No analytics or advertising libraries.

To add a screen: create it in lib/screens/, load data with the client in lib/api.dart, and add the endpoint on the website in routes/api.php (every endpoint is described in docs/mobile-api.md).

Own-brand customer app

By default the customer app is one app for many companies: the renter finds a company by name, QR code or code. A rental company that wants its own app (its own name, icon and store listing, with no company search) can have a copy built just for it.

From the customer_app folder (needs Python 3 with Pillow: pip install pillow, and Flutter on the PATH for --build):

python3 tools/build_branded.py \
  --company sunrentals \
  --name "Sun Rentals" \
  --logo logo.png \
  --api https://your-domain.com/api/mobile/v1 \
  --package com.sunrentals.app \
  --build none

The result is a copy of the app in build_branded/<company>/. The original is never changed. A company can add its own store links under Mobile apps in its menu; they replace the platform's links on that company's website.

Updating to a new version

When a new version of the apps is released:

1. Back up your project folders (driver_app and customer_app), especially your ios/ edits (signing, GoogleService-Info.plist), lib/config.dart and assets/.
2. Update the website first if the release notes say the apps need a newer website version.
3. Copy the new lib/, pubspec.yaml, test/ and docs/ over your project. Put your own values back into lib/config.dart (or keep using --dart-define=API_BASE=…, which needs no edit).
4. Run flutter pub get.
5. Run cd ios && pod install after replacing the files.
6. Raise the version in pubspec.yaml (see "Version numbers"), build and upload as usual.

Troubleshooting

FAQ

Do I need one app per rental company?

No. One customer app serves all companies on your website: renters find the company by name, QR code or code. A company that wants its own listing can have an own-brand build (Own-brand customer app).

Can owners and staff use the apps?

Not in this version. Owners, managers and staff use the website, which is fully mobile friendly. The apps are for drivers and customers.

Where is the data stored?

Only on your website/server. The iPhone keeps the sign-in token (in the Keychain) and a few settings such as saved favourites.

Does the app work without the website?

No, every screen loads from your website's API.

Can I change the server address without a new build?

No, the address is built into the app (API_BASE). Company name, logo and colours are not built in: they come from the website.

How do payments work?

Pay now opens the company's secure payment page in the browser (Stripe, PayPal, Paystack, Flutterwave or Razorpay); card data never passes through the app. Apple allows this because car rental is a real-world service.

Can I publish the apps under my own name?

Yes — your bundle ID, app name, icon and Apple Developer account.

Do I need a Mac?

Yes, Apple requires a Mac with Xcode to build iPhone apps; see Building without a Mac for cloud options.

Can I give testers the app before it is on the App Store?

Yes: TestFlight.

Can customers delete their account?

Yes: Profile → Delete my account in the customer app.

Support & changelog

Before contacting support, please check the Troubleshooting section and run flutter doctor.

When you contact support, include:

• Your purchase code
• App version (pubspec.yaml) and website version
• Output of flutter doctor -v
• The exact error message or a screenshot
• 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 in support but can be ordered separately. Create a support ticket here.

Changelog