Framework for iOS app
Configure the simplest way to work with User login and auth
LoginAuth Framework for iOS
Description
This library is created by DATA MOTION PTE. LTD. and allows you to integrate with our UserService API in a few steps.
LoginAuth Framework main functions:
- Register
deviceTokenfor each new Telematics SDK user. - Refresh the
accessToken (JWT)when it is expired. - Authorize existing SDK user
- Get authorized user profile info
- Update authorized user profile info
Credentials
Before you start using the framework, make sure you registered a company account in DataHub and obtained InstanceID andInstanceKEY. If you are new, please refer to the documentation and register your company account in DataHub. Sing Up
LoginAuth Framework setup
Here you can find a short video guide, how to add LoginAuth Framework to your iOS app:
To integrate the framework, you need to perform a few simple steps:
Step 1: Download the LoginAuth.xcframework library from this repository.
Step 2: Copy LoginAuth.xcframework to your iOS project folder where the rest of your project files are located.
Step 3: Open your project in xCode.
Step 4: Go to the first General tab of your project, select your Target.
Step 5: Scroll down to the "Frameworks, Libraries and Embeddeed Content" section.
Step 6: Drag&DropLoginAuth.xcframework from Finder project folder to this section, OR click the "Plus" button below, and select "Add Other" and manually specify the path to the LoginAuth.xcframework location.
Step 7: Add in header AppDelegate.h (or any file need for you) of your project this line #import <LoginAuth/LoginAuth.h>
Step 8: Enjoy!
Basic concepts
deviceToken - is the main individual SDK user identifier for your app. This identifier is used as a key across all our services.
accessToken - or JSON Web Token (JWT) is the main UserService API key, that allows you to get user individual statistics and user scoring by UserService APIs calls.
refreshToken - is a secret key that allows you to refresh the accessToken when it expires.
Methods
Create DeviceToken
Each SDK user has to have a DeviceToken and be associated with the app users. To create DeviceToken please use the method below. To complete a call, you are required to provide instanceId & instanceKey. If you still have questions on how to obtain the credentials, please refer to the documentation
[[LoginAuthCore sharedManager] createDeviceTokenForUserWithInstanceId:@"instanceId"
instanceKey:@"instanceKey"
result:^(NSString *deviceToken, NSString *jwToken, NSString *refreshToken) {
NSLog(@"LoginAuthResponce deviceToken %@", deviceToken);
NSLog(@"LoginAuthResponce jwToken %@", jwToken);
NSLog(@"LoginAuthResponce refreshToken %@", refreshToken);
}];
LoginAuthCore.sharedManager()?.createDeviceTokenForUser(withInstanceId: "instanceId",
instanceKey: "instanceKey",
result: { (deviceToken, jwToken, refreshToken) in
print("Success Create User")
})
Once user is registered, you will receive the user credentails. make sure you pass the Devicetoken to your server and store it against a user profile, then pass it to your App - this is the main user detials that you will use for our services.
Refresh JWT
Each JWTtoken has a limmited lifetime and in a certain period of time it is expired. As a result, when you call our API using invalid JWTtoken you will receive an Error Unauthorized 401.
Error 401 indicates that the user's JWTtoken has been expired. If so, as the first step, you have to update the JWToken.
To update the JWTtoken, you are required to provide the latest JWTtoken & refreshToken to the method below.
[[LoginAuthCore sharedManager] refreshJWTokenForUserWith:@"jwToken"
refreshToken:@"refreshToken"
result:^(NSString *newJWToken, NSString *newRefreshToken) {
NSLog(@"NEW jwToken %@", newJWToken);
NSLog(@"NEW refreshToken %@", newRefreshToken);
}];
LoginAuthCore.sharedManager()?.refreshJWTokenForUser(with: "jwToken",
refreshToken: "refreshToken",
result: { (newJWToken, newRefreshToken) in
print("Success Refresh jwToken & refreshToken")
})
In response you will receive new JWTtokens.
Get JWT for existing SDK users
During the app usage, there may be several scenarios when the app loses JWTtoken, for example if the a user changes a smartphone or logs out. BTW, that is a reason why we strongly recommend you to store the deviceToken on your backend side. deviceToken cannot be restored if it is lost!
We provide you with a simple re-authorization, a method that you can use to get a valid JWTtoken for a particular user throught providing DeviceToken
To use this mehod, you need deviceToken, instanceId, and instanceKey of which group the user belongs. in this case, Devicetoken works as a login, instancekey as a password. Then you can re-login the user and get a valid JWTtoken & refreshToken.
[[LoginAuthCore sharedManager] getJWTokenForUserWithDeviceToken:@"deviceToken"
instanceId:@"instanceId"
instanceKey:@"instanceKey"
result:^(NSString *jwToken, NSString *refreshToken) {
NSLog(@"NEW JWT by DEVICETOKEN %@", jwToken);
NSLog(@"NEW REFRESHTOKEN by DEVICETOKEN %@", refreshToken);
}];
LoginAuthCore.sharedManager()?.getJWTokenForUser(withDeviceToken: "deviceToken",
instanceId: "instanceId",
instanceKey: "instanceKey",
result: { (jwToken, refreshToken) in
print("Success Getting New jwToken & refreshToken by DeviceToken")
})
In response, you will receive a new jwToken and refreshToken.
Additional methods
Create DeviceToken with Parameters
Additionally, you can create a user's deviceToken and get the necessary keys (JWTtoken, refreshToken ) with additional parameters. This is not a required method, it just allows you to store the user profile in a different way. You can specify the below given parameters when creating a user's deviceToken:
- userEmail
- userPhone
- firstName
- lastName
- address
- birthday
- gender
- maritalStatus
- childrenCount
- clientId
[[LoginAuthCore sharedManager] createDeviceTokenForUserWithParametersAndInstanceId:@"instanceId"
instanceKey:@"instanceKey"
email:@"[email protected]"
phone:@"+10000000000"
firstName:@"TELEMATICS_USERNAME"
lastName:@"TELEMATICS_LASTNAME"
address:@"CITY"
birthday:@""
gender:@"Male" // String Male/Female
maritalStatus:@"1" // String 1/2/3/4 = "Married"/"Widowed"/"Divorced"/"Single"
childrenCount:@"0" // String count 1-10
clientId:@"idOptional" result:^(NSString *deviceToken, NSString *jwToken, NSString *refreshToken) {
NSLog(@"UserServiceResponce deviceToken %@", deviceToken);
NSLog(@"UserServiceResponce jwToken %@", jwToken);
NSLog(@"UserServiceResponce refreshToken %@", refreshToken);
}];
You can always request information about the user profile anytime:
[[LoginAuthCore sharedManager] getUserProfileWithInstanceId:@"instanceId"
instanceKey:@"instanceKey"
jwToken:@"jwToken" result:^(NSString *email, NSString *phone, NSString *firstName, NSString *lastName, NSString *address, NSString *birthday, NSString *gender, NSString *maritalStatus, NSString *childrenCount, NSString *clientId) {
NSLog(@"Success fetch user profile");
//
}];
And also, update the user profile with the following method:
[[LoginAuthCore sharedManager] updateUserProfileWithParametersAndInstanceId:@"instanceId"
instanceKey:@"instanceKey"
jwToken:@"jwToken"
email:@"[email protected]"
phone:@"+10000000000"
firstName:@"TELEMATICS_USERNAME"
lastName:@"TELEMATICS_LASTNAME"
address:@"NEWCITY"
birthday:@""
gender:@"Male" // String Male/Female
maritalStatus:@"1" // String 1/2/3/4 = "Married"/"Widowed"/"Divorced"/"Single"
childrenCount:@"5" // String count 1-10
clientId:@"idOptionalNew" result:^(NSString *result) {
NSLog(@"Success update user profile");
}];
Happy coding!
Links
Official API services web-page
Official ZenRoad app for Android
Official ZenRoad app for Huawei
Copyright © 2020-2021 DATA MOTION PTE. LTD. All rights reserved.
Updated over 2 years ago