Content Comparison

...

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

1. Create an instance of NMApiCredentials with mandatory parameters (account ID, password, email ID, service ID) with one of the methods provided.

2. 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.

3. 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.

...

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

[NMSdk obtainApiKeyWithCredentials:credentials apiKeyType:NMApiKeyTypeDefault completion:^(NSString * _Nullable apiKey, NSString * _Nullable newApiToken, 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.apiKeyapiKeys = @{@(NMApiKeyTypeDefault): apiKey};
        // [navmiiSDK startWithSettings:configurationSettings completion:nil];
    }];
});

...

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

...

    func requestApiKey() async throws -> String {
        return try await NMSdk.obtainApiKey(withCredentials: credentials, apiKeyType: .tiles)
    }

1.2 Obtaining a key for the offline SDK

To obtain a key for the offline SDK call the
+(void)obtainApiKeyWithAccountAuthenticationToken:completion: static method, passing the account authentication token and a completion to receive a new API key and a new account token.

Example:

Objective-C

NSString *token = @"your-api-token";
[NMSdk obtainApiKeyWithAccountAuthenticationToken:token completion:^(NSString * _Nullable apiKey, NSString * _Nullable newAccountAuthenticationToken, 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.apiKeys = @{@(NMApiKeyTypeDefault): apiKey};
        // [navmiiSDK startWithSettings:configurationSettings completion:nil];
        
        // An optional parameter `newAccountAuthenticationToken` returned in cases 
        // where the account authentication token is near expiry or explicitly changed by the customer.
        // The SDK must update its internal state to use this new account authentication token
        // for subsequent API key requests (if applicable). This behavior aligns with the security policy
        // to maintain secure interactions.
     }];
});

2. Storing the API Key Securely

...

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

NSString *storedApiKey = // Retrieve the stored API key
[navmiiSDK updateApiKey:storedApiKey withType:NMApiKeyTypeDefault];

...

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

Objective-C

NSString *storedApiKey = // Retrieve the stored API key
[navmiiSDK updateApiKey:storedApiKey withType:NMApiKeyTypeTiles];

...

1. 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.

2. 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

@interface MyApiKeyExpiredListener: NSObject<NMApiKeyExpireListener>
@end

@implementation MyApiKeyExpiredListener

- (void)onApiKeyExpired:(NMApiKeyType)apiKeyType {

}

@end

MyApiKeyExpiredListener *listener = [[MyApiKeyExpiredListener alloc] init];
[navmiiSDK addApiKeyExpiredListener: listener];

...

5. 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

[navmiiSDK removeApiKeyExpiredListener: listener];

...

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

Objective-C

BOOL isApiKeyExpired = [navmiiSDK isApiKeyExpiredForType: NMApiKeyTypeDefault];

...