Application Registration

Once an app has been integrated with the Approov technology, the app package generated from it has to be registered with the Approov service. This is done by running a registration application.

Registering your application with the Approov cloud service requires:

  1. A signed application which is ready for distribution. It needs to contain the Approov library.
  2. The Approov registration utility.
  3. A token which you receive in your welcome email.
  4. An active internet connection during the registration process.

To register the application package, you need to run the registration utility on your application. The utility will collect some information about your application and the embedded Approov library, sending the collected information to the Approov service. To authenticate this operation, a registration token is needed.

The registration utility can be downloaded from the Admin Portal.

The registration token is a unique key which is only needed during initial registration and after subsequent application updates. Keep it safe! The token should never be shipped with your actual application. It is important not to distribute the registration token to anyone and not to add it to your application package by mistake.

The registration utility is a command-line program which is invoked on a developer’s desktop.

You can register an app temporarily by supplying the –expireAfter parameter, followed by a duration of the form 1d5h30m15s. The app will then only receive valid tokens from the time of registration until the end of its expiry period. This can be helpful when building apps as part of development or inside a continuous integration environment.

Android Registration

For every unique APK you distribute, you need to perform this registration step once. This means that for an APK that contains all the native libraries for multiple supported architectures you will just need to register once. If you build different APKs for different architectures, or otherwise split your application over multiple APKs, you will need to register each APK individually. You will also need to repeat this registration step each time you modify a registered application either by modifying existing code, or by adding or deleting resources.

The Android registration utility works under Windows, Linux or macOS, with the following arguments:

./registration -a <Path to apk> -t <Path to registration token>

The registration executable has been tested on Windows 7, Windows 8.1, Windows 10, Ubuntu 16.04 and OS X (10.11.6)

Registration Tool Arguments

Option Description
-h, –help Show this help message and exit
-a APKPATH, –apkPath APKPATH Path to your Android apk
-t TOKENPATH, –tokenPath TOKENPATH Path to your Approov Registration Token
-e EXPIREAFTER, –expireAfter EXPIREAFTER Duration for a temporary registration, after which the app will fail to attest. (e.g 2d, 3h, 4h30m, 4d10s). By default, registrations are permanent (–expireAfter never)
-u UNZIPPATH, –unzipPath UNZIPPATH Temporary working directory to unzip your app into
-V VERSIONNAME, –versionName VERSIONNAME Version name displayed in the Approov portal as version-name (version-number). If omitted, the apk’s encoded version name will be used.
-v, –version Output the version number of the registration executable

iOS Registration

Registering your application with the Approov cloud service requires a signed application that is ready for distribution and contains the Approov framework, the registration application, a token which you should receive in your welcome email, and an active internet connection during the registration process. The registration token is unique and should only be used during initial registration and subsequent application updates.

If your intention is to submit your application to Apple for App Store approval, you must remove the i386 and x86_64 versions from the Approov framework binary. You can use the following lipo command to do so:

lipo -remove x86_64 Approov.framework/Approov -output Approov.framework/Approov

The registration application is compatible with MAC OS X 10.11 and is a command line tool. The following command completes the registration process:

registration -a MyApplication.ipa -t registration_access.tok

You will need to perform this registration step for every unique iOS application you wish to distribute. You will need to re-register the app if you update the app version string, the bundle identifier or the team identifier.

Note

The Approov framework currently requires applications to be run on physical devices. It is possible to execute an Approov integrated application on any iOS simulator, however the application will not authenticate successfully. While debugging, the library will also fail to authenticate.

Registration Tool Arguments

Option Description
-h, –help show this help message and exit
-a IPAPATH, –ipaPath IPAPATH Path to the ipa file you wish to register
-t TOKENPATH, –tokenPath TOKENPATH Path to your Approov Registration Token
-e EXPIREAFTER, –expireAfter EXPIREAFTER Duration for a temporary registration, after which the app will fail to attest. (e.g 2d, 3h, 4h30m, 4d10s). By default, registrations are permanent (–expireAfter never)
-V VERSIONNAME, –versionName VERSIONNAME Version name displayed on Approov portal, i.e. your App store version or some other identifier. If omitted, the App store version short name will be used.
-v, –version Output the version number of the registration executable

The version name parameter (-V) is used to help you identify which version of your application is registered in the Approov admin portal. The supplied version name may be any string or number.

The version number parameter (-v) is the version of the registration executable. It is nothing to do with your application, it exists to help ensure you are using the correct version of the registration executable.