The most common way to integrate with Emerge Order File Optimization is by including a small number of steps in your release build pipeline.
Order files require periodic release builds to generate. If you don’t currently have such a job in place, then you will need to construct one. Roughly speaking, this job should create release builds of your app off the most recent commit to your main/release branch. The cadence of this job isn’t strict - as long as you have a build created at least every ~10 hours, you will end up with a fully optimized order file.
Once this new job is created, you can follow the steps below.
Note: Start with step 2 for the first build of a new version (no order file exists yet)
Using Emerge's Fastlane Plugin
Include the following in your fastfile:
emerge_order_file(app_id: 'com.example.app', order_file_version: '1.2.3', output_path: '/tmp/orderFile')
Pulling the order file manually
GET request to
https://order-files-prod.emergetools.com/<com.example.app>/1.2.3, with the header ”X-API-Token” set to your Emerge API token.
Note that the downloaded order files are compressed using gzip. Ensure that you unzip the file before using its contents. You can use the command following command to do this:
gunzip -c ORDER_FILE.gz.
Set the “Order File” build setting under “linker settings” to the path of your order file
Using 3rd party build system
-Wl,-order_file,file_path, -Wl,-order_file_statistics to your linker flags
Using Emerge's Fastlane Plugin
emerge fastlane call to set the parameter
orderFileVersion to your app version (‘1.2.3’ in the examples above).
Using Emerge's API Directly
Modify your Emerge upload request (
/uploadWithLink) and set the parameter
orderFileVersion to your app version (‘1.2.3’ in the examples above)
When preparing your final release to the app store, ensure that the build has been linked with the most recent order file (step 1 and 2).
That's it! The output of step 1 will always give the most up-to-date order file for an app version. As long as you have 20+ builds per release cycle, then you will have a fully optimized order file by the end of your release cycle.
There are two numbers that should be logged to understand how order files affect app launch: total app launch and pre-main time.
Metric measurements note
All metrics should be collected at percentiles, such as p50, p75, p95, as well as the mean. The OS may cache pages of app memory between launches making order files more applicable to higher percentiles, but this depends on your app's usages patterns.
The most important metric is the total app launch. Measured from process start to the point in your code where the app launch notification is posted.
The second metric is pre-main time (optional). Measure this as time from process start to when the
main function is called. Depending on the structure of your codebase, this time may or may not be affected by order files. Having this metric can help debug any issues that come up during validation testing.
Measuring order files in production is difficult for typical mobile release schedules because changes caused by the order file can't be separated from changes introduced by all other changes since the last release. To measure the true effect in production order files need to be isolated from other changes. To do this, wait until you have sufficient data to measure app launch after a normally scheduled release, and then release a new build with only order files added.
The startup time difference between the two releases can then be compared to see how much of an impact order files have on your app launch. When comparing startup times make sure you choose date ranges that are comparable. The first few days of a release often have much slower launches because users are opening the version for the first time, so caches aren't built yet. For example, if you released the order file version 3 days ago, compare the p95 of the app launch time with the order file to the p95 of the first 3 days of data for the previous release. Some apps also have weekly patterns - like more usage on the weekend. This is good to watch out for, since it could skew the data for just one release.
Updated 7 months ago