Instrumentation API
Table of Contents
Overview
Often times, an app needs to be prepared for testing in a special way in which the app development team cannot provide for many reasons. Instrumention should be used to prepare a performance profiler-ready version of the original app.
Most tests and automations done on HeadSpin already include instrumentation as a part of the process, and you will not need to use this API.
Use Cases
Some use cases include, but are not limited to:
- Allowing a custom user root certificate in order to decrypt traffic.
- Allowing traffic from Adobe Air-based apps to be decrypted without a warning from the Air runtime during profiling
- Unpinning certificate pinning from OkHTTP3 apps
- Making Webview-based apps remote-debuggable
All of which our instrumentation engines provide support.
Instrumentations
Listed below are all available instrumentation engines for Android platform.
👋 Instrumentations that don't apply to an app will noop and leave the app untouched. For instance, a non-Adobe Air app will not be affected by AdobeAirCertCheck instrumentation, although some analysis time still incur.
API
The following are available instrumentation API endpoints.
- Download an instrumented app
- Apply instruments to an app in the database by apk ID
- Apply instruments to an app in the database by package name
- Upload an apk then download an instrumented version
Download an instrumented app
Before downloading or instrumenting, the base apk should be uploaded via Headspin's App upload API endpoint . Alternatively, the <code class="dcode">/v0/apps/apk/instrument</code> route below can be used to upload an apk and then download an instrumented version in one API call.
When using <code class="dcode">cURL</code>, the app will be downloaded through HeadSpin data server (not API server), and therefore an <code class="dcode">-L</code> flag will be necessary.
Optional Parameters
To download an existing app with specific instrumentations, use the ?instr parameter:
- <code class="dcode">?instr={instr1}</code>
- <code class="dcode">?instr={instr1}&instr={instr2}&instr={instr3}</code>
If no <code class="dcode">?instr</code> is given, an unedited, uninstrumented version of the app will be downloaded.
If the requested app with those instrumentations doesn't already exist in our database, a <code class="dcode">404</code> http response will be sent. Instead of the <code class="dcode">404</code> response, if you wish to create and download a new, instrumented version of the app, use the <code class="dcode">?instrument_in_place</code> parameter:
- <code class="dcode">?instrument_in_place=true</code> to create and download a version of the app with the specified instrumentations if one is not found in the database.
Example
To download a previously store, unedited APK:
To download a previously stored APK with the NetworkSecurity instrument applied:
To download a previously stored APK with both the NetworkSecurity and ActivityCollector instruments applied, or apply these instrumentations if not found:
The above two examples only work if there is already an existing APK with these instrumentation in our database.
Response
- A JSON object: <code class="dcode">{"status": "App not found", "status_code": 404}</code> if there's no package with that name in HeadSpin's apk database. Check that you have the correct package name, or use the <code class="dcode">/v0/apps/apk/instrument</code> route.
- The binary of the instrumented apk if the app package was found. When using <code class="dcode">cURL</code>, to save this as a file, use the flag <code class="dcode">-o {filename}</code>.
Apply instruments to an app in the database apk ID
You can apply instrumentations to an existing apk and store it in the database with the following endpoint:
The desired instruments should be declared with the use of query parameters.
Parameters
To apply instrumentations, use the <code class="dcode">?instr</code> parameter:
- <code class="dcode">?instr={instr1}</code>
- <code class="dcode">?instr={instr1}&instr={instr2}&instr={instr3}</code>
- <code class="dcode">?force_exported=true</code> to make private activities public. You should only use it if you want to test the functionalities of your app's private activities. This is <code class="dcode">false</code> by default.
Example
To apply the <code class="dcode">NetworkSecurity</code> and <code class="dcode">ActivityCollector</code> instrumentations to an apk in the database:
Response
- <code class="dcode">{"instrumented_apk_id": "<apk-id>"}</code> if the apk is successfully instrumented.
- <code class="dcode">{"status_code": 404, "status": "Failed to find apk with apk_id <apk-id>."}</code> if the apk is not found.
Apply instruments to an app in the database by package name
You can apply instrumentations to an existing apk (the previously uploaded base apk) and store it in the database with the following endpoint:
Request Body
The request body should contain a JSON object, <code class="dcode">{"instrs"}</code>, with the list containing the names of the desired instruments. For example: <code class="dcode">{"instrs": ["NetworkSecurity", "ActivityCollector"]}</code>
To include this in the body of your cURL request, use the -d flag.
Optional Parameters
- <code class="dcode">?force_exported=true</code> to make private activities public. You should only use it if you want to test the functionalities of your app's private activities. This is false by default.
Example
To apply the NetworkSecurity and ActivityCollector instrumenations to a base HealthTest app in the database:
Response
- A JSON object: <code class="dcode">{"status": "App not found", "status_code": 404}</code> if there's no package with that name in HeadSpin's apk database. Check that you have the correct package name, or use the <code class="dcode">/v0/apps/apk/instrument</code> route.
Upload an apk then download an instrumented version
When using <code class="dcode">cURL</code>, the app will be downloaded through HeadSpin data server (not API server), and therefore an -L flag will be necessary.
Request Body
The body should include a binary of your apk. To include your apk binary, use the <code class="dcode">cURL</code> argument <code class="dcode">--data-binary "@path/to/your/apk.apk"</code>.
Optional Parameters
To download an existing app with specific instrumentations, use the ?instr parameter:
- <code class="dcode">?instr={instr1}</code>
- <code class="dcode">?instr={instr1}&instr={instr2}&instr={instr3}</code>
- <code class="dcode">?force_exported=true</code> to make private activities public. You should only use it if you want to test the functionalities of your app's private activities. This is <code class="dcode">false</code> by default.
If no ?instr is given, a list of default instrumentations will be applied. That list is:
- <code class="dcode">NetworkSecurity</code>
- <code class="dcode">Debuggable</code>
Example
Response
- The binary of the instrumented apk saved to your specified location. When using <code class="dcode">cURL</code>, to save this as a file, use the flag <code class="dcode">-o {path/filename}</code>.
