This quickstart is written specifically for native Android apps that are written in Java and use HttpsUrlConnection for making the API calls that you wish to protect with Approov. If this is not your situation then check if there is a more relevant Quickstart guide available.

This quickstart provides the basic steps for integrating Approov into your app. A more detailed step-by-step guide using a Shapes App Example is also available.

To follow this guide you should have received an onboarding email for a trial or paid Approov account.

The Approov integration is available via jitpack. This allows inclusion into the project by simply specifying a dependency in the gradle files for the app.

Firstly, jitpack needs to be added to the end the repositories section in the build.gradle file at the top root level of the project:

allprojects { repositories { ... maven { url 'https://jitpack.io' } } } 

Secondly, add the dependency in your app's build.gradle:

dependencies { implementation 'com.github.approov:approov-service-httpsurlconn:3.0.1' } 

Make sure you do a Gradle sync (by selecting Sync Now in the banner at the top of the modified .gradle file) after making these changes.

This package is actually an open source wrapper layer that allows you to easily use Approov with HttpsUrlConnection. This has a further dependency to the closed source Approov SDK.

The following app permissions need to be available in the manifest to use Approov:

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.INTERNET" />

Note that the minimum SDK version you can use with the Approov package is 21 (Android 5.0).

Please read this section of the reference documentation if targetting Android 11 (API level 30) or above.

In order to use the ApproovService you must initialize it when your app is created, usually in the onCreate method:

import io.approov.service.httpsurlconn.ApproovService; public class YourApp extends Application { public static ApproovService approovService; @Override public void onCreate() { super.onCreate(); approovService = new ApproovService(getApplicationContext(), "<enter-your-config-string-here>"); } }

The <enter-your-config-string-here> is a custom string that configures your Approov account access. This will have been provided in your Approov onboarding email.

This initializes Approov when the app is first created. A public static member allows other parts of the app to access the singleton Approov instance. All calls to ApproovService and the SDK itself are thread safe.

You can then make Approov enabled HttpsUrlConnection API calls using the following call on any HttpsUrlConnection connection, before the connection is made:

YourApp.approovService.addApproov(connection);

For API domains that are configured to be protected with an Approov token, this adds the Approov-Token header and pins the connection. This may also substitute header values when using secret protection.

Approov errors will generate an ApproovException, which is a type of IOException. This may be further specialized into an ApproovNetworkException, indicating an issue with networking that should provide an option for a user initiated retry.

Initially you won't have set which API domains to protect, so the any addApproov call will not add anything. It will have called Approov though and made contact with the Approov cloud service. You will see logging from Approov saying UNKNOWN_URL.

Your Approov onboarding email should contain a link allowing you to access Live Metrics Graphs. After you've run your app with Approov integration you should be able to see the results in the live metrics within a minute or so. At this stage you could even release your app to get details of your app population and the attributes of the devices they are running upon.

To actually protect your APIs there are some further steps. Approov provides two different options for protecting APIs:

• TOKEN PROTECTION: You should use this if you control the backend API(s) being protected and are able to modify them to ensure that a valid Approov token is being passed by the app. An Approov Token is short lived crytographically signed JWT proving the authenticity of the call.

• SECRET PROTECTION: If you do not control the backend API(s) being protected, and are therefore unable to modify it to check Approov tokens, you can use this approach instead. It allows app secrets, and API keys, to be protected so that they no longer need to be included in the built code and are only made available to passing apps at runtime.

Note that it is possible to use both approaches side-by-side in the same app, in case your app uses a mixture of 1st and 3rd party APIs.