Identity Authentication SDK

Initialization

To initialize the SDK, see SDK Initialization.

Usage

• Send an API request with identity authentication

  // Import header files
  #import <IMSAuthentication/IMSIoTAuthentication.h>
  #import <IMSApiClient/IMSApiClient.h>
  
  // Build the request
  NSString *path = @"/uc/listByAccount";
  NSString *apiVer = @"1.0.0";
  NSDictionary *params = @{};
  IMSIoTRequestBuilder *builder = [[IMSIoTRequestBuilder alloc] initWithPath:path apiVersion:apiVer params:params];
  
  // Specify the authentication type
  [builder setAuthenticationType:IMSAuthenticationTypeIoT];
  
  // Send the request using IMSRequestClient
  [IMSRequestClient asyncSendRequest:builder.build responseHandler:^(NSError * _Nullable error, IMSResponse * _Nullable response) {
      if (error) {
          // Handle the error. Errors not returned by the server-side are returned through this error callback.
      } else {
          if (response.code == 200) {
              // Success. Process response.data.
          }
          else {
              // Handle server-side errors.
          }
      }
  }];
  					

• Handle authentication errors for API requests

  If your app does not support logon from multiple devices, only the last device that logs on with an account can access the IoT service. When other devices that use the same account send API channel requests, they receive an authentication error (error code 401). For more information, see Create an app. This error is also returned if an account is not logged on or its logon information has expired.

  When these authentication errors occur, you can simply handle the API request error and prompt the end user to log on again.

  [IMSRequestClient asyncSendRequest:builder.build responseHandler:^(NSError * _Nullable error, IMSResponse * _Nullable response) {
   if (error) {
       //...
   } else {
       if (response.code == 200) {
           //...
       }
       else if (response.code == 401) {
           // Handle the authentication error.
       }
       else {
           //...
       }
   }
  }];

  If you want to handle this type of authentication error in a unified way, follow these steps.

  1. Inherit from IMSIoTAuthentication to implement a custom identity authentication feature.

     @interface XXCustomAuthentication : IMSIoTAuthentication
     @end
     @implementation XXCustomAuthentication
     
     - (void)handleRequestBeforeSend:(IMSRequest * _Nonnull)request
                             payload:(IMSRequestPayload * _Nonnull)payload
                          completion:(void (^ _Nonnull)(NSError * _Nullable error,
                                                        IMSResponse *_Nullable mockResponse,
                                                        IMSRequestPayload * _Nullable newPayload))completionHandler {
         [super handleRequestBeforeSend:request payload:payload completion:^(NSError * _Nullable error, IMSResponse * _Nullable mockResponse, IMSRequestPayload * _Nullable newPayload) {
             completionHandler(error, mockResponse, newPayload);
     
             if (mockResponse && mockResponse.code == 401) {
                 // Customize the handling of 401 errors, for example, using a toast notification.
                 NSLog(@"before: 401");
             }
         }];
     }
     
     - (void)handleResponse:(IMSResponse * _Nonnull)response
                 completion:(void (^ _Nonnull)(NSError * _Nullable error, IMSResponse * _Nullable response))completionHandler {
         [super handleResponse:response
                    completion:^(NSError * _Nullable error, IMSResponse * _Nullable response) {
                        completionHandler(error, response);
     
                        if (response && response.code == 401) {
                            // Customize the handling of 401 errors, for example, using a toast notification.
                            NSLog(@"after: 401");
                        }
                    }];
     }
     @end

  2. Register the custom identity authentication.

     XXCustomAuthentication *iotAuthDelegate = [[XXCustomAuthentication alloc] initWithCredentialManager:IMSCredentialManager.sharedManager];
     [IMSRequestClient registerDelegate:iotAuthDelegate forAuthenticationType:IMSAuthenticationTypeIoT];

• Obtain user identity credentials

  After an account successfully logs on, you can use the following method to synchronously obtain the user identity credentials.

  #import <IMSAuthentication/IMSCredentialManager.h>
  
  IMSCredential *credential = [IMSCredentialManager sharedManager].credential;
  NSString *identityId = credential.identityId;
  NSString *iotToken = credential.iotToken;

• Refresh user identity credentials

  If the user identity credentials that you obtained using the synchronous method are empty, you can use the following method to force an asynchronous refresh to obtain new user identity credentials.

  #import <IMSAuthentication/IMSCredentialManager.h>
  
  [[IMSCredentialManager sharedManager] asyncRefreshCredential:^(NSError * _Nullable error, IMSCredential * _Nullable credential) {
      if (error) {
          // The refresh failed. For more information, see the IMSCredentialManagerErrorCode error codes.
      } else {
          NSString *identityId = credential.identityId;
          NSString *iotToken = credential.iotToken;
      }
  }];