Expeazzy Mobile App Documentation

Overview

What this package includes

Expeazzy is a configurable Flutter client for an Sngine or WoWonder-style PHP backend. The app includes timeline, messenger, reels, calls, marketplace modules, wallet routes, notifications, maps, ads, and buyer-owned service configuration.

Server first

Upload the backend API folders and configure includes/config.php before building the app.

App second

Set the API URL, API key, API secret, package id, Firebase file, and app branding in Flutter/Android/iOS.

Release last

Sign the Android build, test login/chat/media/reels/payment routes, then build APK or AAB for publishing.

Security note: do not show API secret or database password in the mobile UI. In this package, login uses the configured values internally and does not expose a credential editor.

Fast path

Quick start checklist

Use this sequence when installing a fresh backend and connecting the mobile app for the first time.

Upload server files. Upload the PHP script to your domain, then merge the mobile backend parts: apis/ and includes/.
Edit database config. Open includes/config.php and set database name, user, password, host, port, and site URL.
Create or copy API keys. In the backend admin/mobile API panel, copy the API key and API secret for native apps.
Configure Flutter. Pass API_BASE_URL, API_KEY, and API_SECRET with Dart defines.
Replace branding. Change logo, app name, colors, launcher icons, package id, and Firebase files before publishing.
Build and test. Run analyzer, install a debug build, test login, feed, chat media, reels, notifications, wallet, and payments.

Server side

Upload backend files first

The mobile app depends on the PHP backend. Install or update the server before you test the Flutter app.

Fresh install

Upload the main PHP script to your domain root or subfolder.
Upload the apis/ folder.
Upload the includes/ folder.
Keep folder names lowercase and unchanged.
Do not delete existing content/, uploads, or media folders during updates.

Update install

Make a full backup of files and database first.
Merge update files over the same paths.
For this update package, copy backend/includes/functions.php to server path includes/functions.php.
Clear server cache if your host uses opcode cache.
Retest /apis/php/ping and login after upload.

Important: upload by merging folders, not by replacing the whole server root blindly. Replacing the root can delete user uploads, custom themes, and local configuration.

Package path	Server path	Purpose
`apis/`	`public_html/app/apis/` or your install folder	Mobile API proxy and native app endpoints.
`includes/`	`public_html/app/includes/`	Backend helpers, upload handling, authentication, and shared PHP functions.
`backend/includes/functions.php`	`includes/functions.php`	Patched helper file used by chat media, uploads, previews, and API compatibility fixes.

Database

Edit includes/config.php

Add your database values first. Keep real passwords and license values private; the example below uses placeholders.

includes/config.php

<?php
define("DB_NAME", "DATABASE_NAME");
define("DB_USER", "DATABASE_USER");
define("DB_PASSWORD", "DATABASE_PASSWORD");
define("DB_HOST", "127.0.0.1");
define("DB_PORT", "3306");
define("SYS_URL", "https://domain.com/app");
define("URL_CHECK", true);
define("DEBUGGING", false);
define("DEFAULT_LOCALE", "en_us");
define("LICENCE_KEY", "LICENSE_KEY_FROM_PURCHASE");

SYS_URL rules

Use the real public URL of the script install. If the backend is installed in a subfolder, include the subfolder.

https://ikon.org.in/app is valid when the script is inside /app.

Debug rules

Use DEBUGGING=true only while fixing a server issue. Turn it back to false before production.

File map

Which setting is in which file

Use this table before editing. It shows the file to open, the setting name, what value to add, and whether the app needs a rebuild.

Setting	Open this file or panel	Change this value	After change
Database connection	`server/includes/config.php`	`DB_NAME`, `DB_USER`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`	Reload backend and test website login.
Website URL	`server/includes/config.php`	`SYS_URL`	Test `/apis/php/ping` and app login.
Mobile API URL	`lib/core/constants/app_api_config.dart` or build define	`API_BASE_URL`	Rebuild app if using build defines.
Mobile API key and secret	Backend admin API panel and build defines	`API_KEY`, `API_SECRET`	Rebuild app; do not show these in UI.
App name	`android/app/src/main/res/values/strings.xml` and `lib/core/constants/app_branding.dart`	`app_name`, `AppBranding.appName`	Rebuild app.
Primary color and accent color	`lib/core/theme/app_colors.dart`	`accent`, `primary`, `primaryDark`, `primaryLight`	Hot restart during development; rebuild for release.
Login and header logo	`assets/images/logo.webp` or `lib/core/constants/app_assets.dart`	Replace image file or update `AppAssets.logo`	Run `flutter pub get` if adding new asset paths.
Android package id	`android/app/build.gradle.kts`	`namespace`, `applicationId`	Replace Firebase JSON and rebuild.
Firebase Android config	`android/app/google-services.json`	Download file from your Firebase project	Run a clean Android build.
AdMob app id	`android/gradle.properties`	`ADMOB_ANDROID_APP_ID`	Rebuild Android; invalid value can crash startup.
Ad placements and intervals	`lib/core/ads/app_ads_config.dart`	`showAdMobBanner`, `nativeFeedInterval`, unit id defines	Rebuild app.
Google Maps	`android/gradle.properties` and build define	`GOOGLE_MAPS_API_KEY`	Enable Maps SDK in Google Cloud and rebuild.
OneSignal notifications	Backend admin settings	Timeline and messenger OneSignal app ids	Save backend settings and reinstall if package id changed.
Agora calls	Backend admin settings	Agora App ID and token/call settings	Retest audio and video calls.
Deep link schemes	`android/app/src/main/AndroidManifest.xml` and `lib/routes/app_router.dart`	Custom schemes and route mapping	Rebuild app and test notification clicks.

Connection

Connect Flutter to your backend

API values belong in the build configuration, not on the login screen. Keep the real key and secret private.

Setting	Where it lives	What to enter	Where it is used
`API_BASE_URL`	Build define or `lib/core/constants/app_api_config.dart`	Your backend mobile API path ending with `/apis/php/`	All mobile API requests.
`API_KEY`	Build define from backend admin/mobile API panel	The native app API key.	Sent as the configured API key header/signature input.
`API_SECRET`	Build define from backend admin/mobile API panel	The native app API secret.	Used for secure mobile API authentication.
`SOCKET_BASE_URL`	Build define	Your realtime socket server URL if chat sockets are enabled.	Realtime chat socket server if enabled.
`ALLOW_RUNTIME_CONNECTION_SETTINGS`	Build define	Use `false` for production if runtime overrides are not needed.	Set false for production if you never want runtime connection override storage.

Build examples after the values are ready

These examples are only for the terminal. Replace the domain and keys with values from your own backend before running.

Debug install example

flutter run \
  --dart-define=API_BASE_URL=https://domain.com/app/apis/php/ \
  --dart-define=API_KEY=YOUR_NATIVE_APP_API_KEY \
  --dart-define=API_SECRET=YOUR_NATIVE_APP_API_SECRET

Release APK example

flutter build apk --release \
  --dart-define=API_BASE_URL=https://domain.com/app/apis/php/ \
  --dart-define=API_KEY=YOUR_NATIVE_APP_API_KEY \
  --dart-define=API_SECRET=YOUR_NATIVE_APP_API_SECRET

Branding

Change logo, colors, name, icons

These are the main files buyers edit to make the app match their brand. Keep image dimensions consistent to avoid stretched UI.

What to change	File	Notes
Login and in-app logo	`assets/images/logo.webp`	Replace with your logo. Keep the same filename or update `AppAssets.logo`.
App colors	`lib/core/theme/app_colors.dart`	Edit `accent`, `primary`, `primaryDark`, `primaryLight`, background, and text colors.
Android app name	`android/app/src/main/res/values/strings.xml`	Change `app_name` from placeholder to your published app name.
Dart app name	`lib/core/constants/app_branding.dart`	Change `AppBranding.appName` for visible Dart-driven labels.
Launcher icon	`android/app/src/main/res/mipmap-*/ic_launcher.png`	Replace all densities or regenerate icons with your own launcher icon tool.
Walkthrough images	`assets/images/walkthrough_1.png` to `walkthrough_4.png`	Use app screenshots or brand illustrations with the same filenames.
Bottom nav icons	`assets/svg/`	Replace SVGs carefully and keep simple single-color paths for tinting.

Color file example

static const Color accent = Color(0xFFA52729);
static const Color primary = Color(0xFFD93437);
static const Color primaryDark = Color(0xFF66111B);
static const Color primaryLight = Color(0xFFF2CFD3);

Android

Package name, permissions, signing

The package id must match Firebase, Google Sign-In, deep links, and store listing configuration.

Open android/app/build.gradle.kts.
Change both namespace and applicationId to your final package id.
Move or rename MainActivity.kt package folders if you change the Kotlin namespace.
Create a matching Android app in Firebase and replace android/app/google-services.json.
Generate a release keystore and configure android/key.properties.

Release signing

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

android/key.properties

storePassword=STORE_PASSWORD
keyPassword=KEY_PASSWORD
keyAlias=upload
storeFile=../upload-keystore.jks

Firebase

Firebase, Google Sign-In, notifications

Firebase must use the same package id as Android. Google Sign-In additionally needs the correct web client id.

Android Firebase

Create Firebase project.
Add Android app with final package id.
Download google-services.json.
Replace android/app/google-services.json.
Use the same Firebase project for OneSignal FCM.

Google Sign-In

Create OAuth web client in Google Cloud/Firebase.
Pass it with GOOGLE_SERVER_CLIENT_ID.
Check SHA-1/SHA-256 for debug and release signing keys.

Google Sign-In define

--dart-define=GOOGLE_SERVER_CLIENT_ID=GOOGLE_WEB_CLIENT_ID.apps.googleusercontent.com

Ads

AdMob configuration

Android needs the AdMob app id in the manifest placeholder. Flutter ad loading also needs real unit ids as Dart defines.

If the AdMob app id is invalid, Android can crash on startup with Invalid application ID. Use the Google test app id for development or a real app id for production.

android/gradle.properties

ADMOB_ANDROID_APP_ID=ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy
GOOGLE_MAPS_API_KEY=GOOGLE_MAPS_ANDROID_KEY

Release with ad units

flutter build appbundle --release \
  --dart-define=API_BASE_URL=https://domain.com/app/apis/php/ \
  --dart-define=API_KEY=YOUR_NATIVE_APP_API_KEY \
  --dart-define=API_SECRET=YOUR_NATIVE_APP_API_SECRET \
  --dart-define=ADMOB_ANDROID_APP_ID=ca-app-pub-xxxxxxxxxxxxxxxx~yyyyyyyyyy \
  --dart-define=ADMOB_BANNER_UNIT_ID=ca-app-pub-xxxxxxxxxxxxxxxx/yyyyyyyyyy \
  --dart-define=ADMOB_NATIVE_UNIT_ID=ca-app-pub-xxxxxxxxxxxxxxxx/yyyyyyyyyy \
  --dart-define=ADMOB_INTERSTITIAL_UNIT_ID=ca-app-pub-xxxxxxxxxxxxxxxx/yyyyyyyyyy

Setting	File or define	Purpose
AdMob app id	`ADMOB_ANDROID_APP_ID`	Manifest metadata required by Google Mobile Ads SDK.
Banner unit	`ADMOB_BANNER_UNIT_ID`	Banner placement.
Native unit	`ADMOB_NATIVE_UNIT_ID`	Native ads in feed/post areas.
Intervals and switches	`lib/core/ads/app_ads_config.dart`	Enable/disable ad formats and tune feed/reels intervals.

Services

Push, calls, maps, GIFs, realtime chat

Some modules are controlled by backend settings and service keys. Configure the service before marking the module as ready.

OneSignal push

Set OneSignal app ids in backend settings. The app reads timeline/messenger notification keys from /app/settings.

Agora calls

Configure Agora App ID, token generation, and call switches in the backend. Audio/video call screens use backend bootstrap data.

Google Maps

Set GOOGLE_MAPS_API_KEY in Gradle properties and Dart defines. Enable Maps SDK for Android and Geocoding APIs.

GIPHY

Pass GIPHY_API_KEY when you want GIF picker support in the post composer.

Realtime sockets

If your backend uses a socket server, pass SOCKET_BASE_URL=https://domain.com:3000/.

Media uploads

Server upload folders must be writable. Chat uses the backend chat upload handle for images, videos, files, and voice notes.

Money modules

Payments, wallet, pro checkout

Payment processors stay server-controlled. The mobile app opens wallet and checkout routes once the backend has valid payment settings.

Enable wallet, pro packages, marketplace, funding, or paid modules in the backend admin panel.
Configure payment gateways such as Stripe, PayPal, bank transfer, or the gateways supported by your PHP script.
Test payments in sandbox mode from the website first.
Open wallet in the app at /wallet and Go Pro return at /go-pro/checkout-return.
Switch payment gateways to live mode only after mobile and web tests are complete.

Navigation

Deep links and notification routing

The app accepts first-party app URLs, custom schemes, notification payload routes, and fallback home routing for unknown first-party paths.

Android schemes

Manifest supports sngine://, sngine_timeline://, and sngine_messenger://.

Checkout return

The checkout return route is sngineandroid://go-pro/checkout-return in the manifest. Update scheme if you rebrand it.

If a notification sends an unknown first-party URL, the current router falls back to Home instead of showing a GoRouter no-route error.

Feature map

Core app features covered

Use this list as a QA map after setup. Server modules must be enabled in the backend for matching app screens to show complete data.

Login, register, forgot password, 2FA
Getting started profile flow
Timeline feed filters
Text, photo, video, file, map posts
Stories and reels
Live videos
Comments, reactions, share
Post details and edit flow
Messenger conversations
Images, videos, files, voice notes
Group chat creation
Broadcast messages
Audio/video calls
Chat QR and contact info
Pages and groups
Events and event posts
Marketplace and products
Jobs and candidates
Offers and funding
Movies and games
Albums and profile screens
Friend requests and suggestions
Search and directories
Wallet and Go Pro webviews
Push notification routing
AdMob placements
Google Maps and location
Account settings and privacy
Blocked users and sessions
Language and AI settings

Release

Build, test, publish

Run these checks before uploading to a store or sending the APK to a client.

Development checks

flutter pub get
flutter analyze
flutter test

Build AAB

flutter build appbundle --release \
  --dart-define=API_BASE_URL=https://domain.com/app/apis/php/ \
  --dart-define=API_KEY=YOUR_NATIVE_APP_API_KEY \
  --dart-define=API_SECRET=YOUR_NATIVE_APP_API_SECRET \
  --dart-define=GOOGLE_MAPS_API_KEY=GOOGLE_MAPS_ANDROID_KEY

QA pass: after install, test login, feed, create post, chat image/video/file/voice, group chat, reels audio stop on back, notification click, wallet, payment flow, profile edit, and logout/switch account.

Update

Update 1.0 to 1.2

The update package keeps edited files in their original project paths. Apply it by copying files over the same paths after backup.

Backup Flutter project and PHP backend.
Open updates/update_1.0_to_1.2/FILE_LIST.txt.
Copy every listed file from updates/update_1.0_to_1.2/ into the matching project path.
For backend, copy backend/includes/functions.php to server includes/functions.php.
Run flutter analyze and retest app flows.

FAQ

Common buyer questions

Short answers for setup decisions that usually slow down first-time installs.

Where do I put my API key and API secret?

Pass them as Dart defines during build/run. Do not show them on the login screen and do not publish screenshots containing real secrets.

Can I install the backend in a subfolder?

Yes. If the website is installed at https://domain.com/app, set SYS_URL to that URL and API_BASE_URL to https://domain.com/app/apis/php/.

How do I change the red app color?

Edit lib/core/theme/app_colors.dart. Change accent, primary, primaryDark, and primaryLight together so buttons, login background, tabs, and selected states remain balanced.

Why do social login buttons not work?

Enable social login in backend admin settings, configure provider credentials on the server, and pass GOOGLE_SERVER_CLIENT_ID for native Google Sign-In.

Do I need OneSignal?

Only if push notifications are required. The app can run without push, but notification click routing needs backend payloads and OneSignal/Firebase configured correctly.

Where are payment settings?

Payment gateway credentials belong in the backend admin panel. The app opens wallet, pro, marketplace, and checkout routes based on backend settings.

Fix guide

Error and issue fix guide

Start here when the app builds but a runtime feature fails.

Problem	Likely cause	Fix
Android crashes with Invalid application ID	Bad AdMob app id in manifest metadata.	Set `ADMOB_ANDROID_APP_ID` in `android/gradle.properties` or use Google's test id while developing.
API key is invalid	Wrong API key/secret, wrong `API_BASE_URL`, or server API credential record mismatch.	Confirm the backend native app API key/secret and make sure URL ends with `/apis/php/`.
Login returns unexpected response	Server returned HTML, PHP warning, or blocked route instead of JSON.	Open the endpoint in logs, enable temporary PHP debugging, check `SYS_URL`, and verify uploaded `apis/`.
Chat image/video shows placeholder	Upload failed, media URL is relative/broken, or backend helper is old.	Apply update backend `includes/functions.php`, check upload permissions, and retest chat media.
Voice message shows 00:00	Server echo does not include duration metadata.	Use update 1.2 chat controller changes; local duration is preserved after send.
Notification click shows no route	Payload URL does not match a known route.	Use update 1.2 route handling; unknown first-party URLs now return to Home.
Google login returns no ID token	Wrong OAuth client or missing SHA fingerprints.	Create a web client id and pass `GOOGLE_SERVER_CLIENT_ID`; add debug/release SHA keys.
Maps screen is blank	Missing key or disabled Maps SDK.	Set `GOOGLE_MAPS_API_KEY` and enable Maps SDK for Android plus required APIs.
Release build is unsigned	`android/key.properties` missing or incomplete.	Create upload keystore and fill store password, key password, alias, and store file.
Firebase package mismatch	`applicationId` does not match `google-services.json`.	Create a new Firebase Android app with the final package id and replace the JSON file.

Expeazzy implementation guide

Configuration reference