pipo_firebase_app_distribution 0.0.1

A Dart CLI tool to automatically upload APK/IPA to Firebase App Distribution with auto-detection of Firebase configuration from google-services.json and GoogleService-Info.plist

example/README.md

Pipo Firebase App Distribution - Usage Examples

Complete examples of using pipo_firebase_app_distribution CLI tool.

Table of Contents

• Basic Usage
• Multi-Environment Setup
• Generated build.yaml Examples
• Common Scenarios
• Troubleshooting

Basic Usage

Step 1: Install the package

# Global installation
dart pub global activate pipo_firebase_app_distribution

# Or add to your project
dart pub add --dev pipo_firebase_app_distribution

Step 2: Initialize configuration

Navigate to your Flutter project root:

cd /path/to/your/flutter/project
pipo_firebase init

This will scan your project and generate build.yaml.

Multi-Environment Setup

Scenario: Dev, Staging, and Production

Project Structure:

my_app/
├── android/
│   └── app/
│       └── src/
│           ├── dev/
│           │   └── google-services.json
│           ├── staging/
│           │   └── google-services.json
│           └── production/
│               └── google-services.json
├── ios/
│   └── Runner/
│       └── Firebase/
│           ├── dev/
│           │   └── GoogleService-Info.plist
│           ├── staging/
│           │   └── GoogleService-Info.plist
│           └── production/
│               └── GoogleService-Info.plist
└── pubspec.yaml

Run init command:

$ pipo_firebase init

🔍 Initializing Firebase App Distribution configuration...

✓ ✅ Firebase configurations scanned (52ms)

📋 Found Firebase configurations:

  🤖 ANDROID (dev)
     App ID: 1:123456:android:abc123def456
     Bundle ID: com.example.myapp.dev
     Project: my-app-dev-12345

  🤖 ANDROID (staging)
     App ID: 1:123456:android:ghi789jkl012
     Bundle ID: com.example.myapp.staging
     Project: my-app-staging-67890

  🤖 ANDROID (production)
     App ID: 1:123456:android:mno345pqr678
     Bundle ID: com.example.myapp
     Project: my-app-prod-11111

  🍎 IOS (dev)
     App ID: 1:123456:ios:stu901vwx234
     Bundle ID: com.example.myapp.dev
     Project: my-app-dev-12345

  🍎 IOS (staging)
     App ID: 1:123456:ios:yza567bcd890
     Bundle ID: com.example.myapp.staging
     Project: my-app-staging-67890

  🍎 IOS (production)
     App ID: 1:123456:ios:efg123hij456
     Bundle ID: com.example.myapp
     Project: my-app-prod-11111

✓ ✅ build.yaml generated successfully (2ms)

🎉 Firebase App Distribution initialized successfully!

📄 Generated file: build.yaml

Generated build.yaml Examples

Example 1: Single Environment (Dev Only)

Input: Only dev Firebase configs present

Generated build.yaml:

# Firebase App Distribution Build Configuration
# Auto-generated by pipo_firebase_app_distribution
# https://pub.dev/packages/pipo_firebase_app_distribution

project:
  name: "my_app"
  version: "1.0.0+1"

firebase:
  project_id: "my-app-dev-12345"
  project_number: "123456789"
  timeout: 600

# Environment configurations
environments:
  dev:
    android_app_id: "1:123456:android:abc123def456"
    android_bundle_id: "com.example.myapp.dev"
    ios_app_id: "1:123456:ios:stu901vwx234"
    ios_bundle_id: "com.example.myapp.dev"
    group: "internal-testers"

    setup:
      build_mode: release
      upload: true
      obfuscate: false
      auto_increment: true
      clean: true

# Build presets
presets:
  quick-dev:
    environment: dev
    build_mode: debug
    upload: false
    clean: false

  test-build:
    environment: staging
    build_mode: release
    upload: false
    clean: true

  production-release:
    environment: production
    build_mode: release
    upload: true
    clean: true
    increment: true

# Default settings
defaults:
  build_mode: release
  upload: true
  clean: true
  auto_increment: true
  obfuscate: false

# Platform-specific settings
platforms:
  android:
    build_format: apk  # or aab for Play Store
    flavor_dimension: environment

  ios:
    export_method: development  # or app-store, ad-hoc, enterprise
    team_id: ""  # Add your Apple Team ID here

Example 2: Multiple Environments

Input: Dev, Staging, and Production Firebase configs

Generated build.yaml:

# Firebase App Distribution Build Configuration
# Auto-generated by pipo_firebase_app_distribution
# https://pub.dev/packages/pipo_firebase_app_distribution

project:
  name: "my_app"
  version: "1.0.0+1"

firebase:
  project_id: "my-app-dev-12345"
  project_number: "123456789"
  timeout: 600

# Environment configurations
environments:
  dev:
    android_app_id: "1:123456:android:abc123def456"
    android_bundle_id: "com.example.myapp.dev"
    ios_app_id: "1:123456:ios:stu901vwx234"
    ios_bundle_id: "com.example.myapp.dev"
    group: "internal-testers"

    setup:
      build_mode: release
      upload: true
      obfuscate: false
      auto_increment: true
      clean: true

  staging:
    android_app_id: "1:123456:android:ghi789jkl012"
    android_bundle_id: "com.example.myapp.staging"
    ios_app_id: "1:123456:ios:yza567bcd890"
    ios_bundle_id: "com.example.myapp.staging"
    group: "qa-team"

    setup:
      build_mode: release
      upload: true
      obfuscate: false
      auto_increment: true
      clean: true

  production:
    android_app_id: "1:123456:android:mno345pqr678"
    android_bundle_id: "com.example.myapp"
    ios_app_id: "1:123456:ios:efg123hij456"
    ios_bundle_id: "com.example.myapp"
    group: "release-team"

    setup:
      build_mode: release
      upload: true
      obfuscate: true
      auto_increment: false
      clean: true

# Build presets
presets:
  quick-dev:
    environment: dev
    build_mode: debug
    upload: false
    clean: false

  test-build:
    environment: staging
    build_mode: release
    upload: false
    clean: true

  production-release:
    environment: production
    build_mode: release
    upload: true
    clean: true
    increment: true

# Default settings
defaults:
  build_mode: release
  upload: true
  clean: true
  auto_increment: true
  obfuscate: false

# Platform-specific settings
platforms:
  android:
    build_format: apk  # or aab for Play Store
    flavor_dimension: environment

  ios:
    export_method: development  # or app-store, ad-hoc, enterprise
    team_id: ""  # Add your Apple Team ID here

Example 3: Android Only

Input: Only Android Firebase configs present

Generated build.yaml:

# Firebase App Distribution Build Configuration
# Auto-generated by pipo_firebase_app_distribution
# https://pub.dev/packages/pipo_firebase_app_distribution

project:
  name: "android_app"
  version: "1.0.0+1"

firebase:
  project_id: "android-app-12345"
  project_number: "987654321"
  timeout: 600

# Environment configurations
environments:
  dev:
    android_app_id: "1:987654:android:abc123"
    android_bundle_id: "com.example.androidapp.dev"
    group: "internal-testers"

    setup:
      build_mode: release
      upload: true
      obfuscate: false
      auto_increment: true
      clean: true

  production:
    android_app_id: "1:987654:android:xyz789"
    android_bundle_id: "com.example.androidapp"
    group: "release-team"

    setup:
      build_mode: release
      upload: true
      obfuscate: true
      auto_increment: false
      clean: true

# ... (presets, defaults, platforms remain the same)

Common Scenarios

Scenario 1: Fresh Project with Firebase

Steps:

1. Add Firebase to your project via Firebase Console
2. Download google-services.json (Android) and/or GoogleService-Info.plist (iOS)
3. Place files in correct locations:
   • Android: android/app/google-services.json
   • iOS: ios/Runner/GoogleService-Info.plist
4. Run pipo_firebase init
5. Review and customize build.yaml

Expected Result:

• build.yaml with single environment
• App IDs automatically extracted
• Project info from pubspec.yaml

Scenario 2: Existing Project with Multiple Flavors

Steps:

1. Organize Firebase configs by flavor:

   android/app/src/
   ├── dev/google-services.json
   ├── staging/google-services.json
   └── production/google-services.json
   

2. Run pipo_firebase init

3. Tool automatically detects all flavors

Expected Result:

• build.yaml with multiple environments
• Each flavor has correct App IDs
• Environment-specific settings

Scenario 3: Updating Existing Configuration

Steps:

1. Make changes to Firebase configs (add new environment, update App IDs)
2. Run pipo_firebase init
3. Tool asks if you want to overwrite:

   ⚠️  build.yaml already exists. Overwrite? (y/N)
   

4. Choose y to regenerate with latest configs

Result:

• Updated build.yaml with new configurations
• Previous customizations will be lost (backup first!)

Scenario 4: Different Bundle IDs for iOS and Android

Project:

• Android: com.company.app.dev
• iOS: com.company.iosapp.dev

Generated build.yaml:

environments:
  dev:
    android_app_id: "1:123:android:abc"
    android_bundle_id: "com.company.app.dev"
    ios_app_id: "1:123:ios:def"
    ios_bundle_id: "com.company.iosapp.dev"  # Different bundle ID
    group: "internal-testers"
    # ...

Result:

• Tool correctly handles different bundle IDs
• Each platform gets correct configuration

Troubleshooting

Issue: "No Firebase configuration files found"

Problem:

❌ No Firebase configuration files found!

Expected files:
  Android: android/app/google-services.json
  iOS: ios/Runner/GoogleService-Info.plist

Solution:

1. Verify Firebase config files exist
2. Check file locations:
   • Android: Must be in android/app/ or android/app/src/{flavor}/
   • iOS: Must be in ios/Runner/ or ios/Runner/Firebase/{flavor}/
3. Ensure files are named correctly (case-sensitive)

Issue: Environment Not Detected

Problem: Configs found but environment shown as "unknown"

Solution: Environment detection works via:

1. File path (e.g., src/dev/, Firebase/staging/)
2. Bundle ID suffix (e.g., .dev, .staging)

Make sure one of these methods can identify your environment.

Issue: Duplicate Configurations

Problem: Same environment detected multiple times

Solution:

• Check if you have multiple config files for same environment
• Common cause: Config in both android/app/ and android/app/src/dev/
• Keep only one config per environment/platform

Issue: Wrong App ID Extracted

Problem: Generated build.yaml has wrong App ID

Solution:

1. Verify your Firebase config file content
2. For Android: Check mobilesdk_app_id in google-services.json
3. For iOS: Check GOOGLE_APP_ID in GoogleService-Info.plist
4. Re-download from Firebase Console if needed

Advanced Usage

Custom Environment Names

If using custom environment names (not dev/staging/production):

1. Organize configs in appropriate folders:

   android/app/src/
   ├── alpha/google-services.json
   └── beta/google-services.json
   

2. Run pipo_firebase init

3. Tool creates environments named alpha and beta

4. Manually adjust settings in build.yaml as needed

Multiple Firebase Projects

For projects using multiple Firebase projects:

1. Keep configs separate by environment
2. Run pipo_firebase init
3. Tool detects different project IDs
4. Review firebase.project_id in build.yaml
5. Manually set correct project ID if needed

Next Steps

After generating build.yaml:

1. Review generated configuration
2. Customize settings per your needs:
   • Update distribution groups
   • Adjust build modes
   • Configure obfuscation settings
3. Commit build.yaml to version control
4. Use with your build system (future feature)

Feedback & Support

Found an issue or have suggestions?

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Read documentation