Authentication

Authenticate as a driver with Bringg Cloud Platform Services

Suggest Edits

Overview

Before you can start using other DriverSdk features you must authenticate the user with Bringg Platform Cloud Services.

Bringg Driver SDK provides several ways to authenticate the user with Bringg Platform Cloud Services.
The authentication state is persisted automatically by the SDK for you so login is usually a once in a lifetime operation.

Bringg Platform may logout a user remotely, in such case the SDK will automatically become offline and notify the implementation using LiveData, and immediately after will logout and notify the implementation using LiveData .

Observe authentication state

Login state can be observed using a LiveData object obtained from DriverSdk:

val driverSdk = DriverSdkProvider.driverSdk
driverSdk.data.login.observeForever { isLoggedIn ->
    if (isLoggedIn) {
        Log.i(TAG,"user is authenticated with Bringg Cloud Services")
    } else {
        Log.i(TAG,"user is not authenticated, use driverSdk.login to login")
    }
}

Authentication Methods

You can use the following methods to manage the authentication and login state for the driver:

📘

All login methods return asynchronous result using a DriverLoginResult callback.

All result callbacks are returned on the main thread.

Login with Bringg token and secret

Bringg Plaftorm and Bringg Driver SDK support authentication by generating a login token and secret which can be for example rendered as QR code to be scanned by the user for authenticating.

DriverSdkProvider.driverSdk.authentication.loginWithTokenAndSecret(region, token, secret, object : ResultCallback<DriverLoginResult> {
    override fun onResult(result: DriverLoginResult) {
        if (result.success) {
            Log.i(TAG, "user is successfully authentication with Bringg, DriverSdkProvider.driverSdk.data.login will post TRUE")
        } else {
            Log.i(TAG,"user authentication failed, error=${result.error}")
        }
    }
})

Parameters

region

String

NOT NULLABLE

the region on Bringg Platform that you are trying to login to. see generating a login token and secret

token

String

NOT NULLABLE

authentication token see generating a login token and secret

secret

String

NOT NULLABLE

authentication secret see generating a login token and secret

callback

ResultCallback<DriverLoginResult>

NOT NULLABLE

receive DriverLoginResult model with the action result

Login with email and password

DriverSdkProvider.driverSdk.authentication.loginWithEmail(email, password, object : ResultCallback<DriverLoginResult> {
    override fun onResult(result: DriverLoginResult) {
        if (result.success) {
            Log.i(TAG, "user is successfully authentication with Bringg, DriverSdkProvider.driverSdk.data.login will post TRUE")
        } else {
            Log.i(TAG,"user authentication failed, error=${result.error}")
        }
    }
})

Parameters

email

String

NOT NULLABLE

user email address

password

String

NOT NULLABLE

user password

callback

ResultCallback<DriverLoginResult>

NOT NULLABLE

receive DriverLoginResult model with the action result

Login with phone number and verification code

DriverSdkProvider.driverSdk.authentication.loginWithPhone(phone, verificationCode, object : ResultCallback<DriverLoginResult> {
    override fun onResult(result: DriverLoginResult) {
        if (result.success) {
            Log.i(TAG, "user is successfully authentication with Bringg, DriverSdkProvider.driverSdk.data.login will post TRUE")
        } else {
            Log.i(TAG,"user authentication failed, error=${result.error}")
        }
    }
})

Parameters

phone

String

NOT NULLABLE

user phone number

verificationCode

String

NOT NULLABLE

verification code see requestPhoneVerificationCode

callback

ResultCallback<DriverLoginResult>

NOT NULLABLE

receive DriverLoginResult model with the action result

Login to a specific merchant

A driver on Bringg Plaftom may sometimes be associated with more than a single merchant (a driver having the same email+password or same phone number for multiple Bringg Platform merchants).
When such driver tries to login the login methods will return the failure result MULTIPLE_MERCHANTS with a populated collection of the available LoginMerchant models on Bringg Platform that the user is associated with to enable the implementation to pick the desiered account and continue the login flow using Login with email and password to a specific merchant or Login with phone number and verification code to a specific merchant

Login with email and password to a specific merchant

This method is used to login to a specific merchant in case that Login with email and password returned a failure result MULTIPLE_MERCHANTS with a list of the available merchants on Bringg Platform that the user is associated with.
On that case the result will populate userMerchantList collection object in the result with the available LoginMerchant models for the implementation to pick from and call this method to login.

DriverSdkProvider.driverSdk.authentication.loginWithEmail(email, password, merchant, object : ResultCallback<DriverLoginResult> {
    override fun onResult(result: DriverLoginResult) {
        if (result.success) {
            Log.i(TAG, "user is successfully authentication with Bringg, DriverSdkProvider.driverSdk.data.login will post TRUE")
        } else {
            Log.i(TAG,"user authentication failed, error=${result.error}")
        }
    }
})

Parameters

email

String

NOT NULLABLE

user email address

password

String

NOT NULLABLE

user password

merchant

LoginMerchant

NOT NULLABLE

the specific merchant to login to

callback

ResultCallback<DriverLoginResult>

NOT NULLABLE

receive DriverLoginResult model with the action result

Login with phone number and verification code to a specific merchant

This method is used to login to a specific merchant in case that Login with phone number and verification code returned a failure result MULTIPLE_MERCHANTS with a list of the available merchants on Bringg Platform that the user is associated with.
On that case the result will populate userMerchantList collection object in the result with the available LoginMerchant models for the implementation to pick from and call this method to login.

DriverSdkProvider.driverSdk.authentication.loginWithPhone(phone, verificationCode, merchant, object : ResultCallback<DriverLoginResult> {
    override fun onResult(result: DriverLoginResult) {
        if (result.success) {
            Log.i(TAG, "user is successfully authentication with Bringg, DriverSdkProvider.driverSdk.data.login will post TRUE")
        } else {
            Log.i(TAG,"user authentication failed, error=${result.error}")
        }
    }
})

Parameters

phone

String

NOT NULLABLE

user phone number

verificationCode

String

NOT NULLABLE

verification code see requestPhoneVerificationCode

merchant

LoginMerchant

NOT NULLABLE

the specific merchant to login to

callback

ResultCallback<DriverLoginResult>

NOT NULLABLE

receive DriverLoginResult model with the action result

Login using OpenID Connect protocol

Bringg Plaftom and Bringg Driver SDK supports user authentication using Open ID Connect protocol.
Merchant may be configured on Bringg Platform to restrict user authentication to OIDC protocol only.
When trying to login a user to such merchant the login methods will return a result with error LOGIN_WITH_OIDC and a populated OpenIdConnectLoginConfig model with the required data for OIDC authentication process that should be done by the implementation. OIDC protocol will return a token to the implementation which should call this method to continue the login flow using OIDC.

DriverSdkProvider.driverSdk.authentication.loginWithOIDCToken(region, token, object : ResultCallback<DriverLoginResult> {
    override fun onResult(result: DriverLoginResult) {
        if (result.success) {
            Log.i(TAG, "user is successfully authentication with Bringg, DriverSdkProvider.driverSdk.data.login will post TRUE")
        } else {
            Log.i(TAG,"user authentication failed, error=${result.error}")
        }
    }
})

Parameters

region

String

NOT NULLABLE

the region on Bringg Platform that you are trying to login to. This value is provided to the implementation on the DriverLoginResult model OpenIdConnectLoginConfig.region

token

String

NOT NULLABLE

authentication token that was retrived from your OIDC implementation

callback

ResultCallback<DriverLoginResult>

NOT NULLABLE

receive DriverLoginResult model with the action result

DriverLoginResult

Model containing the authentication results

Parameters

success

Boolean

NOT NULLABLE

was the user successfuly authenticated with Bringg Platform Cloud Services.

When success=TRUE LiveData driverSdk.data.login will post TRUE value

When success=FALSE DriverLoginResult.Error will be populated with error enum indicating the failure reason

error

DriverLoginResult.Error?

NULLABLE

In case of authentication failure (success = FALSE) this will indicate the reason for the failure.

userMerchantList

Collection<LoginMerchant>

NOT NULLABLE

Only populated when success = FALSE and error = MULTIPLE_MERCHANTS

in case of authentication failure (success = false) with error *MULTIPLE_MERCHANTS* this collection will be populated with the available merchants associated with the login details. Implementation should call Login with email and password to a specific merchant or Login with phone number and verification code to a specific merchant to continue the authentication flow for a specific merchant (represented by the model *LoginMerchant*) from this collection

openIdConnectLoginConfig

OpenIdConnectLoginConfig?

Only populated when success = FALSE and error = LOGIN_WITH_OIDC

NULLABLE

in case of authentication failure (success = false) with error *LOGIN_WITH_OIDC* this model will be populated with the required data for OIDC authentication process. implementation should use OIDC protocol to obtain the required token and use it to call Login using OpenID Connect (OIDC) protocol

DriverLoginResult Errors

    TRANSLATIONS_ERROR,
    MULTIPLE_MERCHANTS

INVALID_RESPONSE

authentication response couldn't be verified by DriverSdk

LOGIN_CANCELED

authentication process was canceled by the user

USER_LOCKED

authentication for these credentials failed too many times, user is locked

NOT_A_DRIVER

provided authentication credentials can't be authenticated as a driver

LOGIN_WITH_OIDC

use openIdConnectLoginConfig and call loginWithOIDCToken(result.openIdConnectLoginConfig!!.region, oidcToken)

NETWORK_ERROR

network connection error

INVALID_CREDENTIALS

provided authentication credentials can't be authenticated

REJECTED_BY_REMOTE

authentication with Bringg Platform Cloud Services failed

INVALID_REGION

provided login region is not valid

TRANSLATIONS_ERROR

the SDK failed to download merchant specific translations

MULTIPLE_MERCHANTS

use userMerchantList to call Login with email and password to a specific merchant or Login with phone number and verification code to a specific merchant to continue the authentication

Phone Verification Code

Request phone login verification code by SMS

Request Bringg Platform to send a verification code to the specified phone number to be later used with Login with phone number and verification code

DriverSdkProvider.driverSdk.authentication.requestPhoneVerification(phone, object : ResultCallback<PhoneVerificationRequestResult> {
    override fun onResult(result: PhoneVerificationRequestResult) {
        if (result.success) {
            Log.i(
                TAG, "phone verification request sent to Bringg." +
                        "SMS verification code will be sent to the provided phone number." +
                        "Use the verification code from the SMS message to call DriverSdkProvider.driverSdk.loginWithPhone(phone, verificationCode, callback)"
            )
        } else {
            Log.i(TAG,"phone verification request failed")
        }
    }
})

Parameters

phone

String

NOT NULLABLE

phone number registered on Bringg Platform

callback

ResultCallback<PhoneVerificationRequestResult>

NOT NULLABLE

receive PhoneVerificationRequestResult model with the action result

PhoneVerificationRequestResult

Model containing the request results

Parameters

success

Boolean

NOT NULLABLE

was the request successfuly sent to Bringg Platform Cloud Services

error

PhoneVerificationRequestResult.Error?

NULLABLE

in case of failure (success = false) this will indicate the reason for the failure.

Reset Password

Request reset password by Email

Request Bringg Platform to send a reset password link to the specified email address

DriverSdkProvider.driverSdk.authentication.requestResetPasswordLink(email, object : ResultCallback<ResetPasswordRequestResult> {
    override fun onResult(result: ResetPasswordRequestResult) {
        if (result.success) {
            Log.i(
                TAG, "reset password request sent to Bringg." +
                        "A link to reset the password will be sent to the provided email address" +
                        "Use the password to call DriverSdkProvider.driverSdk.loginWithEmail(email, password, callback)"
            )
        } else {
            Log.i(TAG,"reset password request failed")
        }
    }
})

Parameters

email

String

NOT NULLABLE

user email

callback

ResultCallback<ResetPasswordRequestResult>

NOT NULLABLE

receive ResetPasswordRequestResult model with the action result

ResetPasswordRequestResult

Model containing the request results

Parameters

success

Boolean

NOT NULLABLE

was the request successfuly sent to Bringg Platform Cloud Services

error

ResetPasswordRequestResult.Error?

NULLABLE

in case of failure (success = false) this will indicate the reason for the failure.

logout

Use to logout a driver.

DriverSdkProvider.driverSdk.authentication.logout()

Updated almost 4 years ago

What’s Next