Metricis Mobile Deployment Guide¶

This guide covers building and publishing the Metricis mobile app for iOS and Android.

Prerequisites¶

General¶

Node.js 18+ and npm
Xcode 15+ (for iOS)
Android Studio (for Android)
Capacitor CLI installed globally: npm install -g @capacitor/cli

iOS Requirements¶

macOS (required for iOS builds)
Apple Developer account ($99/year)
Xcode Command Line Tools: xcode-select --install
CocoaPods: sudo gem install cocoapods

Android Requirements¶

Java Development Kit (JDK) 17+
Android SDK (installed via Android Studio)
Android keystore for signing release builds

Quick Start¶

cd client

# Install dependencies
npm install

# Build web assets and sync to native projects
npm run build:mobile

# Open in Xcode (iOS)
npm run cap:ios

# Open in Android Studio (Android)
npm run cap:android

iOS Deployment¶

Development Build¶

Build and sync:
```
npm run build:ios
```
Open in Xcode:
```
npm run cap:ios
```
In Xcode:
Select your target device or simulator
Click the Play button to build and run

Release Build for App Store¶

Configure signing in Xcode:
Open ios/App/App.xcworkspace in Xcode
Select the "App" project in the navigator
Go to "Signing & Capabilities" tab
Enable "Automatically manage signing"
Select your Apple Developer team
Set version and build numbers:
In Xcode, select the App target
Under "General" tab, update:
- Version: 1.0.0 (user-facing version)
- Build: 1 (increment for each submission)
Create archive:
```
npm run build:ios:release
```

Or manually in Xcode: - Product → Archive - Wait for build to complete

Upload to App Store Connect:
In Xcode Organizer (Window → Organizer)
Select your archive
Click "Distribute App"
Choose "App Store Connect"
Follow the wizard

App Store Submission Checklist¶

[ ] App icon (1024x1024 for App Store)
[ ] Screenshots for required device sizes
[ ] Privacy policy URL
[ ] App description and keywords
[ ] Set age rating
[ ] Configure App Privacy information

Android Deployment¶

Development Build¶

Build and sync:
```
npm run build:android
```
Open in Android Studio:
```
npm run cap:android
```
In Android Studio:
Select your device or emulator
Click the Run button

Release Build for Play Store¶

1. Create a Signing Keystore (one-time setup)¶

keytool -genkey -v -keystore metricis-release-key.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias metricis

Important: Store this keystore securely! You'll need it for all future updates.

2. Configure Environment Variables¶

export ANDROID_KEYSTORE_PATH=/path/to/metricis-release-key.jks
export ANDROID_KEYSTORE_PASSWORD=your_keystore_password
export ANDROID_KEY_ALIAS=metricis
export ANDROID_KEY_PASSWORD=your_key_password

For CI/CD, store these as secrets.

3. Build Release Bundle (recommended for Play Store)¶

npm run build:android:release

The AAB file will be at: android/app/build/outputs/bundle/release/app-release.aab

4. Build Release APK (for direct distribution)¶

npm run build:android:apk

The APK will be at: android/app/build/outputs/apk/release/app-release.apk

Play Store Submission Checklist¶

[ ] App icon (512x512)
[ ] Feature graphic (1024x500)
[ ] Screenshots for phone and tablet
[ ] Privacy policy URL
[ ] Short and full descriptions
[ ] Content rating questionnaire
[ ] Target API level compliance

Version Management¶

Updating Version Numbers¶

iOS (in ios/App/App.xcodeproj/project.pbxproj or via Xcode): - MARKETING_VERSION: User-facing version (1.0.0) - CURRENT_PROJECT_VERSION: Build number (1, 2, 3...)

Android (in android/app/build.gradle):

defaultConfig {
    versionCode 1          // Increment for each release
    versionName "1.0.0"    // User-facing version
}

Web (in client/package.json):

{
  "version": "1.0.0"
}

Semantic Versioning¶

Major (X.0.0): Breaking changes, major features
Minor (0.X.0): New features, backwards compatible
Patch (0.0.X): Bug fixes, minor updates

Push Notifications Setup¶

iOS (APNs)¶

In Apple Developer Portal:
Go to Certificates, Identifiers & Profiles
Create an APNs Key (recommended) or Certificate
Download and store securely
In Xcode:
Enable "Push Notifications" capability
Enable "Background Modes" → "Remote notifications"
Configure your backend with the APNs key

Android (FCM)¶

In Firebase Console:
Create/select your project
Add Android app with package app.metricis.app
Download google-services.json

Place google-services.json in:

client/android/app/google-services.json

Sync Capacitor:
```
cap sync android
```

App Icons and Splash Screens¶

Generating Assets¶

Use a tool like capacitor-assets:

npm install -g @capacitor/assets

# Create source images in resources/
# - resources/icon.png (1024x1024, no transparency)
# - resources/splash.png (2732x2732, centered logo)

npx capacitor-assets generate

Manual Icon Placement¶

iOS: - ios/App/App/Assets.xcassets/AppIcon.appiconset/ - Provide all required sizes (20pt to 1024pt)

Android: - android/app/src/main/res/mipmap-*/ - Provide ic_launcher.png and ic_launcher_round.png

Environment Configuration¶

API Endpoints¶

Update the API base URL in client/src/config.ts before building:

// Development
export const API_BASE_URL = 'http://localhost:8000/api';

// Production
export const API_BASE_URL = 'https://api.metricis.app/api';

Or use environment variables:

export const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:8000/api';

Build-time Variables¶

# Production build with custom API
VITE_API_URL=https://api.yourdomain.com npm run build:mobile

Troubleshooting¶

iOS¶

"No signing certificate" error: - Ensure you're signed into Xcode with your Apple ID - Enable automatic signing in project settings

"CocoaPods not found":

sudo gem install cocoapods
cd ios/App && pod install

Android¶

"SDK not found": - Set ANDROID_HOME environment variable - Or create android/local.properties:

sdk.dir=/Users/username/Library/Android/sdk

Gradle build failures:

cd android && ./gradlew clean

Keystore issues: - Verify all environment variables are set - Check keystore path is absolute

General¶

Capacitor sync issues:

# Clean and rebuild
rm -rf node_modules
npm install
npm run build
cap sync

WebView not loading: - Check capacitor.config.ts server settings - Verify CORS is configured on your API

CI/CD Integration¶

GitHub Actions Example¶

name: Build Mobile Apps

on:
  push:
    tags:
      - 'v*'

jobs:
  build-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: Install dependencies
        working-directory: client
        run: npm ci

      - name: Build Android
        working-directory: client
        env:
          ANDROID_KEYSTORE_PATH: ${{ secrets.ANDROID_KEYSTORE_PATH }}
          ANDROID_KEYSTORE_PASSWORD: ${{ secrets.ANDROID_KEYSTORE_PASSWORD }}
          ANDROID_KEY_ALIAS: ${{ secrets.ANDROID_KEY_ALIAS }}
          ANDROID_KEY_PASSWORD: ${{ secrets.ANDROID_KEY_PASSWORD }}
        run: npm run build:android:release

      - name: Upload AAB
        uses: actions/upload-artifact@v4
        with:
          name: android-bundle
          path: client/android/app/build/outputs/bundle/release/*.aab

  build-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        working-directory: client
        run: npm ci

      - name: Build iOS
        working-directory: client
        run: npm run build:ios

      # Note: Full iOS signing requires additional setup
      # See: https://docs.github.com/en/actions/deployment/deploying-xcode-applications

Security Considerations¶

Never commit keystores or signing certificates to version control
Use environment variables for sensitive configuration
Enable certificate pinning for API communication
Disable WebView debugging in production builds
Validate API responses on the client side
Implement proper session management with token refresh