Order File Integration

๐Ÿ“˜

Linkmaps Required

This feature requires xcarchives with linkmaps included in the upload

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.

1. Upload your app

Using the Fastlane Plugin

Modify your emerge fastlane call to set the parameter orderFileVersion to your app version (ex โ€˜1.2.3โ€™).

Using the API Directly

Modify your upload request (/upload) and set the parameter orderFileVersion to your app version (ex โ€˜1.2.3โ€™)

2. Download the most recent order file

Using the 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 following command to do this: gunzip -c ORDER_FILE.gz.

3. 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

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.