View Categories

Flutter Mobile App — Setup & Configuration

7 min read

Table of Contents

Every Academy & Exam OS edition (Single Site, Multi Site and Reseller / White-Label) includes the source code of the student mobile app for Android and iOS, built with Flutter. You (or your developer) build the app for your institute and publish it under your own store accounts.

The app works only with a running Academy & Exam OS website that provides the same API contract: version 1.0.0, which Academy & Exam OS 1.0.0, 1.0.1 and 1.0.2 all provide (see Keep the app and website on matching versions below). It has no content, accounts or settings of its own: students sign in with their website accounts and see what your website grants them.

  • The app has no licence key and no licensing of its own; it is licensed together with the web application.
  • The app is never a purchase channel. Students buy or receive access on your website or from your staff.
  • Store deployment is done under your own Google Play and Apple developer accounts. OsDot Solutions offers Android and iOS deployment as separate services.

Where the source is #

The app is in the Flutter-App/ folder of your download:

PathContents
Flutter-App/Flutter-App-Source/The Flutter project: lib/ (app), test/ (tests), assets/, android/ and ios/ (native projects), bin/validate_profile.dart (profile validator) and config/production.example.json (profile template)
Flutter-App/README-BUILD.htmlThe full build and deployment guide
Flutter-App/Documentation/The build guide and changelog as an offline site
Flutter-App/THIRD-PARTY-LICENSES.htmlLicences of the bundled fonts, the science renderer and the pub dependencies
Flutter-App/CHANGELOG.html, VERSION, manifest.json, checksums.txtRelease metadata and checksums

No signing key, keystore, provisioning profile or private configuration is shipped. What you add for your institute stays with you.

Prerequisites #

  • A working Academy & Exam OS website on HTTPS that provides API contract 1.0.0 (Academy & Exam OS 1.0.0, 1.0.1 or 1.0.2; see Installing Academy & Exam OS).
  • Flutter 3.44.x with Dart 3.12 — the versions this source was tested with. Install Flutter from flutter.dev and run flutter doctor until the Android toolchain is green.
  • Android: Android Studio or the command-line SDK with the API 36 platform, build tools, and JDK 17 or newer for Gradle (Android Studio includes one).
  • iOS: a Mac with the current Xcode and an Apple Developer account for signing. CocoaPods is not required. See iOS Project & Xcode Requirements.

Step 1: Check the source #

Run every command from the Flutter-App-Source/ folder:

flutter pub get
flutter analyze
flutter test

flutter analyze must report no issues and flutter test must pass before you build.

Step 2: Find your website’s identifiers #

  1. Open https://your-domain/api/v1/bootstrap in a browser.
  2. Copy the values of deployment_id and brand_key exactly.

These are public values that tie the app to your installation. At start-up the app compares them with your website’s answer and refuses to continue on a mismatch (“This app does not match the configured institute”).

Step 3: Create the production profile #

The app is configured at build time by a production profile: a small JSON file of public values. Copy the template:

cp config/production.example.json config/production.local.json

Edit config/production.local.json. The template refuses to build as it is, because two of its values are placeholders.

KeyRequiredValue
PROFILE_SCHEMAYes1
APP_ENVYesproduction (nothing else is accepted by a release build)
SITE_NAMEYesYour institute’s name as students see it (app header and launcher label), at most 80 characters
BRAND_KEYYesThe brand_key from your website’s bootstrap (usually default)
API_BASE_URLYeshttps://your-domain/api/v1 — HTTPS, your own domain, ending in /api/v1, no port, no credentials, no query
DEPLOYMENT_IDYesThe deployment_id from your website’s bootstrap (a UUID)
ANDROID_APPLICATION_IDNoYour Android application ID, for example org.myinstitute.learn (default com.osdots.academyexam)
GOOGLE_SERVER_CLIENT_IDNoThe Google web client ID that enables Sign in with Google on Android (see below); leave empty to keep it off
NATIVE_CLIENT_IDNoLeave it out unless your website registers institute-specific API clients

No value in the profile is a secret. Files named config/*.local.json are ignored by git, so your institute’s profile does not end up in a shared repository by accident.

Step 4: Validate the profile #

dart run bin/validate_profile.dart config/production.local.json

The validator lists every rule the file breaks with a code in brackets, for example [api_host] for a local, reserved or example host name, [deployment_id] for a placeholder ID or [unknown_key] for a misspelled key. Fix the listed keys and run it again until it passes.

Development profiles (for developers). For debug builds against a development website, a developer can use a separate profile with APP_ENV=development and CATALOGUE_DATA=api. The API address must be HTTPS, or the Android emulator’s host alias on port 8765 (http://10.0.2.2:8765/api/v1) for a local server. Such builds label themselves LOCAL BACKEND · LIVE CATALOGUE on screen and can never be released: a release build accepts APP_ENV=production only. The full rules are in section 6 of the complete build guide, Flutter-App/README-BUILD.html in your download. Release builds are covered in Building the Android App.

Step 5: Build the app #

Optional: Sign in with Google (Android) #

  1. On your website, configure Google Login / OAuth (under System / Integrations). The same Google Cloud project serves web and app sign-in. See Users, Roles, Batches & Access.
  2. In the Google Cloud console, create an Android OAuth client for your application ID and the SHA-1 fingerprint of the key that signs the app (your upload key, or Google Play’s app-signing key when Play signing is on). Note the ID of the Web client of the same project.
  3. Register that web client ID as a Google audience of the website’s native app client app.android. Version 1.0.2 has no staff-area page for this: an owner or administrator (or your developer) sets it through the staff REST API endpoint /api/v1/staff/app-clients, which is described in Documentation/api/openapi.json in your download.
  4. Put the web client ID into GOOGLE_SERVER_CLIENT_ID in the profile and rebuild.

The app offers Google only when your website reports Google as enabled for the client and the build carries a valid client ID. The app never holds a Google client secret; your website verifies every Google token. Sign in with Google is not available in the iOS app in version 1.0.2; e-mail and password sign-in works on both platforms.

What the app does #

  • Content and access: published Mock Tests, materials, videos and courses from your website, with the same access rules (free after sign-in, or package access). Results follow your website’s release policy.
  • Accounts: sign-in, password reset request, e-mail verification, profile and the Communication Hub inbox. Registration and legal pages open in the device browser on your website.
  • No purchases: the app shows access and purchase history as read-only information from your website, but has no checkout, payment, renewal or subscription controls. Native in-app purchases are not part of this version.

Keep the app and website on matching versions #

The app uses API contract 1.0.0, which Academy & Exam OS 1.0.0, 1.0.1 and 1.0.2 all provide, and checks your website’s API version at start-up. When you install a website update that changes the app, rebuild the app from the updated source of the same release and publish it through the stores. Students on an older app keep working until the API contract changes, which is announced in the release notes.

The REST API contract is shipped as an OpenAPI 3 document in your download: Documentation/api/openapi.json.

Related documents #

Watch the Video Tutorial #

Academy & Exam OS Video Tutorial 11: Flutter App Setup & Android Build shows this topic step by step (7:04).

Watch on YouTube · All Academy & Exam OS video tutorials

What are your Feelings