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.
Updated 23 days ago