Capacitor Configuration - Rodando Driver

Overview

Capacitor is the native runtime that powers Rodando Driver on Android and iOS devices. It provides a bridge between your Ionic/Angular web application and native platform APIs, enabling features like camera access, geolocation, push notifications, and more.

Current Configuration

The application’s Capacitor configuration is defined in capacitor.config.ts:

capacitor.config.ts

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'io.ionic.starter',
  appName: 'rodandoApp-frontend',
  webDir: 'www'
};

export default config;

The default appId (io.ionic.starter) should be changed to a unique identifier for your application before building for production.

Configuration Properties

Required Properties

Property	Type	Current Value	Description
`appId`	`string`	`'io.ionic.starter'`	Unique identifier for your app (reverse domain notation)
`appName`	`string`	`'rodandoApp-frontend'`	Display name of your application
`webDir`	`string`	`'www'`	Directory containing the built web assets

Recommended Configuration

Update the configuration for production deployment:

capacitor.config.ts

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.rodando.driver',              // Change to your domain
  appName: 'Rodando Driver',                 // User-facing app name
  webDir: 'www',
  
  // Platform-specific configurations
  android: {
    buildOptions: {
      keystorePath: 'path/to/keystore.jks',
      keystoreAlias: 'your-alias'
    }
  },
  
  ios: {
    contentInset: 'automatic',
    scheme: 'App'
  },
  
  // Server configuration for development
  server: {
    // Uncomment for live reload during development
    // url: 'http://192.168.1.100:8100',
    // cleartext: true
  },
  
  // Plugin configurations
  plugins: {
    SplashScreen: {
      launchShowDuration: 2000,
      backgroundColor: '#FFFFFF'
    },
    Keyboard: {
      resize: 'body',
      style: 'dark'
    }
  }
};

export default config;

Installed Capacitor Plugins

The application uses the following Capacitor plugins (from package.json):

package.json

{
  "dependencies": {
    "@capacitor/android": "7.4.2",
    "@capacitor/app": "7.0.1",
    "@capacitor/core": "7.4.2",
    "@capacitor/haptics": "7.0.1",
    "@capacitor/keyboard": "7.0.1",
    "@capacitor/preferences": "^7.0.2",
    "@capacitor/status-bar": "7.0.1",
    "capacitor-secure-storage-plugin": "^0.11.0"
  },
  "devDependencies": {
    "@capacitor/cli": "7.4.2"
  }
}

Plugin Reference

Plugin	Version	Purpose
`@capacitor/app`	7.0.1	App lifecycle events, deep linking, app state
`@capacitor/haptics`	7.0.1	Haptic feedback (vibration)
`@capacitor/keyboard`	7.0.1	Keyboard appearance and behavior
`@capacitor/preferences`	7.0.2	Local data storage (key-value pairs)
`@capacitor/status-bar`	7.0.1	Status bar styling and visibility
`capacitor-secure-storage-plugin`	0.11.0	Secure credential storage

Initial Setup

Install Capacitor

Capacitor is already installed. Verify installation:

npx cap --version

Expected output: 7.4.2 or similar

Update App Configuration

Edit capacitor.config.ts and update the appId:

const config: CapacitorConfig = {
  appId: 'com.yourcompany.rodando.driver', // Use your domain
  appName: 'Rodando Driver',
  webDir: 'www'
};

The appId must be unique and should follow reverse domain notation (e.g., com.company.app).

Build Web Assets

Before adding platforms, build your Angular application:

npm run build

This creates the www directory with compiled assets.

Add Platform(s)

Add Android and/or iOS platforms:

Android
iOS

npx cap add android

This creates an android/ directory with a native Android project.

npx cap add ios

This creates an ios/ directory with a native iOS project.

iOS development requires macOS with Xcode installed.

Sync Project

Copy web assets and Capacitor configuration to native projects:

npx cap sync

Run this command whenever you:

Change capacitor.config.ts
Install/update Capacitor plugins
Build new web assets

Development Workflow

Build and Sync

After making changes to your web code:

# Build Angular app
npm run build

# Sync to native projects
npx cap sync

Opening Native IDEs

Open native projects for building and debugging:

Android Studio
Xcode

npx cap open android

This opens the android/ project in Android Studio.From Android Studio:

Wait for Gradle sync to complete
Select a device/emulator
Click Run ▶️

npx cap open ios

This opens the ios/ project in Xcode.From Xcode:

Select a target device/simulator
Click Run ▶️

Requires macOS with Xcode installed.

Live Reload (Development)

Enable live reload for faster development:

Start Development Server

npm start

Note the IP address (e.g., http://192.168.1.100:4200)

Update Capacitor Config

capacitor.config.ts

const config: CapacitorConfig = {
  // ...
  server: {
    url: 'http://192.168.1.100:4200', // Your local IP
    cleartext: true
  }
};

Sync and Run

npx cap sync
npx cap run android # or ios

Disable for Production

Always comment out or remove the server configuration before building for production!

Platform-Specific Configuration

Android Configuration

Update Package Name

Edit android/app/build.gradle:

android/app/build.gradle

android {
    namespace "com.yourcompany.rodando.driver"
    defaultConfig {
        applicationId "com.yourcompany.rodando.driver"
        // ...
    }
}

Permissions

Add required permissions in android/app/src/main/AndroidManifest.xml:

AndroidManifest.xml

<manifest>
    <!-- Location permissions for driver tracking -->
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
    
    <!-- Network permissions -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    
    <!-- Camera permission (if needed) -->
    <uses-permission android:name="android.permission.CAMERA" />
    
    <!-- Notification permission (Android 13+) -->
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
</manifest>

Signing Configuration

For release builds, configure signing in capacitor.config.ts:

android: {
  buildOptions: {
    keystorePath: 'release.keystore',
    keystorePassword: process.env.KEYSTORE_PASSWORD,
    keystoreAlias: 'rodando-driver',
    keystoreAliasPassword: process.env.KEY_PASSWORD
  }
}

iOS Configuration

Update Bundle Identifier

Open Xcode and:

Select your project in the navigator
Select the target
Go to Signing & Capabilities
Update Bundle Identifier to com.yourcompany.rodando.driver

Permissions (Info.plist)

Add permission descriptions in ios/App/App/Info.plist:

Info.plist

<dict>
    <!-- Location permissions -->
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>Rodando Driver needs your location to show nearby ride requests</string>
    
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>Rodando Driver needs background location to track active rides</string>
    
    <key>NSLocationAlwaysUsageDescription</key>
    <string>Rodando Driver uses location in the background for ride tracking</string>
    
    <!-- Camera permission -->
    <key>NSCameraUsageDescription</key>
    <string>Rodando Driver needs camera access for profile photos</string>
    
    <!-- Photo library -->
    <key>NSPhotoLibraryUsageDescription</key>
    <string>Rodando Driver needs access to save and upload photos</string>
</dict>

Plugin Configuration

Configure installed plugins in capacitor.config.ts:

capacitor.config.ts

const config: CapacitorConfig = {
  // ...
  plugins: {
    // Status Bar Configuration
    StatusBar: {
      style: 'dark', // 'light' or 'dark'
      backgroundColor: '#FFFFFF',
      overlaysWebView: false
    },
    
    // Keyboard Configuration
    Keyboard: {
      resize: 'body',     // 'native', 'body', 'ionic', or 'none'
      style: 'dark',      // 'light' or 'dark'
      resizeOnFullScreen: true
    },
    
    // Splash Screen Configuration
    SplashScreen: {
      launchShowDuration: 2000,
      backgroundColor: '#FFFFFF',
      showSpinner: false,
      androidSpinnerStyle: 'small',
      iosSpinnerStyle: 'small',
      spinnerColor: '#999999',
      splashFullScreen: false,
      splashImmersive: false
    },
    
    // App Configuration
    App: {
      handleRedirects: true
    },
    
    // Preferences (Storage) Configuration
    Preferences: {
      group: 'com.rodando.driver'
    }
  }
};

Using Capacitor Plugins

Example: Status Bar

src/app/app.component.ts

import { Component, OnInit } from '@angular/core';
import { StatusBar, Style } from '@capacitor/status-bar';
import { Platform } from '@ionic/angular';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html'
})
export class AppComponent implements OnInit {
  constructor(private platform: Platform) {}
  
  async ngOnInit() {
    await this.platform.ready();
    
    if (this.platform.is('capacitor')) {
      // Configure status bar
      await StatusBar.setStyle({ style: Style.Dark });
      await StatusBar.setBackgroundColor({ color: '#FFFFFF' });
    }
  }
}

Example: Haptics

import { Haptics, ImpactStyle } from '@capacitor/haptics';

// Trigger haptic feedback
await Haptics.impact({ style: ImpactStyle.Light });

// Notification haptics
await Haptics.notification({ type: 'success' });

Example: Preferences (Storage)

import { Preferences } from '@capacitor/preferences';

// Save data
await Preferences.set({
  key: 'driverId',
  value: '12345'
});

// Retrieve data
const { value } = await Preferences.get({ key: 'driverId' });
console.log('Driver ID:', value);

// Remove data
await Preferences.remove({ key: 'driverId' });

// Clear all data
await Preferences.clear();

Example: Secure Storage

import { SecureStoragePlugin } from 'capacitor-secure-storage-plugin';

// Store secure data (auth tokens, credentials)
await SecureStoragePlugin.set({
  key: 'authToken',
  value: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
});

// Retrieve secure data
const { value } = await SecureStoragePlugin.get({ key: 'authToken' });

// Remove secure data
await SecureStoragePlugin.remove({ key: 'authToken' });

Building for Production

Android Release Build

Create Keystore

Generate a release keystore (one-time setup):

keytool -genkey -v -keystore release.keystore \
  -alias rodando-driver \
  -keyalg RSA -keysize 2048 -validity 10000

Store the keystore file and passwords securely! You cannot update your app without them.

Build Web Assets

npm run build --configuration=production
npx cap sync android

Build APK/AAB

Open Android Studio:

npx cap open android

Then:

Build → Generate Signed Bundle / APK
Select Android App Bundle (AAB) for Google Play
Choose your keystore and enter credentials
Select release build variant
Click Finish

The signed AAB will be in android/app/release/

iOS Release Build

Apple Developer Account

Ensure you have:

Active Apple Developer account ($99/year)
Certificates and provisioning profiles configured

Build Web Assets

npm run build --configuration=production
npx cap sync ios

Configure Signing

Open Xcode:

npx cap open ios

Select project → Target → Signing & Capabilities
Enable Automatically manage signing
Select your Team
Verify bundle identifier matches App Store Connect

Archive and Upload

In Xcode:

Select Any iOS Device as target
Product → Archive
When complete, click Distribute App
Follow wizard to upload to App Store Connect

Troubleshooting

Plugin Not Found

Error: “Plugin [PluginName] not found” Solutions:

# Reinstall plugins
npm install

# Sync with native projects
npx cap sync

# If still failing, rebuild native projects
npx cap sync --force

Build Failing After Plugin Update

# Clean and rebuild
rm -rf node_modules package-lock.json
npm install
npx cap sync

# For Android
cd android && ./gradlew clean && cd ..

# For iOS
cd ios && rm -rf Pods Podfile.lock && pod install && cd ..

Live Reload Not Working

Ensure device/emulator is on same network as development machine
Verify server.url uses your local IP (not localhost)
Check firewall isn’t blocking port 4200
Disable VPN if active

Android Build Errors

Gradle build failed:

Update Android Studio and Gradle
Check Java version (JDK 17 recommended)
Clean gradle cache:
```
cd android
./gradlew clean
```

iOS Pod Installation Issues

cd ios/App
rm -rf Pods Podfile.lock
pod repo update
pod install

Getting Started

Core Features

User Guides

Configuration

​Overview

​Current Configuration

​Configuration Properties

​Required Properties

​Recommended Configuration

​Installed Capacitor Plugins

​Plugin Reference

​Initial Setup

​Development Workflow

​Build and Sync

​Opening Native IDEs

​Live Reload (Development)

​Platform-Specific Configuration

​Android Configuration

​Update Package Name

​Permissions

​Signing Configuration

​iOS Configuration

​Update Bundle Identifier

​Permissions (Info.plist)

​Plugin Configuration

​Using Capacitor Plugins

​Example: Status Bar

​Example: Haptics

​Example: Preferences (Storage)

​Example: Secure Storage

​Building for Production

​Android Release Build

​iOS Release Build

​Troubleshooting

​Plugin Not Found

​Build Failing After Plugin Update

​Live Reload Not Working

​Android Build Errors

​iOS Pod Installation Issues

​Next Steps

Environment Config

Google Maps Setup

​Additional Resources

Build docs developers (and LLMs) love

Overview

Current Configuration

Configuration Properties

Required Properties

Recommended Configuration

Installed Capacitor Plugins

Plugin Reference

Initial Setup

Development Workflow

Build and Sync

Opening Native IDEs

Live Reload (Development)

Platform-Specific Configuration

Android Configuration

Update Package Name

Permissions

Signing Configuration

iOS Configuration

Update Bundle Identifier

Permissions (Info.plist)

Plugin Configuration

Using Capacitor Plugins

Example: Status Bar

Example: Haptics

Example: Preferences (Storage)

Example: Secure Storage

Building for Production

Android Release Build

iOS Release Build

Troubleshooting

Plugin Not Found

Build Failing After Plugin Update

Live Reload Not Working

Android Build Errors

iOS Pod Installation Issues

Next Steps

Additional Resources