Installation Guide Part 3
This page covers the undimmed parts of the flow.
Using the research dashboard, you can build and use your own OmniTrack app, connected to your server.
This is the master version of OmniTrack, where the full functionalities are unlocked, and exclusive to researchers. We call this a master app hereinafter.
With the master app, you can do the following things:
- You can use every feature in OmniTrack.
- You can export the tracking components designed with the master app, and use them to define tracking plans to be deployed to the study participants.
After signing in the research dashboard, go to Settings on the top navigation bar.
On the Unlocked OmnitTrack Apps panel, click Initialize to initialize a new build config for Android.
Then, a configuration panel will be initialized.
A package name is a unique key that the Android OS distinguishes the apps. The convention is to reverse the parts of the domain of an website of you or your affiliation, and append the app-specific suffixes. For example, if your affiliation is hcil.snu.ac.kr, kr.ac.snu.hcil.omnitrack would be a reasonable, unique package name.
The default value is io.github.omnitrack.[YOUR_EMAIL_ID]. You can change this.
Note that the master app is on a higher level than the experiments in your server. You should maintain only one package name for the master app on your server, and do not put the experiment-specific suffix on the package name.
To deploy the APK file to participants' Android devices, you should sign the APK file with your own keystore. The keystore file usually has (.jks) extension and you can use a single keystore file in signing multiple apps.
A keystore file contains one or more keypairs, and each keypair is used for signing an Android app. However, you can use a single keypair for signing all of your OmniTrack android apps, including the master app and the experiment apps.
If you don't have your own keystore file yet, you can generate one in the build configuration panel.
-
Click Create New Keystore button.
-
Fill form cells in the dialog, and click Generate & Download to generate the keystore file and download.
You must memorize the following three variables:
- Keystore password (or store password): A main password for the keystore itself.
- alias: an alias of keypair. The alias is used as an ID.
- key password (or keypair password): a password of keypair. This can be the same value as the keystore password.
-
Register your jks file to the Keystore file field, and fill up the other fields.
After configuring the keystore information, click Save Changes & Validate the Keystore:
If the information is all set and valid, the button will be replaced with this message:
If the information is incomplete or invalid, the panel will notify this:
You cannot start a build process until the keystore settings are verified.
Because the OmniTrack app makes use of other self-tracking services, you should insert your API key of these services if you want to integrate them. If you do not set the API keys, such services will not be displayed in the app.
One important API key you should add in most cases is the Google Maps API key, as the Location fields use a Google map view. Follow our guide to get a Google Maps API key.
Register the API keys in the Third-party service credentials pane:
After you finish the configuration, click the Start Build button on the bottom of the panel.
The build process will take about 5 ~ 10 minutes depending on the performance of the server machine. The build process is done asynchronously in the server, so turning off the browser won't hurt the process.
On the panel, you can check whether the build process is ongoing or not:
After the build process finishes, you can see the client information on the Client Binaries list:
You can directly download the installation file, or copy a shortened URL to share with you or colleagues.
Do NOT share a master app with study participants. When you conduct an experiment, you will build the experiment-specific version of the OmniTrack app and deploy it to your study participants.
To use the master app, install the app on your Android device and run the app.
- (a): This is the first screen you will see. Tap "Create New Account" to create a new account.
- (b): You can register the account using an arbitrary username, but use the e-mail address that you use for the research dashboard.
- (c): After you successfully create an account, you can use all the features of the OmniTrack app.
Now you are done with the installation. Refer to Starting a New Experiment to start your first experiment with OmniTrack!