Policy Hub iPhone app

How to set up, build and publish the customer app for iPhone: connect it to your website, brand it, add push notifications and release it on the App Store.

FlutteriPhoneCustomer app

Getting started

Overview

The Policy Hub iPhone app is the companion of the Policy Hub SaaS website. Customers see their policies, pay premiums, file claims, chat with their agent and keep a policy card on their phone.

One app serves every agency on your platform: the customer finds their agency by name, company code or QR code, and signs in. You can also build an own-brand app for a single agency.

What is in the package

Item	What it is
`iphone_app/`	The complete Flutter project for iPhone (source code)
`iphone_app/README.md`	Setup, build, push notification and store publishing steps
`iphone_app/docs/mobile-api.md`	Reference of the customer API the app uses
`lib/`	The app code (screens, API client, session, helpers)
`ios/`	The iPhone project files

Requires the website

This app needs Policy Hub SaaS v1.7 or newer installed on an HTTPS domain. The website is sold separately.

Getting started

Features

Everything a policyholder needs, in one app.

Feature	What it does
Find your agency	Search by name or city, type the company code, or scan the QR code from the agency's website. One app for many agencies.
Sign in	Email and password, or a 6-digit code sent to the customer's email, depending on what the agency allows.
Home	Policies in force, yearly premium, what is owed, late payments, the next renewal, open claims, KYC status and the agent's contact details.
My policies	Every policy with status, cover, insured people, nominees, instalments, payments, documents and a change history. Certificate as a PDF.
Policy cards	A digital card for each policy that opens even with no network (the last copy is kept in the phone's secure storage and removed at sign-out).
Plans	The agency's plans with search and filters, full details, a premium estimator by term (tax included), side-by-side comparison of up to 3 plans, and "I want this plan" which sends the agent a quote request.
Payments due	Late payments, upcoming instalments and policies to renew within 60 days in one place, each with a Pay button. PDF receipts for every payment.
Pay	Opens the agency's secure payment page (Stripe or Razorpay) in the phone's in-app browser. No card details pass through the app.
Claims	File a claim on a policy, see the documents it needs, upload photos or PDFs (up to 10 MB) and follow every status step.
Chat with the agent	Messages to the agency or the customer's own agent, with pictures (shown inline), PDFs and text files up to 5 MB. Call, WhatsApp or email the agent from a bottom sheet.
Ask my agency	Callback, renewal help, quote and nominee change requests, with the agency's reply. Download all personal data, or ask for it to be erased.
Documents (KYC)	Upload an ID photo or PDF and see whether it is approved, in review or not accepted.
Inbox and push	Reminders and updates in an inbox, plus phone notifications when push is set up.
Assistant	Ask questions about their own policies, claims and payments when the agency switches the assistant on.
Refer a friend	Personal referral link and the people referred.
Security and look	Fingerprint or face unlock, dark mode, a list of phones signed in with remote sign-out, change password, sign out of all devices. Several agencies on one phone with Switch company.

Not included

Owner, agent and staff tools. Agencies manage everything on the website; the app is for customers only.
Card payments inside the app. Payment opens the agency's own gateway page.

Getting started

Requirements

Your computer (to build the app)

Flutter (a current stable release whose Dart is 3.13 or newer)
A Mac with Xcode (iPhone apps can only be built on a Mac) and CocoaPods
About 30 GB of free disk space

Phones

iPhone with iOS 15 or newer

Accounts

Apple Developer Program membership (yearly) to publish and to test on a real iPhone
Optional: a Firebase project and an APNs key for push notifications

Website

Policy Hub SaaS v1.7 or newer on https
The agency's website published (the company code is the name in its address, /site/<code>)
Email (SMTP) set up if you want emailed sign-in codes
The cron job running, for reminders and push

Getting started

Install Flutter & Xcode

Install FlutterFollow docs.flutter.dev and add flutter to your PATH.
Install XcodeInstall Xcode from the Mac App Store, open it once to accept the licence, then run sudo xcode-select --switch /Applications/Xcode.app and sudo xcodebuild -runFirstLaunch.
Install CocoaPodssudo gem install cocoapods (or use Homebrew).
CheckRun flutter doctor. Flutter and Xcode should have a green tick.

Prepare the website

Do this once, before you test the app.

Use httpsThe app talks to your website over https. A debug build also accepts plain http for testing.
Publish the agency's websiteUnder Website the agency switches the website on. The company code is the name in the website address.
Open Mobile AppsThe owner's Mobile Apps page shows the QR code, the company code and the page customers use to get the app. The super admin saves the store links there once the app is published.
Run the migrationAfter uploading the website, run php artisan migrate so the chat tables and permissions exist.
Set up emailUnder Settings → Email Settings. It is used for emailed sign-in codes and reminders.
Add the cron line* * * * * cd /path/to/site && php artisan schedule:run >> /dev/null 2>&1 so reminders and push messages go out.
Create a test customerAdd a customer on the website, or let one register online. The customer signs in to the app with the same email and password.

Set up the project

UnzipUnzip policy-hub-iphone-v1.0.0.zip and open the iphone_app folder in Xcode or VS Code.
Get the packagesIn that folder run flutter pub get.
Install the iOS podscd ios && pod install && cd ..
Check the codeOptional: flutter analyze and flutter test.

cd iphone_app
flutter pub get

Run the app

Run on a phone or simulator

Pass your website address when you run or build, so customers never type it.

On the simulator

Start a simulator (open -a Simulator), then run the app. The simulator reaches a website on your Mac as http://localhost/....

flutter run --dart-define=API_BASE_URL=http://localhost/your-folder/main_file

On a real iPhone

Open the projectOpen ios/Runner.xcworkspace in Xcode.
Choose your teamRunner → Signing & Capabilities → pick your Apple Developer team and set your own bundle identifier.
RunConnect the iPhone, trust the computer, then flutter run --dart-define=API_BASE_URL=https://yourdomain.com.

Quick check without a phone

This signs in and out against your website using a customer account and reads the data the app needs:

dart run tool/smoke.dart https://yourdomain.com company-code customer@example.com password

No address given?

Leave API_BASE_URL out and the first screen also asks for the server address. That is handy while testing.

How it works

How customers connect

Way in	How it works
Search	The customer types the agency's name or city.
Company code	The customer types the code (the name in the agency's website address, `/site/<code>`).
QR code	The QR code is on the agency's Get our app page and in its website footer. Scanning it opens the app on that agency; the app asks Connect to <company> at <host>? before it trusts the address.
Link	A `policyhub://connect` link, or a link from the agency's page, opens the app on that agency.

After that the sign-in screen shows the agency's logo and name, and the whole app takes on its colour. A phone can hold several agencies (More → Switch company).

An app for one agency only

Build with the agency's code as well and the app has no company screen:

flutter build ipa --dart-define=API_BASE_URL=https://yourdomain.com --dart-define=COMPANY=company-code

Fixed server

When API_BASE_URL is built in, codes and links cannot point the app to a different server.

How it works

Sign-in & security

Topic	What happens
Sign-in	Email and password, or an emailed 6-digit code when the agency allows it.
Token storage	The sign-in token is kept in the iOS Keychain, not in plain files.
Lock	Under More the customer can turn on Unlock with fingerprint or face. The app asks when it opens and after 30 seconds away. Turning it on asks once, so a lock the person cannot open is never enabled.
Policy cards	The offline copy of the policy cards is kept in secure storage and deleted when the customer signs out.
Signed-in phones	More → Phones signed in lists every phone signed in to the account and can sign any of them out.
Password change	Changing the password signs the app out everywhere. Sign out of all devices is in the app.
First sign-in	A customer created by staff with a typed password is asked to choose their own.
Idle sign-out	An app that is not used for 90 days is signed out (`MOBILE_TOKEN_IDLE_DAYS` on the server).
Update and maintenance	The server can require a minimum app version (`MOBILE_MIN_APP_VERSION`) or show a maintenance message (`MOBILE_MAINTENANCE`).

Customise

Branding & customisation

Changes that need no new build (from the website)

The agency's logo, name and colour: the app takes them from the agency's website settings.
The QR code, company code and store links on the Mobile Apps page.
Whether emailed codes and the assistant are available.

Changes in the code (then build again)

What	Where
App name shown on the phone	`Policy Hub` in `ios/Runner/Info.plist` (`CFBundleDisplayName`)
App id	`com.policyhub.policyHubApp` — change the Bundle Identifier in Xcode (Runner → Signing & Capabilities). Do this before you publish.
Colour	`buildTheme()` in `lib/main.dart` (one seed colour)
Icon and logo	`assets/icon.png`, `assets/icon_foreground.png`, `assets/logo.png`. Replace them, then run `dart run flutter_launcher_icons`.
Version	`version` in `pubspec.yaml` (now `1.0.0+1`) and `AppConfig.appVersion` in `lib/config.dart`

Notifications

Push notifications (Firebase)

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

Create a Firebase projectAt console.firebase.google.com add an iPhone app with your bundle id.
Add the fileDownload GoogleService-Info.plist, put it in ios/Runner/ and add it to the Runner target in Xcode.
APNs keyUpload an APNs key in Firebase (Project settings → Cloud Messaging) and turn on the Push Notifications capability in Xcode.
Connect the serverProject settings → Service accounts → generate a private key. On the server put its path in .env as FCM_CREDENTIALS=/path/key.json.
Check the schedulerThe Laravel cron line must be running; reminders are sent from it.

When customers are notified

Before and after an instalment or renewal is due (reminders)
A payment is received
A claim changes status or needs a document
The agency replies in the chat
A request is answered

Release

Build the release

Set the versionRaise version in pubspec.yaml (for example 1.0.0+1).
SignOpen ios/Runner.xcworkspace in Xcode, pick your team under Signing & Capabilities.
Buildflutter build ipa --dart-define=API_BASE_URL=https://yourdomain.com
UploadUpload the result with Transporter, or Xcode → Window → Organizer → Distribute App.

Release

Publish on the App Store

Developer accountJoin the Apple Developer Program.
Create the appIn App Store Connect add a new app with your bundle identifier.
Test firstUpload the build, add testers in TestFlight and try sign-in, a payment, a document upload and the chat on a real iPhone.
Store listingAdd the name, subtitle, description, keywords, the screenshots for each required iPhone size and the privacy policy link.
App PrivacyFill in the App Privacy answers (see below).
Submit for reviewSelect the build, add review notes with a demo company code and a test customer login, and submit.
Add the link to your websiteCopy the App Store link into the website's Mobile Apps page (super admin).

Review notes

Apple reviewers need a working sign-in. Give them a company code and a customer email and password on a live website.

Release

Privacy & data safety

Use this when you fill in the store forms.

Permissions used

Permission	Why
Face ID (NSFaceIDUsageDescription)	Unlock the app with Face ID
Camera (NSCameraUsageDescription)	Photograph a document or a damaged item
Photo library (NSPhotoLibraryUsageDescription)	Choose a document or picture to send
Push notifications	Show messages (when push is set up)

Data the app handles

Data	Used for	Shared
Name, email, phone	Account and contact with the agency	Only with the customer's own agency
Policy, claim and payment details	Showing policies and handling claims	Only with the customer's own agency
Messages, documents and photos the customer chooses	Chat, claims and KYC checks	Only with the customer's own agency
Device push token (if push is on)	Sending notifications	Firebase Cloud Messaging

Your policy

Describe your own data practices in your privacy policy. The app has no ads and no analytics of its own.

Reference

Settings reference

ios/Runner/Info.plist

CFBundleDisplayName: the app name
The permission texts above
A policyhub URL scheme so a scanned QR code opens the app
Background mode for push messages
Minimum iOS 15.0

Reference

Code structure

Path	What it holds
`lib/main.dart`	App start, theme (light and dark) and routing
`lib/config.dart`	Build-time settings: `API_BASE_URL`, `COMPANY`, version
`lib/push.dart`	Push notification setup
`lib/api/api_client.dart`	Every call to the customer API
`lib/state/session.dart`	Signed-in agencies, tokens, lock, theme, offline policy cards
`lib/screens/`	Company, login, scan, shell (tabs), dashboard, policies, policy detail, policy cards, plans and plan detail, payments due, claims, file a claim, requests, KYC, chat, notifications, assistant, referral, signed-in phones, more, switch company, change password, lock
`lib/util/`	Formatting, files, payment page, picker, QR parsing
`lib/widgets/`	Shared pieces (company logo, confirm dialog, loaders)
`test/`	Unit and widget tests, and a screenshot renderer
`tool/smoke.dart`	Command-line check of the app against your website

The Android project in the other package has identical lib/ code; when you change one, make the same change in the other.

Maintenance

Updating to a new version

Back upKeep your own changes (name, id, icons, colours) somewhere safe.
ReplaceUnzip the new package and copy your changes over it.
Raise the versionIncrease version in pubspec.yaml.
Build and uploadBuild the release again and upload it to App Store Connect.

Update the website to the version the new app needs first.

Help

Troubleshooting & FAQ

Problem	Try this
The app cannot find my agency	Check the company code, that the agency's website is published, and that the address is https and reachable from the phone.
"Could not connect to the server"	Check `API_BASE_URL` (https for release builds) and that the website opens in the phone's browser.
No emailed code arrives	Set up and test Settings → Email Settings on the website, and check the spam folder.
The QR code does not open the app	Install the app first, then scan from inside the app (Scan QR on the first screen).
No push notifications	Check `GoogleService-Info.plist` is in the Runner target, the APNs key is uploaded and Push Notifications is on in Xcode, `FCM_CREDENTIALS` is set on the server and the cron job runs.
Chat or Plans screens are missing	Run `php artisan migrate` on the website, and make sure the customer role has the "use chat" permission.
Customer is asked to change password	They were created with a typed password. They choose their own once and carry on.
Payment page does not open	The agency must have Stripe or Razorpay switched on in the website's payment settings.
Build fails after changing packages	Run `flutter clean`, `flutter pub get` and build again.

Do I need one app per agency?

No. One app serves every agency; the customer picks theirs. You can also build an own-brand app for a single agency.

Can owners and agents use the app?

No, it is for customers. Agencies and agents use the website.

Where is the data stored?

On your website's server. The app keeps the sign-in token, and the offline policy cards, only on the phone.

How do payments work?

The app opens the agency's own payment page in a secure in-app browser. No card details pass through the app.

Can I publish under my own name?

Yes. Change the name, id and icons, then publish with your own Apple Developer account.

Help

Support

Open a ticket at support.smartwebinfotech.com with your purchase code, the app version, what you did and what you saw.

Before you publish

Build and test the app on a real iPhone device against your own website, including sign-in, a payment, a document upload and the chat. Store reviewers will do the same.