Job Board SaaS – iPhone App Documentation

Overview

Job Board Recruiter is the iPhone app for the people who run hiring with the Job Board website: owner, HR, recruiters and hiring managers. Candidates keep using your careers website. The app talks only to your website, so all data stays on your server.

What is in the package

Inside the folder:

Features

For the hiring team

• Sign in with the same email and password as on the website; accounts with two-factor sign-in are asked for the 6-digit code. The app is built for your platform, so nobody types a server address. The first time, a person enters a company code (or scans the company QR code or opens an invite link) and sees their company's logo, name and colour.
• Home: key numbers, Needs your attention (waiting candidates, flagged candidates, interviews without a scorecard), summary, coming interviews, latest applicants and the pipeline. Hiring managers see their own jobs and candidates instead.
• Candidates: search names, skills and resume text; filter by stage, flagged or talent pool; long-press to select several and compare (2 to 4) or reject, add to the talent pool or archive in bulk. Add a candidate by hand with the Add button.
• Candidate: profile, AI fit and summary, knock-out flag, screening answers, timeline, comments, call / email / send a template, move stage, rate, talent pool, archive, resume and documents. From here you can also schedule an interview (the candidate is emailed with a calendar file and a video link), write and send an offer and, when AI is connected, score the candidate with AI.
• Interviews: upcoming by day with an Everyone / Mine switch, join the video link, reschedule or cancel, and fill in the scorecard. Past interviews that still need your scorecard are listed on top.
• Jobs with insights, activate / switch off and share links tagged by source; talent-pool matches for a job with one-tap invitations; requisitions (approve / reject); offers (send drafts); all ten reports with a date range.
• AI Assistant: ask about your candidates, jobs and interviews in plain words (when AI is connected). It only reads your data.
• Onboarding checklists of new hires and the Activity log (who did what), for the people with access.
• Notifications: an in-app list with an unread badge, and push messages for new applicants, knock-out flags, offers answered, hiring-manager feedback and interviews.

What each login can do

The app shows only what the signed-in person may use on the website. These are the usual roles; you can change them under Roles & Permissions.

Common

• Every screen follows the user's permissions, exactly as on the website.
• The last good answer of each list is kept, so screens still open without a signal (a banner says so).
• The login token is kept in the phone's secure storage. Signing out removes it and the saved data.
• Branding: the super admin sets the platform name, logo and colour, the store links, the lowest allowed app version and a maintenance message on the Mobile Apps page. Each owner sets their company's app name, description, logo, icon and colour under Integrations → Mobile App, so they change without a new build. The careers website then shows a Get the app section with a QR code. The name and icon under the app on the phone itself are set when you build (see Your own app id).
• Not in version 1.0: creating or editing jobs, a fingerprint / face lock and offline changes (everything you do needs a connection). The app is in English.

Requirements

Your computer (to build the app)

• A Mac with a recent macOS, Xcode (from the Mac App Store) and about 20 GB free disk space. iPhone apps can only be built and signed on a Mac.
• Flutter SDK 3.13 or newer, and CocoaPods (sudo gem install cocoapods).

Phones that can run the app

• iPhone with iOS 13 or newer.

Accounts

• Apple Developer Program (yearly fee) to run on real phones and publish.
• Firebase (free) if you want push notifications; it uses Apple's push service (APNs).

Website

• Job Board SaaS 1.9 or newer on an https address.

Install Xcode & Flutter

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

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

2. Install Flutter: docs.flutter.dev/get-started/install/macos and CocoaPods.
3. Check everything:

   flutter doctor -v

   The Xcode and CocoaPods lines should have a green tick.

Prepare the website

The app talks to your Job Board website through its API. Check these once:

1. Job Board SaaS 1.9 or newer is installed (the API, the super admin's Mobile Apps page and the owners' Mobile App page come with it). After updating run php artisan migrate.
2. https. Phones refuse plain http:// addresses. Install an SSL certificate and set APP_URL=https://your-domain.com in the website's .env.
3. As super admin open Mobile Apps and save the Google Play and App Store links once your app is published, plus the shared push key. Each owner then opens Integrations → Mobile App to set the company's app name, logo, icon and colour. The address the app connects to is set in the app itself (see Set your platform address).
4. Make sure the cron line of the website is set, so interview reminders (and their push messages) are sent.
5. Create the users: Users in the admin panel. Give hiring managers the Hiring Manager role and tick them on their jobs.

Open the project

1. Unzip the package and open the folder recruiter_app/iphone_app in Android Studio or VS Code, or in a terminal.
2. Download the packages:

   cd recruiter_app/iphone_app
   flutter pub get

3. Optional check:

   flutter analyze
   flutter test

   Both should finish without errors. The tests use a pretend server, so they need no internet and no website.

Run on an iPhone or simulator

1. Open ios/Runner.xcworkspace in Xcode once. Under Runner → Signing & Capabilities choose your Team and set a unique Bundle Identifier.
2. Simulator: open -a Simulator, then

   flutter run

3. Real iPhone: connect it, trust the computer, switch on Developer Mode (Settings → Privacy & Security) and run flutter run.

Set your platform address

One app is published for the whole platform and serves every company. The first time, a person enters their company code, scans the company's QR code or opens its invite link (jobboard://join/<code> or https://your-platform/join/<code>). The app then shows that company's logo, name and colour before sign-in, and sign-in is refused for accounts of other companies. The platform may also refuse the app: app disabled (the super admin switched the company off), plan ended, maintenance or update needed (below the lowest version set on Mobile Apps); the app shows the message. Make sure scanning works by keeping the camera permission that is already declared in the project.

Job Board is installed on your own server, so the app is built for it and does not ask people for an address or a company code. You set the address once, before you build:

1. Open lib/config.dart and replace the address in defaultServer with your platform address (the same as APP_URL in the website's .env, https, no slash at the end):

   static const defaultServer = 'https://jobs.yourcompany.com';

2. Or leave the file as it is and give the address when you run or build:

   flutter run --dart-define=SERVER_URL=https://jobs.yourcompany.com
   flutter build ipa --release --dart-define=SERVER_URL=https://jobs.yourcompany.com

3. Run the app. It opens straight on the sign-in page with your company name. Sign in with your email and password (plus the 6-digit code if two-factor is on).

Push notifications (Firebase + APNs)

Optional. Without it the app has its notification list, but no messages on the lock screen.

1. Create a project at console.firebase.google.com and add an iOS app with your bundle id.
2. Download GoogleService-Info.plist and add it to the Runner target in Xcode (drag it into Runner, tick Copy items).
3. In Xcode Signing & Capabilities add Push Notifications and Background Modes → Remote notifications.
4. In the Apple Developer account create an APNs Auth Key (Keys) and upload it in Firebase: Project settings → Cloud Messaging → Apple app configuration.
5. In Firebase open Project settings → Service accounts → Generate new private key and, as super admin, paste the file on the Mobile Apps page under Push notifications (one Firebase project serves every company). An owner can press Send me a test message on Integrations → Mobile App to check.

When people are notified

• A new applicant, and a candidate flagged by a knock-out question.
• An offer accepted or declined.
• An interview scheduled or moved, and a reminder before it starts.

Version numbers

In pubspec.yaml the line version: 1.0.0+1 has two parts: 1.0.0 is what people see, +1 is the build number. App Store Connect rejects a build number it has already seen. Raise both for every update you upload.

Your own bundle id

Set your own Bundle Identifier (for example com.yourcompany.hiring) in Xcode under Runner → General, and use the same id in Firebase and App Store Connect. The name under the icon is CFBundleDisplayName in ios/Runner/Info.plist (currently Job Board). To change the icon, replace assets/icon.png (1024 × 1024) and run dart run flutter_launcher_icons.

Create the app in App Store Connect

1. In App Store Connect choose Apps → + → New App. Pick your Bundle ID (create it first under Certificates, Identifiers & Profiles if needed), a name and a language.
2. Fill in App Information (category, privacy policy URL) and App Privacy (see Privacy & data safety).
3. Prepare screenshots: use the pictures in docs/screenshots/ or capture your own on a simulator.

Build & upload

cd recruiter_app/iphone_app
flutter build ipa --release

The archive is created in build/ios/archive/. Upload it with the Transporter app (drag the .ipa from build/ios/ipa/) or from Xcode: Product → Archive → Distribute App. It appears in App Store Connect under TestFlight after a few minutes.

Publish on the App Store

1. Test the build with TestFlight on a real iPhone.
2. On the app's version page choose the build, add screenshots, description and a test account plus the address of a demo server for the reviewers (the app needs a Job Board to connect to).
3. Press Submit for Review. Apple usually answers in one to two days.

Updates

Raise the version in pubspec.yaml, build and upload again, and attach the new build to a new version.

Privacy & data safety

The app has no analytics or advertising and talks only to your Job Board website (and to Firebase if you switch on push). Use this for the store forms:

You are responsible for your own privacy policy (candidate data is personal data) and for stating where it is stored.

iPhone permissions used

Code structure

lib/
  main.dart                       start-up
  config.dart                     the address of your website (set before building)
  screens/                        every screen (app_root.dart switches between sign in and the app)
  api/                            API client (token, errors, remembered answers)
  state/                          sign-in, secure session storage, cache, push, app scope
  util/                           theme, date and text helpers
  widgets/common.dart             cards, pills, loader with pull-to-refresh, messages
test/                             unit and screen tests against a pretend server
tool/screenshots.sh               makes docs/screenshots/*.png from sample data
docs/openapi.yaml                 the API the app uses

The website address is in lib/config.dart. Colours and the theme are in lib/util/theme.dart (the teal is Brand.teal). The code in lib/ is the same in the Android and iPhone projects; change both, then run mobile_app/check-sync.sh.

Updating to a new version

1. Keep a copy of your changes, your signing key and GoogleService-Info.plist.
2. Unzip the new package, copy your changes over, run flutter pub get, flutter analyze and flutter test.
3. Raise the version in pubspec.yaml and build again.

The app and the website are updated separately. Keep the platform at Job Board SaaS 1.9 or newer; the app uses its API.

Troubleshooting

FAQ

Can one app serve several websites? No. The app is built for one website (yours). To serve another Job Board installation, build a second copy with that address.

Do candidates use this app? No. Candidates use your careers website. This app is for your hiring team.

Is the app free to use once built? Yes. There is no fee for the app itself; you pay the store developer fee and your own hosting.

Can I change the colours and name? Yes, see Your own bundle id and lib/util/theme.dart.

Is the AI assistant in the app? AI fit scores and summaries are shown when AI is connected on the website. The AI assistant chat itself is on the website for now.

Support & changelog

Open a ticket at support.smartwebinfotech.com. Please include your purchase code, the app version (pubspec.yaml) and website version, the output of flutter doctor -v, the exact error or a screenshot, and what you did just before.

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

Changelog