LoginAuth Framework for Android

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:

1. Register deviceToken for each new Telematics SDK user.
2. Refresh the accessToken (JWT) when it is expired.
3. Authorize existing SDK user
4. Get authorized user profile info
5. 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

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.

Setup

Here you can find a short video guide, how to add LoginAuth Framework to your Android app:

1. Add our maven-repository to your build.gradle file:

maven {
    url "https://s3.us-east-2.amazonaws.com/android.telematics.sdk.production/"
}

2. Import library:

dependencies {
    implementation "com.telematicssdk:auth:1.1.0"
}

3. If you are using R8 or ProGuard add this line to options:

-keep public class com.telematicssdk.auth.** {*;}

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 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:

• email
• phone
• firstName
• lastName
• address
• birthday
• gender
• maritalStatus
• childrenCount
• clientId

    TelematicsAuth.createDeviceToken(
            instanceId = "<your instanceId>",
            instanceKey = "<your instanceKey>"
            email = "[email protected]",
            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()                
            }

Refresh Access Token

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.

Get Access Token for existing SDK users

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.

Refresh Access Token or Login

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.

Additional methods

Get User Profile

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()    
        }

Update User

    TelematicsAuth.updateUserProfile(
       instanceId = "<your instanceId>",
       instanceKey = "<your instanceKey>",
       deviceToken = "<your deviceToken>",
       accessToken = "<your accessToken>",
       email = "[email protected]",
       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!

Links

Official product Web-page

Official API services web-page

Official API references

Official ZenRoad web-page

Official ZenRoad app for iOS

Official ZenRoad app for Android

Official ZenRoad app for Huawei

Copyright © 2020-2021 DATA MOTION PTE. LTD. All rights reserved.