Adjust Store & Pre-Install Tool

If your app is pre-installed on a device, you need to use a pre-install tracker to attribute users. The Adjust Store & Pre-Install Tool (adjust-dtt) enables you to insert this information into your APK. The Adjust SDK reads the information inserted by adjust-dtt. This enables you to attribute users of pre-installed apps to specific Adjust trackers.

Before you begin

To get started, download the adjust-dtt tool from GitHub. You need to make this file executable to use it. Run the following command to make the file executable:

chmod +x adjust-dtt

To run adjust-dtt, you need the following installed on your machine:

1. ruby – the language tools used to run adjust-dtt.
2. apktool – a tool for unpacking and re-packing APKs.
3. jarsigner – a tool for signing APKs.

Installation instructions

brew install apktool

brew install openjdk@16 # use your preferred version number here

Add tools to PATH

For adjust-dtt to work, both apktool and jarsigner need to be present in your shell's PATH variable. Run the following command to determine if they are available on your PATH:

# Returns the location of apktool
which apktool

# Returns the location of jarsigner
which jarsigner

Package managers like brew, apt, dnf, and pacman will add these tools to your PATH when you install them. If you have installed these tools in a different way, you need to add them to your PATH manually.

For example: you could download apktool (1) and jarsigner (2) to the following locations:

To access the tools from your terminal, these directories need to be present on your PATH.

To add new directories to your PATH, you need to edit the PATH variable in your shell run commands (rc) file. This file is usually located in your home directory. It uses the following naming convention: .{shell name}rc.

You can add new directories to your PATH by adding them to your rc file. You should separate each directory entry with a colon (:). Open the relevant file in your preferred editor and add the following to the end of it:

export PATH="/User/username/apktool/:/Library/Java/JavaVirtualMachines/jdk1.8.0_102.jdk/Contents/Home/bin/:$PATH"

Once you have added the directories to your file, save and close it. The sources will be available on your PATH the next time you open a terminal. To make them available immediately, run the following command:

source ~/.zshrc

Congratulations! You now have everything you need to run the adjust-dtt tool.

Add pre-install tracker information

Step 1. Get keystore file

When you create an APK, Android Studio will sign it. This happens even if you have generated an "unsigned" version of the APK. When you do this, Android Studio signs the APK with a default debug signing keystore file. This keystore file is located at ~/.android/debug.keystore by default.

If you export a signed APK from Android Studio, you will sign the APK with your custom signing keystore file.

To use adjust-dtt you need to have access to either the default keystore file or your custom one. This is because apktool will remove all signing when you use it to unpack the APK. Once you repackage the APK, signing is not re-enabled. This means you need to run jarsigner with your signing information to re-sign the APK. You need to re-sign the application to deliver it to Android devices.

Step 2. Create tracker token

Next, you need to create a tracker token in your Adjust dashboard. You will use this tracker as the default tracker for your pre-installed app. This means that all users who have the app pre-installed will be attributed to this tracker.

Step 3. Create a config file

Once you have your keystore file and your tracker token, you can create a configuration file. adjust-dtt uses an adjust-config.yaml configuration file to read your settings. This file includes settings for the different app stores you need to set up.

You can set the following parameters in your adjust-config.yaml:

Below is an example adjust-config.yaml file. This example includes settings for three stores named store_1, store_2, and store_3.

apk_path: /Users/username/Desktop/apk/example-release.apk
keystore_path: /Users/username/Desktop/apk/mykeystore.jks
keystore_pass: mykeystorepass
keystore_alias: mykeystorealias
stores:
    store_1:
        default_tracker: abc123
    store_2:
        default_tracker: abc456
    store_3:
        default_tracker: abc789

You can define global parameters in the root of the file if you want to use the same settings for each store. Parameters set on a store will override the global parameters for that store. For example:

apk_path: /Users/username/Desktop/apk/example-release.apk
keystore_path: /Users/username/Desktop/apk/mykeystore.jks
keystore_pass: mykeystorepass
keystore_alias: mykeystorealias
stores:
    store_1:
        default_tracker: abc123
        keystore_path: /Users/username/Desktop/apk/differentkeystore.jks
        keystore_pass: differentkeystorepass
        keystore_alias: differentkeystorealias
    store_2:
        default_tracker: abc456
    store_3:
        default_tracker: abc789

In this example, the adjust-dtt tool will use differentkeystore.jks, differentkeystorepass and differentkeystorealias when generating the APK for store_1. The tool will generate a modified APK for each store.

Step 4. Run the adjust-dtt tool

The adjust-dtt tool takes the path to the your adjust-config.yaml file as an argument. To add your tracker information to your APK, run the tool like so:

adjust-dtt adjust-config.yaml

When you run the adjust-dtt tool, it does the following:

1. Unpacks your APK into a folder. The folder will be located in the same directory as your APK. It will have the same name as your APK.
2. Searches for an assets folder and an adjust_config.properties file. The adjust_config.properties file contains default tracker information.
   • Creates the assets folder and adjust_config.properties file if they do not exist. The tool writes your default_tracker information to the adjust_config.properties file.
   • Writes the default_tracker information to the adjust_config.properties file if it exists. If the file already contains a default tracker value, it compares the two. If they differ, the value in your adjust-config.yaml file overwrites the existing value.
3. Repackages the APK.
4. Signs the APK with the information specified in the adjust-config.yaml. It uses the keystore_path, keystore_pass, and keystore_alias parameters.
5. Generates an APK with the same name as the original with a _[store_name] suffix. In the above example, the tool generates three APK files. These would be named example-release_store_1.apk, example-release_store_2.apk and example-release_store_3.apk. Once the tool has generated these files, you can rename them.

If you have any questions or issues with this tool, contact support@adjust.com.