Job Board SaaS – Android App Documentation

Overview

Job Board Recruiter is the Android 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)

• Windows, macOS or Linux with 8 GB RAM or more and about 10 GB free disk space.
• Flutter SDK 3.13 or newer (includes Dart), and Android Studio with the Android SDK.
• Java 17 (installed with Android Studio).

Phones that can run the app

• Android 6.0 (API 23) or newer.

Accounts

• Google Play Console (one-time fee) to publish.
• Firebase (free) if you want push notifications.

Website

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

Install Flutter & Android Studio

1. Install Flutter: docs.flutter.dev/get-started/install. Add flutter/bin to your PATH.
2. Install Android Studio, open it once and let it install the Android SDK. In SDK Manager → SDK Tools tick Android SDK Command-line Tools.
3. Accept the licences and check everything:

   flutter doctor --android-licenses
   flutter doctor -v

   Every line should have a green tick (Chrome and Xcode lines do not matter for Android).

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/android_app in Android Studio, or in a terminal.
2. Download the packages:

   cd recruiter_app/android_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 a phone or emulator

On a real phone

1. On the phone open Settings → About phone and tap Build number seven times. Then in Developer options switch on USB debugging.
2. Connect it by USB and allow the computer. Check: flutter devices.
3. Start the app:

   flutter run

On the emulator

1. In Android Studio open Device Manager and create a phone (Pixel, recent Android).
2. Start it 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 appbundle --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)

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 Android app with your package name (see Your own app id).
2. Download google-services.json and put it in android/app/. The build picks it up automatically.
3. In Firebase open Project settings → Service accounts → Generate new private key. As super admin open Mobile Apps and paste the file under Push notifications. It is stored encrypted and serves every company (a company may add its own key, but it must belong to the same Firebase project the app was built with).
4. Rebuild and install the app, sign in, then press Send me a test message on the Mobile App page.

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.

Only people with the matching permission who use the app are told; a hiring manager only hears about their own jobs.

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. Google Play rejects a build number it has already seen. Raise both for every update you upload.

Your own app id

The package name com.smartweb.jobboard.job_board_recruiter is ours. Choose your own (for example com.yourcompany.hiring) before you publish. Change it in two places: applicationId and namespace in android/app/build.gradle.kts, and the folder / package line of MainActivity under android/app/src/main/kotlin/. Use the same name in Firebase.

The app name people see is android:label in android/app/src/main/AndroidManifest.xml (currently Job Board). To change the icon, replace assets/icon.png (1024 × 1024) and run dart run flutter_launcher_icons.

Signing key (keystore)

Google Play only accepts apps signed with your own key. Keep the key and its passwords safe: if you lose them you cannot update the app.

1. Create the key:

   keytool -genkey -v -keystore ~/jobboard-upload.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

2. Create android/key.properties (it is excluded from git; never share it):

   storePassword=YOUR_STORE_PASSWORD
   keyPassword=YOUR_KEY_PASSWORD
   keyAlias=upload
   storeFile=/home/you/jobboard-upload.jks

3. The build reads that file automatically. Without it, release builds are signed with the debug key and cannot be published.

Build the release

cd recruiter_app/android_app
flutter build appbundle --release   # file for Google Play
flutter build apk --release         # a file to install directly on phones

The files are in build/app/outputs/bundle/release/app-release.aab and build/app/outputs/flutter-apk/app-release.apk.

Publish on Google Play

1. Create the app in the Play Console (name, language, app, free).
2. Fill in App content: privacy policy link, app access (give reviewers a test account and the address of a demo server), ads (none), data safety (see Privacy & data safety), target audience.
3. Store listing: short and full description, icon (512 px) and phone screenshots (use the pictures in docs/screenshots/).
4. Upload the .aab under Production (or Internal testing first), review and roll out.

Updates

Raise the version in pubspec.yaml, build a new .aab, upload it as a new release.

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.

Android 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 google-services.json.
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 app 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