API key management

These instructions are only applicable to users who do not have a persistent API key. Persistent API keys do not expire and can be included in the AndroidManifest.xml file.

1. Obtaining an API Key

When using the SDK for the first time, you need to obtain an API key. To do this, follow the steps below.

1.1 Obtaining a key using ApiCredentials

Create an instance of ApiCredentials.Builder.
Set the necessary parameters (account ID, password, email ID, service ID) on the Builder instance using the provided setter methods.
Call the build() method on the Builder instance to create an ApiCredentials instance.
Call the Sdk.obtainApiKey() static method, passing a key type, the ApiCredentials instance and an ObtainApiKeyWithCredentialsListener to receive the new API key.

Example:

ApiCredentials credentials = new ApiCredentials.Builder()
        .setAccountId("yourAccountId")
        .setPassword("yourPassword")
        .setEmailId("yourEmail")
        .setServiceId(111)
        .build();

Sdk.obtainApiKey(ApiKeyType.DEFAULT, credentials, new ObtainApiKeyWithCredentialsListener() {
    @Override
    public void onApiKeyObtained(String apiKey) {
        // Store the received API key securely
        // Pass the key to the SDK via Sdk.ConfigurationSettings
    }
    @Override
    public void onObtainApiKeyFailed(int errorCode, String errorMessage) {
        // Handle the error
    }
});

If you need to use a separate key for tile servers, it can be obtained using the same method:

ApiCredentials credentials = new ApiCredentials.Builder()
        .setAccountId("yourAccountId")
        .setPassword("yourPassword")
        .setEmailId("yourEmail")
        .setServiceId(222)
        .build();

Sdk.obtainApiKey(ApiKeyType.TILES, credentials, new ObtainApiKeyWithCredentialsListener() {
    @Override
    public void onApiKeyObtained(String apiKey) {
        // Store the received API key securely
        // Pass the key to the SDK via Sdk.ConfigurationSettings
    }
    @Override
    public void onObtainApiKeyFailed(int errorCode, String errorMessage) {
        // Handle the error
    }
});

1.2 Obtaining a key for the offline SDK

To obtain a key for the offline SDK call the Sdk.obtainApiKey() static method, passing the account authentication token and an ObtainApiKeyWithAccountAuthenticationTokenListener to receive the new API key.

Sdk.obtainApiKey("token", new ObtainApiKeyWithAccountAuthenticationTokenListener() {
    @Override
    public void onApiKeyObtained(String apiKey, String newAccountAuthenticationToken) {
        // Store the received API key securely
        // Pass the key to the SDK via Sdk.ConfigurationSettings
        // If the `newAccountAuthenticationToken` is not empty, it has to be used
        // for the subsequent calls to Sdk.obtainApiKey() instead of the original one.
    }
    @Override
    public void onObtainApiKeyFailed(int errorCode, String errorMessage) {
        // Handle the error
    }
});

2. Storing the API Key Securely

After obtaining the API key, store it securely within your app. This ensures the key is available for use in future SDK initialization without needing to request a new key every time.

3. Setting the API Key

When initializing the SDK, pass the stored API key to the Sdk.ConfigurationSettings. To update the key after the SDK has been initialized, use the setApiKey() method:

String storedApiKey = // Retrieve the stored API key
Sdk.getInstance().setApiKey(ApiKeyType.DEFAULT, storedApiKey);

If you have a separate key for tile servers, call this method again, passing ApiKeyType.TILES as the first argument:

String storedApiKeyForTileServers = // Retrieve the stored API key
Sdk.getInstance().setApiKey(ApiKeyType.TILES, storedApiKeyForTileServers);

4. Handling API Key Expiration

The API key can expire, causing the SDK methods requiring authentication to return the ApiKeyExpired status. There are two ways to handle this situation:

For SDK methods that require authentication and are explicitly called by users, handle the ApiKeyExpired status by obtaining a new API key as described in step 1.
For methods that implicitly make online requests, set up a listener to be notified of API key expiration. Follow the steps below:
1. Create a class that extends ApiKeyExpiredListener.
2. Implement the onApiKeyExpired(ApiKeyType) method to handle the expiration event.
3. Add the listener using the addApiKeyExpiredListener() method. Please note that this method should not be called before the SDK has been initialized.
4. When the listener is triggered, obtain a new API key as described in step 1.