API key management (v2.1.x – 2.2.x)

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 Info.plist 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:

Create an instance of NMApiCredentials with mandatory parameters (account ID, password, email ID, service ID) with one of the methods provided.
Call the + (void)obtainApiKeyWithCredentials:apiKeyType:completion: method, to request a new API Key. A result is expected to come in the completion block. To request a key for general SDK usage, use NMApiKeyTypeDefault API key type. Optionally, map tiles service may require separate authentication, in this case NMApiKeyTypeTiles API key type should be used.
Check received API Key and NSError object. Non-empty error instance indicates a failed request. A type of received error. It’s error code corresponds an error type, specified in NMApiKeyObtainError.

Example:

Objective-C

NMApiCredentials *credentials = [NMApiCredentials alloc] initWithAccountId:@"accountId"
        emailId:@"your@email.com"
        password:@"password"
        serviceId:@(123);

[NMSdk obtainApiKeyWithCredentials:credentials apiKeyType:NMApiKeyTypeDefault completion:^(NSString * _Nullable apiKey, NSError * _Nullable error) {
        // if (error) {
        // Handle error
        // }
        
        // if (apiKey && [apiKey lenght] > 0) {
        // Store the received API key securely
        // Now you can start the SDK
        // [navmiiSDK startWithSettings:configurationSettings completion:nil];
        // } 
        
        // Next time pass the key to the SDK via NMConfigurationSettings object
        // NMConfigurationSettings *configurationSettings = [NMConfigurationSettings new];
        // configurationSettings.apiKey = apiKey;
        // [navmiiSDK startWithSettings:configurationSettings completion:nil];
    }];
});

Swift

    func setupSdk() async {
        do {
            let apiKey = try await requestApiKey()
            // Store the received API key securely
            
            try await startSDK(with: apiKey)
            
        } catch {
            // Handle error
            print(error)
        }
    }
    
    func requestApiKey() async throws -> String {
        let credentials = NMApiCredentials(accountId: "accountId",
                                           emailId: "your@email.com",
                                           password: "password",
                                           serviceId: 456)
        return try await NMSdk.obtainApiKey(withCredentials: credentials, apiKeyType: .default)
    }
    
    func startSDK(with apiKey: String) async throws {
        let settings = NMConfigurationSettings()
        settings.apiKey = apiKey
        return try await sdk.start(withSettings: settings)
    }

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

Objective-C

[NMSdk obtainApiKeyWithCredentials:credentials apiKeyType:NMApiKeyTypeTiles completion:^(NSString * _Nullable apiKey, NSError * _Nullable error) {
});

Swift

2. Storing the API Key Securely

After obtaining the API key, store it securely within your app. Keychain will do the best. 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 NMConfigurationSettings. To update the key after the SDK has been initialized, use the - (void)updateApiKey:withType: method:

Objective-C

Swift

If you have a separate key for tile servers, call this method again, passing NMApiKeyTypeTiles as the second argument:

Objective-C

Swift

4. Handling API Key Expiration

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

For SDK methods explicitly called by users that require authentication, 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 NMApiKeyExpiredListener.
2. Implement the - (void)onApiKeyExpired: method to handle the expiration event.
3. Add the listener using the - (void)addApiKeyExpiredListener method.
4. When the listener is triggered, obtain a new API key as described in step 1.

Example:

Objective-C

Swift

The listener object retains when passed to the method. It you need to remove it when it's no longer needed using the - (void)removeApiKeyExpiredListener: method:

Objective-C

Swift

5. Checking the API Key expiration status

The API Key expiration status can be checked with - (BOOL)isApiKeyExpiredForType: method.

Objective-C

Swift

6. Error handling

+ (void)obtainApiKeyWithCredentials:completion: method provides a convenient way to handle errors received on obtaining process. In the callback NSError shares an error code. Possible values are:

NMApiKeyObtainErrorNoError - means no error received, API Key delivered successfully.
NMApiKeyObtainErrorUnknown - unknown error received.
NMApiKeyObtainErrorNetwork - networking error.
NMApiKeyObtainErrorBadResponse - no API Key obtained, check credentials submitted.
NMApiKeyObtainErrorBadKeyType - unsupported API Key Type provided.