Before You Start: Google Firebase Dependency

• You need your own Firebase project (free to create at console.firebase.google.com) under your own Google account if you want push notifications in the app. The author does not provide, share or operate a Firebase project for you, and the package contains no google-services.json, GoogleService-Info.plist, API key or service account.
• You must accept Google’s terms. Creating a Firebase project means agreeing to the Firebase Terms of Service and the Google APIs Terms of Service, and Google’s data-processing terms. Mention Firebase Cloud Messaging in your app’s privacy policy and in the store data-safety forms (it processes a device token).
• Costs: Firebase Cloud Messaging is currently free, but it is Google’s service and its pricing and terms can change; any charge is between you and Google.
• Without Firebase the app still builds and runs: articles, accounts, podcasts, e-paper and everything else work, only push notifications stay off.
• Who: a developer adds the Firebase files when building the app (Firebase Push); the project id and service-account JSON are then pasted into the admin panel (Common Setup → Push).

What the App Does

The MediaDesk app is a Flutter client (Android and iOS, v1.2.0, Flutter 3.44 / Dart 3.12) for your MediaDesk backend. It has no content of its own: everything comes from your site’s REST API under /api/v1, in the language the reader chooses (English, Bangla, Arabic with right-to-left layout, French). State management is provider; the sign-in token is kept in the Keychain / EncryptedSharedPreferences via flutter_secure_storage.

• Home (breaking bar, hero, latest, trending), categories, article reader with key points, reactions and comments, search.
• E-paper, live blogs, podcasts with an audio player, polls.
• Accounts (register, sign in, forgot password), profile, saved articles and reading history (stored on the device), membership plans, notification settings.
• Settings: language, light / dark / system theme, text size. Offline cache of the latest articles. Push with Firebase (optional) and deep links.

What’s New in 1.2.0

• Read aloud: the headphones button in article tools reads the article with the device voice. Tap it again to stop. Languages depend on the voices installed on the device.
• Following: readers follow topics and authors, and see them in the Following feed.
• Library: saved articles and reading history work without signing in, and readers can back up their library.
• Account tools: account security controls and billing access under Account & Library.
• E-paper: lists real PDF editions from your site, with protected PDF access.
• Bottom tabs and theme: set on the website under Site → Navigation → Mobile bottom tabs and Settings → Public site → Default theme.
• Update and maintenance control: set on the website under System → Operations.

Screens

Captured on an iPhone 16 Pro simulator against the demo database (English locale).

Requirements

Setup & Run

cd Main_Files/AppSourceCode
flutter pub get
flutter analyze
flutter test
flutter run --dart-define=API_BASE=http://10.0.2.2:8000

Start the backend (php artisan serve in the web project, or your staging URL). Targets:

API_BASE

The server address is read in lib/config.dart:

String get apiBase {
  const fromEnv = String.fromEnvironment('API_BASE');
  if (fromEnv.isNotEmpty) return fromEnv;
  if (!kIsWeb && Platform.isAndroid) return 'http://10.0.2.2:8000';
  return 'http://127.0.0.1:8000';
}

Pass it on every run and build with --dart-define=API_BASE=https://your-domain.com: no trailing slash and no /api/v1 (the app appends it). Release builds default to the placeholder https://your-domain.com; debug/profile builds use the emulator or simulator localhost defaults unless you pass an explicit value. If you prefer not to type it each time, create a dart_defines.json file and use --dart-define-from-file=dart_defines.json:

{ "API_BASE": "https://your-domain.com" }

Confirm the API answers: curl https://your-domain.com/api/v1/languages.

Customization & Rebranding

Replace the MediaDesk identity with your own before the first store build. Use only letters, digits, hyphens and dots in identifiers: Apple rejects underscores in bundle identifiers, so keep the Android and iOS ids identical and underscore-free (for example com.yourbrand.news). The application id and bundle identifier cannot change after publishing.

The table shows the current value of every identifier and where to change it.

App icon

The project includes flutter_launcher_icons (configured at the end of pubspec.yaml). Replace the two source images and regenerate every Android and iOS size:

1. Replace the images

   assets/icon/app_icon.png — 1024×1024 PNG, square, no transparency (used for iOS and the legacy Android icon). assets/icon/app_icon_foreground.png — 1024×1024 PNG with the logo centred inside the middle ~66% and a transparent background (Android adaptive icon). Change adaptive_icon_background: "#FFFFFF" in pubspec.yaml to your background colour.

2. Generate

   Run dart run flutter_launcher_icons. It rewrites android/app/src/main/res/mipmap-*, drawable-*/ic_launcher_foreground.png and ios/Runner/Assets.xcassets/AppIcon.appiconset.

Splash screen

The native launch screens are used (no splash package):

• Android: android/app/src/main/res/drawable/launch_background.xml and drawable-v21/launch_background.xml. Change @android:color/white to your colour, and uncomment the <bitmap> item to show a centred logo (add the image as mipmap/launch_image or point android:src at your drawable).
• iOS: replace the images in ios/Runner/Assets.xcassets/LaunchImage.imageset (1x, 2x, 3x) and adjust the background colour in ios/Runner/Base.lproj/LaunchScreen.storyboard with Xcode’s Interface Builder.

Prefer a generator? Add flutter_native_splash to dev_dependencies, configure your colour and image in pubspec.yaml, and run dart run flutter_native_splash:create; it writes the same files.

Colours, fonts and texts

• Colours: the app mirrors the website’s reader skins. Per-skin colours, including the brand colour, are in _build in lib/theme/md_tokens.dart; the Material theme is built in lib/theme/md_theme.dart. The backend’s app-config endpoint can override background, surface, text and line colours and the corner radius at runtime.
• Fonts: bundled in assets/fonts/ and declared under fonts: in pubspec.yaml (Inter, Source Serif 4, Noto Sans Bengali, Noto Naskh Arabic); the family names are kSansFamily / kSerifFamily in lib/theme/md_tokens.dart.
• Texts: shared labels in lib/strings.dart, feature labels in each lib/features/*/strings.dart (en, bn, ar, fr). The server can override them.

Signing team (iOS)

The project ships without an Apple development team. Open ios/Runner.xcworkspace in Xcode → Runner → Signing & Capabilities and choose your own team before running on a device or archiving.

Run flutter clean && flutter pub get after renaming, then rebuild. flutter pub get also creates the generated plugin files (GeneratedPluginRegistrant.*, ios/Flutter/Generated.xcconfig), which are not shipped.

Firebase Push

Push needs your own Firebase project (see Firebase dependency). PushService calls Firebase.initializeApp(); when no Firebase configuration is present it stays inert, so the app runs fine without it. To enable it:

1. Create the Firebase project

   Add an Android app with your application id and an iOS app with your bundle id.

2. Android

   Download google-services.json into android/app/. Add the Google services Gradle plugin: id("com.google.gms.google-services") version "…" apply false in the plugins block of android/settings.gradle.kts, and id("com.google.gms.google-services") in android/app/build.gradle.kts. POST_NOTIFICATIONS is already declared for Android 13+.

3. iOS

   Add GoogleService-Info.plist to ios/Runner in Xcode (tick the Runner target). Enable Push Notifications and Background Modes → Remote notifications capabilities, and upload an APNs authentication key in Firebase → Project settings → Cloud Messaging.

4. Shortcut

   dart pub global activate flutterfire_cli && flutterfire configure generates the platform files for you.

5. Connect the server

   In the admin panel add the Firebase project id and service-account JSON under Settings → Integrations → Firebase (FCM) (Common Setup). The app registers its FCM token with POST /api/v1/devices (with language and topics); the server sends through FCM HTTP v1 when you send a push campaign or a breaking alert.

6. Test

   On a real device: php artisan fcm:test <token> --title="Hello" --body="Test" --url=/en/news/some-slug in the web project. Tapping a notification whose data.url is an article opens that article.

Deep Links

• Custom scheme works out of the box: mediadesk://article/{slug} (Android intent filter in AndroidManifest.xml, iOS CFBundleURLSchemes). Change the scheme in both places if you rebrand; push payloads from the server convert /{locale}/news/{slug} to mediadesk://article/{slug}, so keep the scheme as mediadesk unless you also change the server.
• Android App Links (https): add a second intent-filter with android:autoVerify="true" and <data android:scheme="https" android:host="your-domain.com"/>, and host /.well-known/assetlinks.json with your package name and signing-certificate SHA-256 on your domain.
• iOS Universal Links: add the Associated Domains capability (applinks:your-domain.com) and host /.well-known/apple-app-site-association.
• articleSlugFromUri in lib/services/deep_links.dart already parses mediadesk://article/{slug} and https://your-domain/{locale}/news/{slug}.

# test on an Android emulator
adb shell am start -a android.intent.action.VIEW -d "mediadesk://article/your-slug"
# test on an iOS simulator
xcrun simctl openurl booted "mediadesk://article/your-slug"

Release Builds

Android

1. Create an upload keystore

   keytool -genkeypair -v -keystore ~/mediadesk-upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias mediadesk. Keep it and its passwords safe and out of git.

2. Create android/key.properties

   Use exactly: storePassword=your_keystore_password, keyPassword=your_key_password, keyAlias=mediadesk, storeFile=/absolute/path/to/mediadesk-upload-keystore.jks.

3. Use the shipped signing setup

   The distributed android/app/build.gradle.kts already reads android/key.properties and uses its keystore for release builds. It does not use the debug key.

4. Build

   flutter build appbundle --release --dart-define=API_BASE=https://your-domain.com (Play Store, .aab) or flutter build apk --release --dart-define=API_BASE=https://your-domain.com. Output in build/app/outputs/.

iOS

1. Signing

   Open ios/Runner.xcworkspace in Xcode, select your team, set the bundle id, enable automatic signing (or use a distribution certificate and profile).

2. Build

   flutter build ipa --release --dart-define=API_BASE=https://your-domain.com — creates an archive in build/ios/archive and an .ipa in build/ios/ipa.

3. Upload

   Use Xcode Organizer or Transporter to upload to App Store Connect, then submit via TestFlight / review.

Always pass the same --dart-define=API_BASE=… to every build command when targeting a different server. A release build without it uses the placeholder https://your-domain.com; debug/profile builds use local defaults. Release builds enable R8 shrinking and resource shrinking. For stronger Dart obfuscation, use --obfuscate --split-debug-info=build/symbols and archive the symbols for crash de-obfuscation.

Payments & Store Policy

The app contains no in-app purchase and no payment code. Choose plan (membership screen) and Buy this article (premium articles) open your website checkout — /{lang}/membership/checkout/{plan} and /{lang}/membership/buy/{article} — in the device’s external browser, never in a WebView inside the app. The reader pays on your website with the gateways you enabled; when they come back to the app it re-loads their plan and purchased articles from the server, and the access is shared with the website account.

# Store build without purchase buttons
flutter build ipa --release --dart-define=API_BASE=https://your-domain.com --dart-define=CHECKOUT_LINKS=false
flutter build appbundle --release --dart-define=API_BASE=https://your-domain.com --dart-define=CHECKOUT_LINKS=false

Store checklist

• Final app name, unique application id / bundle id, version and build number
• App icon and splash replaced with your own (see Customization & Rebranding)
• Release signing in place (Android upload key with Play App Signing; iOS distribution certificate and profile)
• Release build uses https:// and has no debug URLs (cleartext is debug/profile only)
• Privacy policy URL (the site’s static pages are reachable from the app) and data-safety / App Privacy answers: email, name, device id, push token; reading history stored locally
• Account deletion: the Profile screen includes a delete-account action that calls DELETE /api/v1/me. For the store listing, use https://your-site/{locale}/account/delete as the web link for account deletion: readers can use it without the app, and Google sign-in accounts can confirm by e-mail. The API answers 409 while an author payout is in progress. Keep the privacy-policy and account-deletion links available in the published app and store listing
• Paid plans: decide between external checkout links (default) and CHECKOUT_LINKS=false for each store and region, as described above
• Your own Apple team selected in Xcode (none is set in the project)
• Screenshots (phone and tablet), short and full descriptions per language, category, content rating, contact e-mail
• Notification permission text and Android 13 POST_NOTIFICATIONS (declared); Firebase configured if you advertise push
• Test on real devices (Android 8+ and a recent iPhone), Arabic RTL, large text, dark mode, offline start
• Decide on crash reporting / analytics and disclose it

Troubleshooting