Authentication

Authentication (Auth) component is responsible for all of the commands that are related to authentication, session acquisition and management.

Copilot.cx user registration has two modes:

• Email and password user
• Anonymous user

💡 GDPR consent should be provided in any case, for every user type, unless the application is not GDPR required (if so, please refer the Copilot.cx SDK Configuration for Android and iOS.

Email and password registration

Registration requires providing a valid email address and a password. Once the user is registered, it’s possible to log in using the registration credentials they provided.

💡Email field validation - Email field should be validated with regular expression on the client side in order to help users detect input errors when they register, and aim for valid emails that you can later use for User Engagement.

Result error - SignupError

Below are the possible errors you can receive in case of failure:

• InvalidApplicationId - Application ID is not recognized. Please refer the Copilot.cx SDK configuration for Android and iOS and SDK configuration sections.
• InvalidEmail - The provided email is not a legal email.
• InvalidParameters - One of or more of the command's parameters are missing or invalid.
• UserAlreadyExists - The user with the provided email already exists.
• PasswordPolicyViolation - The provided password violates the password policy. Password should be validated locally before executing the signup command. For more details, please refer the fetchPasswordPolicy section.
• ConnectivityError - A communication failure occurred while executing this command.
• GeneralError - A unexpected general failure occurred while executing the command. Please refer the debug message for more details.

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .auth
        .signup()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", value: true)
        .with(email: "ck@dailyplanet.com", password: "Superman1234", firstname: "Clark", lastname: "Kent")
        .build()
        .execute { (response) in
            switch response {
            case .success:
                break
                
            case .failure(error: let registerError):
                switch(registerError) {
                case .connectivityError(let debugMessage):
                    break
                case .generalError(let debugMessage):
                    break
                case .userAlreadyExists(let debugMessage):
                    break
                case .passwordPolicyViolation(let debugMessage):
                    break
                case .invalidApplicationId(let debugMessage):
                    break
                case .invalidEmail(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .signup()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", true)
        .withEmailPassword("ck@dailyplanet.com","Superman1234", "Clark", "Kent")
        .build()
        .execute(new RequestListener<Void, SignupError>() {
            @Override
            public void success(Void response) {
                // User signed up with success
            }
            @Override
            public void error(SignupError error) {
                switch (error) {
                    case InvalidApplicationId:
                        break;
                    case InvalidEmail:
                        break;
                    case InvalidParameters:
                        break;
                    case UserAlreadyExists:
                        break;
                    case PasswordPolicyViolation:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .signup()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", true)
        .withEmailPassword("ck@dailyplanet.com", "Superman1234", "Clark", "Kent")
        .build()
        .execute(object : RequestListener<Void?, SignupError> {
            override fun success(response: Void?) {
                // User signed up with success
            }

            override fun error(error: SignupError?) {
                when (error) {
                    SignupError.InvalidApplicationId -> {}
                    SignupError.InvalidEmail -> {}
                    SignupError.InvalidParameters -> {}
                    SignupError.UserAlreadyExists -> {}
                    SignupError.PasswordPolicyViolation -> {}
                    SignupError.ConnectivityError -> {}
                    SignupError.GeneralError -> {}
                }
            }
        })

Anonymous Registration

Registration can be done without requiring the user to provide credentials. A unique anonymous user should then be created for the user over Copilot.

💡 You’ll be able to block certain features for anonymous users and can expose contextual signup when elevation to registered user is required (please refer the Elevate anonymous user section). In order to to distinguish anonymous users, you can refer a dedicated property name CredentialsType under the UserMe object (please refer the Fetch user details section).

Result error - SignupAnonymouslyError

Below are the possible errors you can receive in case of failure:

• InvalidApplicationId - Application ID is not recognized. Please refer the Copilot.cx SDK configuration for Android and iOS and SDK configuration sections.
• InvalidParameters - One of or more of the command's parameters are missing or invalid. Please check the provided email, password, firstName, lastName.
• ConnectivityError - A communication failure occurred while executing this command.
• GeneralError - A unexpected general failure occurred while executing the command. Please refer the debug message for more details.

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .auth
        .signup()
        .withNoGDPRConsentRequired
        .anonymously
        .build()
        .execute { (response) in
            switch response {
            case .success:
                break
                
            case .failure(error: let signupError):
                switch(signupError) {
                case .invalidApplicationId(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .signup()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", true)
        .anonymously()
        .build()
        .execute(new RequestListener<Void, SignupAnonymouslyError>() {
            @Override
            public void success(Void response) {
            }

            @Override
            public void error(SignupAnonymouslyError error) {
                switch (error) {
                    case InvalidApplicationId:
                        break;
                    case InvalidParameters:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .signup()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", true)
        .anonymously()
        .build()
        .execute(object : RequestListener<Void?, SignupAnonymouslyError> {
            override fun success(response: Void?) {}
            override fun error(error: SignupAnonymouslyError) {
                when (error) {
                    SignupAnonymouslyError.InvalidApplicationId -> {}
                    SignupAnonymouslyError.InvalidParameters -> {}
                    SignupAnonymouslyError.ConnectivityError -> {}
                    SignupAnonymouslyError.GeneralError -> {}
                }
            }
        })

💡 After successfully registration (or login) user will be able to login the system without specifying the login credentials. In order to use this capability please refer the Silent login section.

Login with email and password

This command enables registered user to login providing email and password.

Result error - LoginError

Below are the possible errors you can receive in case of failure:

• Unauthorized - Login credentials are wrong or not existing.
• InvalidParameters - One of or more of the command's parameters are missing or invalid. Please check the provided email / password fields.
• MarkedForDeletion - User has requested to delete his account using the logout().markForDeletion command, the user is no longer active.
• ConnectivityError - A communication failure occurred while executing this command.
• GeneralError - A unexpected general failure occurred while executing the command. Please refer the debug message for more details.
• AccountSuspended - Several consecutive failed attempts have been made.

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .auth
        .login()
        .with(email: "ck@dailyplanet.com", password: "Superman1234")
        .build()
        .execute { (response) in
            switch response {
            case .success:
                break
                
            case .failure(error: let loginError):
                switch(loginError) {
                case .invalidParameters(let debugMessage):
                    break
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .markedForDeletion(let debugMessage):
                    break
                case .unauthorized(let debugMessage):
                    break
                case .accountSuspended:
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .login()
        .withEmailPassword("ck@dailyplanet.com","Superman1234")
        .build()
        .execute(new RequestListener<Void, LoginError>() {
            @Override
            public void success(Void response) {
                // Logged in successfully
            }
            @Override
            public void error(LoginError error) {
                switch (error) {
                    case Unauthorized:
                        break;
                    case InvalidParameters:
                        break;
                    case MarkedForDeletion:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                    case AccountSuspended:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .login()
        .withEmailPassword("ck@dailyplanet.com", "Superman1234")
        .build()
        .execute(object : RequestListener<Void?, LoginError> {
            override fun success(response: Void?) {
                // Logged in successfully
            }

            override fun error(error: LoginError) {
                when (error) {
                    LoginError.Unauthorized -> {}
                    LoginError.InvalidParameters -> {}
                    LoginError.MarkedForDeletion -> {}
                    LoginError.ConnectivityError -> {}
                    LoginError.GeneralError -> {}
                    LoginError.AccountSuspended -> {}
                }
            }
        })     

Silent login

Perform silent login

Once the user is logged in, a login session can be recovered without asking the user to provide the login credentials using the silent login command. Silent login is available for both anonymous and registered with email and password users.

Result error - LoginSilentlyError

Below are the possible errors you can receive in case of failure:

• RequiresRelogin - Session expired and cannot be regained, please relogin.
• ConnectivityError - A communication failure occurred while executing this command.
• GeneralError - A unexpected general failure occurred while executing the command. Please refer the debug message for more details.

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .auth
        .login()
        .silently
        .build()
        .execute { (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let silentLoginError):
                switch(silentLoginError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .login()
        .silently()
        .build()
        .execute(new RequestListener<Void, LoginSilentlyError>() {
            @Override
            public void success(Void response) {
                // Silent login performed with success
            }
            @Override
            public void error(LoginSilentlyError error) {
                // Failed to silently log in, handle the error
                switch (error) {
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .login()
        .silently()
        .build()
        .execute(object : RequestListener<Void?, LoginSilentlyError?> {
            override fun success(response: Void?) {
                // Silent login performed with success
            }

            override fun error(error: LoginSilentlyError?) {
                // Failed to silently log in, handle the error
                when (error) {
                    LoginSilentlyError.RequiresRelogin -> {}
                    LoginSilentlyError.ConnectivityError -> {}
                    LoginSilentlyError.GeneralError -> {}
                }
            }
        })

Can login silently

It is well recommended to call the canLoginSilently which returns boolean value indicating that a session can be recovered before calling the silentLogin command or actually doing the navigation to the relevant startup screen (Signup/Login).

iOS

Android (Java)

Android (Kotlin)

Copilot.instance.manage.sphere.defaultAuthProvider.canLoginSilently()

Copilot.getInstance().Manage.Sphere.getAuthTokenProvider().canLoginSilently();

Copilot.getInstance().Manage.Sphere.authTokenProvider.canLoginSilently()

Logout

Logout can be used to end the user’s current session.

💡 In case your application is GDPR compliant, and a user has asked to delete their account permanently , part of the process is deleting their account over Copilot. In order to do so Log the user out, and mark them for deletion on Copilot. In order to do so, chain the logout() call the .markForDeletionOnServer() command. Important note : Deletion is irrevocable, and should be used with caution.

Result error - LogoutError

Below the possible errors you could receive in case of failure:

• ConnectivityError - A communication failure occurred while executing this command.
• GeneralError - A unexpected general failure occurred while executing the command. Please refer the debug message for more details.

Result error - LogoutError

In case a deletion of the user was requested as part of the logout. Below are the possible errors you could receive in case of failure:

• RequiresRelogin - Session expired and cannot be regained, please relogin.
• ConnectivityError - A communication failure occurred while executing this command.
• GeneralError - A unexpected general failure occurred while executing the command. Please refer the debug message for more details.

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .auth
        .logout()
        .build()
        .execute { (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let logoutError):
                switch(logoutError) {
                case .internalError(_):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .logout()
        .build()
        .execute(new RequestListener<Void, LogoutError>() {
            @Override
            public void success(Void response) {
                // User logged out with success
            }
            @Override
            public void error(LogoutError error) {
                switch (error) {
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .Auth
        .logout()
        .build()
        .execute(object : RequestListener<Void?, LogoutError?> {
            override fun success(response: Void?) {
                // User logged out with success
            }

            override fun error(error: LogoutError?) {
                when (error) {
                    LogoutError.ConnectivityError -> {}
                    LogoutError.GeneralError -> {}
                }
            }
        })