Runtime

Fetch Status

When some operation are performed that interact with Approov a fetch status is returned that may be output in the logging. The possible status results are enumerated in the table below. Note that all iOS errors are prefixed by ApproovTokenFetchStatus..

Status (Android / iOS)	Description
SUCCESS / success	Indicates that a fetch call to the SDK was successfully completed. If you are fetching an Approov token then if it was successfully fetched it still might not be valid if the app does not pass its rejection policy. Common reasons for unexpected invalid tokens include forgetting to register new app builds, see registering an app, or because a debugger is attached to the device when a token is requested. Note that you can set a device specific custom always pass security policy to get valid tokens in both the previous scenarios but, if you do, you must take extra care to test your app on a variety devices without a custom policy before release.
UNPROTECTED_URL / unprotectedURL	Indicates that the provided URL is valid but is not one for an API domain that needs to be provided with an Approov token. The request should continue without adding an Approov token. You get this on API domains that have been added with the -noApproovToken option.
UNKNOWN_URL / unknownURL	Indicates that the provided URL is valid but is is not an API domain configured for use, and wildcard mode has not been enabled. You should add the API domain if necessary. The request should continue without adding an Approov token.
NO_APPROOV_SERVICE / noApproovService	Indicates that a fetch operation could not be completed due to the unlikely event that Approov cloud services are completely down (including the failover service) or, more likely, that the account has been cancelled. The error might also occur in some cases of poor network connectivity. In the case of an Approov token fetch we suggest you continue without adding any Approov token to the API call, so that requests can still reach your backend. This is to guard against some catastrophic failure or cancellation of your Approov service. In the case of secure string or custom JWT fetches it is not possible to continue, and you must retry.
NO_NETWORK / noNetwork	Indicates that a fetch operation could not be completed because there is no network connectivity. The SDK checks for network connectivity before making a fetch attempt. This allows a rapid return from the fetch if there is no connectivity. If this error is received then there is no point in proceeding with any following API call which will also require network access. A timed, or user initiated, retry is required.
POOR_NETWORK / poorNetwork	Indicates that a fetch could not be completed due to poor network connectivity. If this error is received then there is no point in proceeding with any following API call which will also require network access. A timed, or user initiated, retry is required.
MITM_DETECTED / mitmDetected	Indicates that there is a Man-In-The-Middle (MITM) in the communication with the Approov cloud service. This may be malicious or may simply indicate that the end user is using a network with a firewall that intercepts all traffic for inspection. If this error is received then there is no point in proceeding with any following API call which will also require network access. A timed, or user initiated, retry is required.
REJECTED / rejected	Indicates that for a secure strings or custom JWT usage the app does not pass the selected rejection policy, so the operation cannot be completed. A suitable message must be presented to the user about why it is not possible to proceed. Common reasons for this include forgetting to register new app builds, see registering an app, or because a debugger is attached to the device when the fetch request is made. Note that you can set a device specific custom always pass security policy but you must take extra care to test your app on a variety devices without a custom policy before release.
BAD_URL / badURL	Indicates that the provided URL is not in the correct format. The URL should just be provided as a domain, although a full URL path may be specified from which the domain is extracted. This error can occur if such a URL is provided with a http:// rather than the https:// scheme.
DISABLED / disabled	Indicates that for a secure strings or custom JWT usage that the appropriate feature is not enabled in the account settings.
UNKNOWN_KEY / unknownKey	Indicates that for a secure strings usage that there is no secure string with the given key value.
NA / badKey	For iOS, indicates that for a secure strings usage the key value provided is invalid, either being empty or longer than the 64 character maximum allowed.
NA / badPayload	For iOS, indicates that for a custom JWT fetch that the payload provided is invalid. It is either too large or is not a valid JSON object.
NO_NETWORK_PERMISSION / NA	For Android, indicates that the app does not have ACCESS_NETWORK_STATE or INTERNET permission.
MISSING_LIB_DEPENDENCY / NA	For Android, indicates that the Approov SDK dependency on the OkHttp library has not been satisfied.
INTERNAL_ERROR / internalError	Indicates there has been an internal error within the SDK. Please contact Approov support if this ever happens.
NA / notInitialized	For iOS, indicates that an attempt is being made to use an SDK method before it has been initialized. Note that the Android SDK generates an exception in this case.

Enabling Token Prefetch On SDK Initialization

If a particular app installation has ever previously fetched an Approov token, then the fast resumption capability of the SDK will cause a fresh fetch to be performed in the background every time the SDK is initialized. This can substantially reduce the latency when the app first uses an Approov token or secure string.

However, if a particular app installation has never previously fetched an Approov token then no resumption can be performed. An option is provided to cause an Approov token prefetch even in these cases to improve latency. This is especially relevant the first time the app is used.

To enable the prefetch capability, use the following command:

approov sdk -setConfigOptions InitFetch

This will output the following if completed successfully:

config options were set successfully

To disable all config options, use the following command:

approov sdk -setConfigOptions none

If you have multiple options selected and wish to remove the InitFetch entry, reissue the original command to set all the options with a comma separated list of entries but omit the InitFetch value.

info

This option only has an impact on 3.5.1 and later SDKs.

Inhibiting Resumption On SDK Initialization

The SDK has a fast resumption capability to fetch an Approov token in the background as part of the SDK initialization. This happens if an Approov token was fetched the previous time the app was launched. This substantially reduces the latency when the app first uses an Approov token or secure string.

An implication of this is that the device ID will appear in the billing for your account even if the app instance does not make any further specific Approov token fetch calls. If you are using a billing plan based on device ID usage then this will likely have no net impact, since a given device ID may be used any number of times in a monthly billing period.

However, it is possible to disable the fast resumption capability in the SDK. If this is used then resumption Approov token fetch on launch is performed, although of course this means that the initial latency to obtain one will be higher when it is required.

To disable the resumption capability, use the following command:

approov sdk -setConfigOptions NoResumption

This will output the following if completed successfully:

config options were set successfully

To disable all config options, use the following command:

approov sdk -setConfigOptions none

If you have multiple options selected and wish to remove the NoResumption entry, reissue the original command to set all the options with a comma separated list of entries but omit the NoResumption value.

info

This option only has an impact on 3.5.0 and later SDKs.

Fetch Latency

The integrity check operation provided by Approov requires the SDK to perform a CPU computation and possibly one or more network requests. For latency purposes the fetch types are categorized as follows:

• Initial Fetch: The initial fetch after the app has been installed for the first time. This timing of this may be impacted by various options used in the Approov account (see below).
• Network Fetch: Fetches when an app is relaunched or when a previously fetched Approov token has expired.
• Cached Fetch: This returns a previously fetched Approov token and/or secure string and does not require much additional computation or any network connection. Typically this information is cached for a period of 5 minutes, after which a Network Fetch is required again. Note that a custom JWT fetch always requires a Network Fetch.

info

If you are using a 3.5 or later SDK then the Network Fetch latency is optimized to allow an Approov token to be fetched more quickly after the app is restarted if a resumption from a previous Approov token fetch is possible. These SDKs are able to initiate a background fetch process as part of the SDK initialize call. This means that the latency experienced by an explicit call to perform the fetch may be much lower (as low as that for a Cached Fetch) although this will depend on the period of time between initialization and the first subsequent fetch that requires a result.

The table below provides an average of values obtained by measuring the performance of fetch operation on a range of devices for both Android and iOS with good network conditions and using the latest SDK version. Note, these devices were located close to one of our AWS points of presence for the Approov cloud. More geographically remote devices will suffer higher average Initial Fetch and Network Fetch latencies due to networking delays beyond our control. Please contact Approov support for a current list of our AWS point of presence or other information regarding latency optimization.

Platform	Initial Fetch	Network Fetch	Cached Fetch
Android	850ms*	500ms**	65ms
iOS	650ms*	450ms	45ms

The type of fetch call made (synchronous or asynchronous) does not impact the overall latency before a result is obtained.

*: These timings may be further impacted if DeviceCheck, AppAttest or Play Integrity options are enabled. These operations require additional network connection(s) and CPU processing time, over which the Approov SDK has no control. The impact will depend on various factors, including the age of the device being used. Expect an additional latency of between 2500ms and 3500ms for each option used, on an applicable platform.

**: If you have added app signing certificates, this will cause an increase to the latency of the first Network Fetch after launching the app by an amount proportional to the size of the APK and the performance of the device on which the app is running. Since the 3.3.0 SDK version this should be negligible on arm64 based devices. On other architectures this will add further delay. For example, a 30MB APK on an entry-level device may take around 1300ms to complete the additional checks.

info

Note that the Approov fetch process itself may make various retries of the communication with the Approov server. Within the SDK, the absolute worst case timeout before the method returns is typically configured to be 30 seconds.