Smart Tenant – iPhone App Documentation

Overview

Smart Tenant is the iPhone app for the Smart Tenant property management website. It gives tenants and maintainers (repair staff) everything they need on their phone, while property owners, managers and the owner keep using the website. The app talks only to your website, so all data stays on your server.

What is in the package

Features

Tenant features

Maintainer features

Common to both

• Login with email and password, "Remember me", forgot password, and the 6-digit code when the user has 2-factor login on the website.
• Notifications inbox: bell with unread count on the home screen; tap a notification to open the right screen; "Mark all read".
• Push notifications — see the Push notifications section for the full list of events.
• Dynamic branding: login screen shows the website's logo, name and colours; after sign-in the user's company branding.
• Money and dates are shown in the company's currency and date format (set on the website).
• Server messages (errors, confirmations) follow the user's language on the website. The app's own labels are English; translate them in lib/ if needed.
• Works with large phone font sizes and dark mode.
• Offline-friendly start: remembers the session and branding; shows "No connection" with Retry when the server cannot be reached.

Requirements

Your computer (to build the app)

Phones that can run the app

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

Smart Tenant v3.6 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 app.

1. Website on HTTPS. Install Smart Tenant v3.6+ on your domain with an SSL certificate (Let's Encrypt is free). Release builds of the app 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 and notifications.
3. Find your API address. Sign in as the owner → Settings → Mobile App. The page shows the address the app needs, which is your website address followed by /api/v1, for example https://app.yourdomain.com/api/v1. Open https://app.yourdomain.com/api/v1/app-config in a browser: you should see JSON with your logo and colours.
4. Branding. Settings → General (Application Name, logo, favicon) and the theme colour are used by the app's login screen. Each owner's own General settings and theme are used after their tenants sign in.
5. Accounts to test with. Create (or use) one tenant account and one maintainer account on the website.
6. Cron job. The website's cron (php artisan schedule:run every minute) sends the reminder notifications (rent due, lease and document expiry).
7. Upload size. Photos are sent from the iPhone; set PHP upload_max_filesize and post_max_size to at least 10M.

Set up the project

1. Unzip the package. It contains the iphone_app folder; put it in a path without spaces, for example ~/projects/iphone_app.
2. Choose your bundle identifier prefix: your company's reversed domain, e.g. com.acmehomes. The app's bundle ID becomes com.acmehomes.smartTenant (you can change it in Xcode in the next steps).
   The bundle ID cannot change after the app is created in App Store Connect.
3. Run the setup script in Terminal:

   cd ~/projects/iphone_app
   chmod +x setup.sh
   ./setup.sh com.acmehomes "Acme Homes"
   cd ios && pod install && cd ..

   It creates the ios/ folder and applies everything the app needs:
   • Camera and photo library permission texts
   • Background notifications
   • App name under the icon (CFBundleDisplayName)
   • App icon from assets/icon.png
   • Downloads the Flutter libraries
   You can run it again at any time; it never duplicates settings.
4. Set your website address in lib/config/app_config.dart:

   static const String appName = 'Acme Homes';
   static const String apiBaseUrl = String.fromEnvironment('API_BASE_URL',
       defaultValue: 'https://app.yourdomain.com/api/v1');
   static const String websiteUrl = 'https://app.yourdomain.com';

5. Open the Xcode project — always the workspace:

   open ios/Runner.xcworkspace

How the setup script works

The ios/ folder is not included in the package on purpose: every app needs its own permanent bundle ID, so the folder is created on your computer with yours. setup.sh does this in two steps.

Step 1 — Flutter creates the folder

The script runs Flutter's own command:

flutter create . --org com.acmehomes --project-name smart_tenant --platforms ios

This builds a standard ios/ folder from Flutter's official template with your ID (com.acmehomes.smartTenant). The app's code in lib/ is not touched.

Step 2 — the script adds this app's settings

Flutter's template is generic, so the script then edits the new files:

Result

iphone_app/
  ios/      <- created, with com.acmehomes.smartTenant
  lib/      (unchanged)
  assets/
  ...

• Safe to run again: settings are never added twice. Run it again to change the app name.
• Different ID before publishing: delete the ios/ folder and run the script again with the new ID. After publishing the ID cannot change.
• Next: run cd ios && pod install (shown above). It downloads the iOS libraries the app uses.

Every change is also listed in Manual iOS settings, for reference or to make them by hand.

Xcode signing & capabilities

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: check it, e.g. com.acmehomes.smartTenant. 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 app only uses standard HTTPS encryption.

Run on an iPhone or simulator

Simulator

open -a Simulator
flutter run

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_URL=http://localhost/smart-tenant/main_file/api/v1. iOS blocks plain http:// on real devices unless you add an App Transport Security exception — for real devices, test against an https website.

Sign in with the tenant or maintainer account you created on the website.

Branding & customisation

Changes that need no new build (from the website)

The app checks for changes every time it opens. The look is remembered, so it opens correctly even offline.

Changes in the code (then build again)

The settings file:

class AppConfig {
  static const String appName = 'Acme Homes';
  static const String apiBaseUrl = String.fromEnvironment('API_BASE_URL',
      defaultValue: 'https://app.yourdomain.com/api/v1');
  static const Color brandColor = Color(0xFF2CA58D);     // buttons, links
  static const Color brandDarkColor = Color(0xFF0A2342); // headings, accents
  static const String logoAsset = 'assets/logo.png';
  static const String websiteUrl = 'https://app.yourdomain.com';
}

Push notifications (Firebase + APNs)

Without this step the app works and shows updates in the bell inbox, but iPhones do not get notifications. Apple delivers iPhone notifications through APNs; Firebase connects your website to APNs. The Firebase app settings are pasted on the website: no Firebase file inside the app.

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 app.
2. Add app → iOS: Apple bundle ID exactly as in Xcode (e.g. com.acmehomes.smartTenant) → Register.
3. Download GoogleService-Info.plist. Do not add it to Xcode; skip the remaining SDK steps.
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

1. As the owner: Settings → Mobile App. Open each file in a text editor and paste:
   • the service account key JSON → Firebase service account
   • the GoogleService-Info.plist content → iPhone app (GoogleService-Info.plist)
   Save. A tick appears for each part.
2. On a real iPhone (the simulator has limited push support): close and reopen the app, sign in and tap Allow for notifications.
3. Test: tenant More → Send a test notification (maintainer: Account).

When users are notified

Every notification is also saved in the in-app inbox (the bell), even when phone notifications are off. Each user can switch phone notifications off under More (tenant) or Account (maintainer).

Version numbers

The version is in 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

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-tenant-ios), access: Full.

Build & upload

Make sure apiBaseUrl points to your https website, then:

flutter clean
flutter pub get
cd ios && pod install && cd ..
flutter build ipa --release
# file: build/ios/ipa/*.ipa   (archive: build/ios/archive/Runner.xcarchive)

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: Lifestyle or Business (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: give a demo tenant email and password (and mention a maintainer login in the notes). The demo account must have data (an invoice, a repair, a notice) so the reviewer can see the app working.
• Notes (example): "Smart Tenant is used by tenants and maintenance staff of property management companies. Accounts are created by the property manager on the company's website; there is no in-app sign-up. Rent is paid on the property manager's website (a real-world service). Users can request account deletion by emailing support@yourdomain.com."
• Contact name, phone and email.

5. Submit

Add for Review → Submit. Review usually takes 1–3 days. Choose automatic or manual release after approval.

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 app handles. Publish a privacy policy page on your website 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.
• Users can ask the property manager to delete their account; mention this (with a contact email) in the privacy policy.

iPhone permissions used

Change the texts in ios/Runner/Info.plist (e.g. to translate them).

Manual iOS settings

What setup.sh adds to ios/Runner/Info.plist:

<key>CFBundleDisplayName</key>
<string>Acme Homes</string>
<key>NSCameraUsageDescription</key>
<string>Take photos of problems and finished repairs.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Attach photos of problems and finished repairs.</string>
<key>UIBackgroundModes</key>
<array>
    <string>remote-notification</string>
</array>

Plus in Xcode: Push Notifications capability (creates Runner.entitlements with aps-environment) and the app icon (dart run flutter_launcher_icons).

Code structure

Libraries used: dio, provider, flutter_secure_storage (Keychain), firebase_core, firebase_messaging, flutter_local_notifications, url_launcher, image_picker, path_provider, open_filex, signature, cached_network_image, flutter_launcher_icons.

Updating to a new version

When a new version of the app is released:

1. Back up your project folder (especially ios/, lib/config/app_config.dart and assets/).
2. Update the website first if the release notes say the app needs a newer website version.
3. Replace lib/, pubspec.yaml, setup.sh, docs/ and documentation/ with the new files. Keep your own ios/ folder, your assets/ images and put your values back into lib/config/app_config.dart.
4. Run ./setup.sh com.yourcompany "Your App Name" again (same values as before). It only adds missing settings and never changes your package name or signing.
5. Raise the version in pubspec.yaml (see "Version numbers"), build and upload as usual.

After replacing files run cd ios && pod install.

Troubleshooting

FAQ

Do I need one app per property owner?

No. One app serves all companies on your website; after sign-in it shows the tenant's company branding.

Can owners or managers use the app?

Not in this version. They are directed to the website, which is fully mobile friendly.

Where is the data stored?

Only on your website/server. The phone keeps the login token (in secure storage) and the last branding.

Does the app work without the website?

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

Can I change the API without a new build?

The website address is built into the app. Branding and push settings are not — they come from the website.

How do payments work?

Pay now opens the website's secure payment page (Stripe/Razorpay) in the browser; card data never passes through the app. This is allowed by both stores because rent is a real-world service.

Can I build the iPhone app on Windows?

Not directly. Use a cloud Mac or Codemagic (see Building without a Mac).

Can I publish under my own company?

Yes — your bundle ID, app name, icon and Apple Developer account (enrol as Organization to show your company name).

Do I need the Android version too?

No. This product covers the iPhone app; both use the same website.

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.

Changelog