Skip to content

Mobile App Build Guide

This guide covers the build process for the TopsPizza mobile app using Ionic Capacitor for both Android and iOS platforms.

Prerequisites

Required Software

  • Node.js (v14 or higher)
  • npm or yarn
  • Ionic CLI: npm install -g @ionic/cli
  • Capacitor CLI: npm install -g @capacitor/cli

Android Development

  • Android Studio with Android SDK
  • Java Development Kit (JDK) 8 or higher
  • Android SDK with API level 21+ (Android 5.0+)
  • Gradle (usually bundled with Android Studio)

iOS Development (macOS only)

  • Xcode (latest version recommended)
  • CocoaPods: sudo gem install cocoapods
  • iOS Simulator or physical iOS device

Project Setup

Initial Setup

cd frontend/mobile-app
npm install

Platform Setup

Android Setup

# Add Android platform
ionic capacitor add android

# Generate app resources (icons, splash screens)
npm run resources

iOS Setup

# Add iOS platform
ionic capacitor add ios

# Generate app resources
npm run resources

# Copy web assets to iOS
ionic capacitor copy ios

# Update Capacitor
ionic capacitor update

# Install CocoaPods dependencies
cd ios/App
pod reintegrate
pod install
cd ../../

# Open in Xcode
ionic capacitor open ios

Development

Running on Device/Simulator

Android Development

# Local environment
npm run serve-local-android-device

# Development environment
npm run serve-develop-android-device

# Staging environment
npm run serve-staging-android-device

iOS Development

# Local environment
npm run serve-local-ios-device

# Development environment
npm run serve-develop-ios-device

# Staging environment
npm run serve-staging-ios-device

Live Reload

The -l flag enables live reload, and --external allows connections from external devices on the same network.

Building for Production

Android Builds

Development Build

npm run build-develop-android

Staging Build

npm run build-staging-android

Production Build

npm run build-production-android

iOS Builds

Local Build

npm run build-local-ios

Development Build

npm run build-develop-ios

Staging Build

npm run build-staging-ios

Production Build

npm run build-production-ios

Build Outputs

Android

  • APK files: Located in android/app/build/outputs/apk/
  • AAB files: Located in android/app/build/outputs/bundle/ (for Google Play Store)

iOS

  • IPA files: Generated through Xcode after building
  • Simulator builds: Available in Xcode's derived data

Environment Configuration

The app uses different environment configurations:

  • Local: IONIC_ENV=local - Development server
  • Development: IONIC_ENV=development - Development API
  • UAT/Staging: IONIC_ENV=uat - Staging API
  • Production: IONIC_ENV=production - Production API

App Configuration

Capacitor Configuration

The main configuration is in capacitor.config.json: - App ID: co.uk.topspizza.mobile - App Name: TopsPizza UK - Web Directory: dist - Splash Screen: Configured with custom settings

Ionic Configuration

Basic Ionic settings in ionic.config.json: - Project Type: Vue - Integration: Capacitor

App Version Management

The mobile app version can be updated in two places:

1. Environment File

  • Path: frontend/env/.env.production
  • During the build process, the version specified in this file is used to set the app version for both Android and iOS.
  • The build scripts and vue.config.js read this value and update the native project files accordingly.

2. Nova Settings

  • The app version can also be managed from the Nova admin panel under settings.
  • This allows for dynamic version management and visibility for administrators.

Troubleshooting

Common Issues

Android Build Issues

  1. Gradle sync failed: Check Android SDK installation
  2. Missing dependencies: Run npm install and sync project
  3. Permission issues: Ensure proper file permissions

iOS Build Issues

  1. CocoaPods errors: Run pod install in ios/App directory
  2. Xcode build errors: Clean build folder and rebuild
  3. Signing issues: Check provisioning profiles and certificates

Debug Commands

# Check Capacitor status
ionic capacitor status

# Sync project
ionic capacitor sync

# Update Capacitor
ionic capacitor update

# Clean and rebuild
ionic capacitor clean

Deployment

Android Deployment

  1. Build the app using appropriate environment script
  2. Test APK/AAB on target devices
  3. Upload AAB to Google Play Console for release

iOS Deployment

  1. Build the app using appropriate environment script
  2. Archive in Xcode
  3. Upload to App Store Connect for review

Updating the APK/AAB on Google Play Store Console

  1. Build the Release APK/AAB
  2. Run the production build command: bash npm run build-production-android

  3. The output file will be in:

    • APK: frontend/mobile-app/android/app/build/outputs/apk/release/
    • AAB: frontend/mobile-app/android/app/build/outputs/bundle/release/

  4. Sign the APK/AAB

  5. Ensure your APK/AAB is signed with your release key. (Capacitor/Android Studio usually handles this if configured.)

  6. Login to Google Play Console

  7. Go to Google Play Console.

  8. Select Your App

  9. Choose the app you want to update.

  10. Create a New Release

  11. Go to Release > Production (or your desired track).

  12. Click Create new release.

  13. Upload the APK/AAB

  14. Drag and drop or browse to upload your new APK or AAB file.

  15. Fill in Release Details

  16. Add release notes and any required information.

  17. Review and Rollout

  18. Click Review release.

  19. If all checks pass, click Start rollout to production (or your chosen track).

  20. Wait for Review

  21. Google will review your release. Once approved, it will be available on the Play Store.

Resources