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
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
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.
Here you can find a short video guide, how to add LoginAuth Framework to your Android app:
- Add our maven-repository to your
build.gradlefile:
maven {
url "https://s3.us-east-2.amazonaws.com/android.telematics.sdk.production/"
}- Import library:
dependencies {
implementation "com.telematicssdk:auth:1.1.0"
}- If you are using R8 or ProGuard add this line to options:
-keep public class com.telematicssdk.auth.** {*;}
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 quiestions on how to obtain the credentails, please refer to the documentation
TelematicsAuth.createDeviceToken(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>"
)
.onSuccess {
it.deviceToken
it.accessToken
it.refreshToken
}
.onError { e ->
e.printStackTrace()
}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.
Additionally, you can create a user's deviceToken and get the necessary keys (accessToken, 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:
- phone
- firstName
- lastName
- address
- birthday
- gender
- maritalStatus
- childrenCount
- clientId
TelematicsAuth.createDeviceToken(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>"
email = "mail@mail.mail",
phone = "+10000000000",
clientId = "idOptional",
firstName = "TELEMATICS_USERNAME",
lastName = "TELEMATICS_LASTNAME",
birthDay = "1970-01-01",
maritalStatus = MaritalStatus.Married,
childrenCount = 0,
address = "CITY",
gender = Gender.Male
)
.onSuccess {
it.deviceToken
it.accessToken
it.refreshToken
}
.onError { e ->
e.printStackTrace()
}Each accessToken has a limited lifetime and in a certain period of time it is expired. As a result, when you call our API using invalid accessToken you will receive an Error Unauthorized 401.
Error 401 indicates that the user's accessToken has been expired. If so, as the first step, you have to update the accessToken.
To update the accessToken, you are required to provide the latest accessToken & refreshToken to the method below.
TelematicsAuth.refreshToken(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>",
accessToken = "<your accessToken>",
refreshToken = "<your refreshToken>"
)
.onSuccess {
it.accessToken
it.refreshToken
}
.onError {e ->
e.printStackTrace()
}In response, you will receive a new accessToken and refreshToken.
During the app usage, there may be several scenarios when the app loses accessToken, 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 accessToken for a particular user throught providing DeviceToken
To use this method, 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 accessToken & refreshToken.
TelematicsAuth.login(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>",
deviceToken = "<your deviceToken>"
)
.onSuccess {
it.accessToken
it.refreshToken~~~~
}
.onError {e ->
e.printStackTrace()
}In response, you will receive a new accessToken and refreshToken.
Refreshes accessToken when it expires or authorises user using instanceId, instanceKey and deviceToken when refreshToken expires.
TelematicsAuth.refreshTokenOrLogin(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>",
deviceToken = "<your deviceToken>" ,
accessToken = "<your accessToken>",
refreshToken = "<your refreshToken>"
)
.onSuccess {
it.accessToken
it.refreshToken
}
.onError {e ->
e.printStackTrace()
}In response, you will receive a new accessToken and refreshToken.
You can always request information about the user profile anytime:
TelematicsAuth.getUserProfile(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>",
accessToken = "<your accessToken>"
)
.onSuccess {user ->
user
}
.onError {{e ->
e.printStackTrace()
} TelematicsAuth.updateUserProfile(
instanceId = "<your instanceId>",
instanceKey = "<your instanceKey>",
deviceToken = "<your deviceToken>",
accessToken = "<your accessToken>",
email = "mail@mail.mail",
phone = "+10000000000",
clientId = "idOptional",
firstName = "TELEMATICS_USERNAME",
lastName = "TELEMATICS_LASTNAME",
birthDay = "1970-01-01",
maritalStatus = MaritalStatus.Married,
childrenCount = 0,
address = "CITY",
gender = Gender.Male
)
.onSuccess {
}
.onError {
}That's it! Now you are ready to use our authorization library.
Also you can check references in our doc.
Happy coding!
Official API services web-page