The Pie Documentation
Integrations & Automation
Mobile Build Preparation
Android Apps

Android Apps

Overview

This guide covers building Android applications (native or React Native) for Pie testing. You’ll create an APK file that can be installed on Android emulators.

What You’ll Need

  • Android Studio: Latest version with Android SDK
  • Android Virtual Device (AVD): Configured emulator
  • Your Android Project: Native or React Native Android app
  • Java Development Kit (JDK): Properly configured (usually bundled with Android Studio)

Initial Setup

Create an Android Virtual Device

If you don’t already have an AVD configured:

  1. Open Android Studio
  2. Navigate to Tools → Device Manager
  3. Click “Create Device”
  4. Select Phone category → Choose latest Pixel model
  5. Select the latest Android OS version available
  6. Click “Finish” to create the AVD

Configure Project for Testing

Before building, ensure your app is configured correctly:

  1. Open build.gradle (app level)
  2. Verify all API endpoints point to staging/test environments
  3. Confirm API keys and configurations are for test environment only
  4. Remove any production-specific security measures that would block testing

Step-by-Step Build Instructions

1. Open Your Project

  1. Launch Android Studio
  2. Open your Android app project
  3. Wait for Gradle sync to complete
    • You’ll see a progress indicator in the bottom status bar
    • Resolve any sync errors before proceeding

2. Generate the APK

  1. Navigate to Build menu → Build Bundle(s) / APK(s) → Build APK(s)
  2. Android Studio will compile your app
    • This may take several minutes for the first build
    • Watch the Build Output panel for progress
  3. Once complete, a notification will appear with a link to the APK location

3. Locate Your APK

Option A: Click “locate” in the build completion notification

Option B: Navigate manually to the default path:

app/build/outputs/apk/debug/app-debug.apk
ℹ️

Note: The exact path may vary based on:

  • Build configuration (debug/release)
  • Product flavors
  • Custom output directories

4. Verify Your Build

Before uploading, test the APK on your emulator:

  1. Start your Android Virtual Device from Device Manager
  2. Install the APK: Drag and drop the APK file onto the emulator window
  3. Launch the app from the app drawer
  4. Verify test environment: Confirm it connects to your staging/test servers
  5. Test basic functionality: Navigate through key features to ensure stability

5. Upload to Pie

  1. Your APK is ready for direct upload (no compression needed)
  2. Go to Pie’s upload portal
  3. Upload the app-debug.apk file
Android APK files can be uploaded directly without zipping!

Build Configuration Best Practices

Use Debug or Staging Variants

  • Debug builds are ideal for testing (include helpful diagnostics)
  • Avoid release builds unless specifically needed (they may have obfuscation)
  • If using build flavors, use staging or QA flavors, not production

Environment Configuration

Verify your build.gradle is properly configured:

android {
    buildTypes {
        debug {
            applicationIdSuffix ".debug"
            debuggable true
            // Test environment configuration
        }
    }
}

Permissions

Ensure AndroidManifest.xml includes all necessary permissions:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Add other required permissions -->

Security Features

For testing purposes:

  • Disable anti-debugging features that might interfere with testing
  • Remove certificate pinning for test environments
  • Disable ProGuard/R8 obfuscation in debug builds
  • Allow cleartext traffic for test endpoints (if needed)

Example network security configuration for testing:

<!-- res/xml/network_security_config.xml -->
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">your-test-server.com</domain>
    </domain-config>
</network-security-config>

React Native Android Considerations

If you’re building a React Native Android app:

JavaScript Bundle

React Native automatically bundles JavaScript code in debug builds. No additional bundling steps are required for debug APKs.

Metro Bundler

The APK will be self-contained and won’t require Metro bundler to run. If you want to verify this:

  1. Close all terminal windows running Metro
  2. Install and launch the APK on the emulator
  3. App should run without connecting to Metro

Assets

All JavaScript assets are automatically included in the APK during the build process.

Troubleshooting

Gradle Sync Failed

Problem: Project won’t sync with Gradle.

Solutions:

  • Check your internet connection (Gradle may need to download dependencies)
  • Update Android Studio to the latest version
  • Navigate to File → Invalidate Caches → Restart
  • Check build.gradle for syntax errors
  • Verify JDK path is correctly configured

Build Failed with Errors

Problem: Build process fails with compilation errors.

Solutions:

  • Read the error message in the Build Output panel
  • Check for missing dependencies in build.gradle
  • Verify all imported libraries are compatible with your target SDK
  • Clean and rebuild: Build → Clean Project, then Build → Rebuild Project

APK Not Found

Problem: Cannot locate the generated APK.

Solutions:

  • Use the “locate” link in the build notification
  • Search for *.apk files in your project directory
  • Check if you have custom output directories defined in build.gradle
  • Verify the build actually completed successfully (check Build Output)

App Crashes on Launch

Problem: APK installs but crashes immediately.

Solutions:

  • Check Logcat in Android Studio for crash logs
  • Verify all required permissions are in AndroidManifest.xml
  • Confirm minimum SDK version is compatible
  • Check for missing native dependencies
  • Ensure proper ProGuard rules if using code obfuscation

Network Connection Issues

Problem: App cannot connect to backend services.

Solutions:

  • Verify INTERNET permission in AndroidManifest.xml
  • Check that API endpoints are accessible from external networks
  • Confirm network security configuration allows connections to test servers
  • Test endpoint connectivity from a web browser

Wrong Environment

Problem: App connects to production instead of test environment.

Solutions:

  • Double-check build.gradle configuration
  • Verify build variant is debug or staging (not release)
  • Check for hardcoded production URLs in code
  • Confirm environment variables are properly set

Build Variants and Flavors

If your project uses product flavors:

android {
    flavorDimensions "environment"
    productFlavors {
        staging {
            dimension "environment"
            applicationIdSuffix ".staging"
            // Use this variant for Pie testing
        }
        production {
            dimension "environment"
            // Don't use for testing
        }
    }
}

To build a specific flavor:

  1. Open Build Variants panel (usually on the left side)
  2. Select the desired variant (e.g., stagingDebug)
  3. Build the APK as described above

API Level Compatibility

Ensure your app is compatible with Pie’s testing infrastructure:

  • Minimum SDK: API 21 (Android 5.0) or higher recommended
  • Target SDK: Use recent versions for best results
  • Test on: Latest available Android versions in AVD

Next Steps

After preparing your Android build:

  1. Upload it to Pie’s upload portal
  2. Review the Post-Upload Requirements
  3. Pie’s AI agents will begin testing within 30 minutes

Need Help?

Contact Pie Labs support with:

  • Android Studio version
  • Gradle version
  • Build errors or Logcat output
  • Screenshot of any error dialogs
  • Description of the issue you’re experiencing
React Native iOS AppsPost-Upload Requirements