Order File Integration

Building

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 have a job set up for this, you'll need to create one. This job should build release versions of your app from the latest commit on your main or release branch. The frequency of these builds isn't strict, but you should aim to generate at least 25 builds before the final release to ensure the order file is fully optimized. It's recommended that the upload interval is at least 1 hour longer than your average build time to ensure you're always using the most up-to-date order file.

Once this new job is created, you can follow the steps below.

1. Pull the most recent order file from Emerge

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

Make a 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.

2. Ensure the order file is used to link your app

Using Xcode

Set the “Order File” build setting under “linker settings” to the path of your order file

Using 3rd party build system

Add -Wl,-order_file,file_path, -Wl,-order_file_statistics to your linker flags

3. Upload your app to Emerge

Using Emerge's Fastlane Plugin

Modify your 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 (/upload or /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.

Measuring

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.

Total app launch

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.

Pre-main time

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.

Validating

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.