Uploading Basics

To manually upload a local build, navigate to the Uploads page and click on "Upload a local build".

For information on automating uploads, check out integrating into CI.

Supported artifacts

Emerge supports the following upload formats:

Zipped XCArchive (preferred).zip (zipped .xcarchive)iOS
IPA (basic support).ipaiOS
Zipped XCFramework.zip (zipped .xcframework)iOS
Android App bundle.aabAndroid
Zipped APK(s) with proguard mappings.zip (zipped .apks(s) with a proguard.txt, mapping.txt proguard.pro, or proguard.map mapping file included).

Note: We require one APK (the primary APK if uploading multiple APKs) to be named base.apk.
Zipped AAB with optional test APK.zip (zipped .aab with an optional .apk test APK leveraging Emerge's test SDK)Android

Obtain an API key

On your Emerge settings page click the button to Create a new API Key. Make sure you save the resulting key, as you won't be able to view it again on the Emerge site.


Debugging symbols

Debugging symbols allow us to symbolicate your app symbols back into human-readable functions and classes, making our analysis easier to understand. To enable this feature, configure the following build setting for your app target and framework targets:

Debug Information Format = DWARF with dSYM File

This will generate .dSYM files alongside your app binaries in a top-level dSYMs directory in your XCArchive folder.


Linkmaps are generated during the linking phase when building your app and give us additional context for analyzing your app symbols. If you're building with Xcode, enable linkmap generation by configuring the following build settings:

Write Link Map File = YES

When uploading your .xcarchive, check to make sure the linkmaps are included in a top-level Linkmaps directory. For example:

- MyApp.xcarchive
  - Info.plist
  - dSYMs
    - MyApp.app.dSYM
  - Products
    - Applications
      - MyApp.app
  - Linkmaps
    - MyApp-LinkMap.txt

Device architecture

We recommend uploading builds targeting arm64 architectures as this is more representative of what your user will download.

Compiler Optimizations

Compiler optimization flags will have a drastic impact on the resulting size and performance of your binary, so we recommend uploading builds with optimizations enabled. See the Swift documentation for Optimization Level and Whole Module Optimization.


Proguard and R8

Tools like Proguard and R8 will obfuscate the final code that makes it into your app binary. For the best results, we recommend including the resulting "mapping file" generated by these tools alongside your app in a zipped upload. This allows us to de-obfuscate your code back into the original human-readable symbols.

R8 also performs many code optimization techniques such as "tree-shaking" which will have a drastic impact on the resulting size and performance of your binary, so we recommend uploading builds with R8 optimizations enabled.

Setting a tag

Screenshot showing multiple buildTypes

To help separate builds, Emerge lets you set an arbitrary tag for tag on every upload. For example, we recommend setting a separate build type like pull-request for PR's since these builds might not be release quality and pollute your build history. Common examples include:

  • default
  • nightly
  • feature
  • pull-request

Under the hood

To learn more about how our upload process works, check out our REST API documentation.