User

User component is responsible for all of the commands that are related to connected User data management.

Fetch user details

Getting full user's details can be done by calling the fetch me command.

Result model

Result of type UserMe contains:

• User

  • ID- User’s ID.
  • Email - User’s supplied email address for identification.
  • UserInfo - Contains the following properties (all of those properties can be modified - please refer the update user section).
    • FirstName - User’s first name.
    • LastName - User’s last name.
  • CustomSettings - Custom settings stored specifically for this user. Please refer the code example for accessing custom properties.

  Please note: On Android, non primitive objects should implement the Serializable interface.

• AccountStatus - Contains the following properties:

  • TermsOfUseApproved - Boolean value indicating whether the user approved the “terms of use”.
  • CredentialsType - User registration type (email/anonymous). For more details please refer the email registration and anonymous registration sections.
  • EmailVerificationStatus - Property indicating the current status of user's email verification in case the application configured to send verification email upon registration. Statuses may be:
    • Unset - No verification status is known for the user or the application is not configured to send verification emails.
    • Pending - Verification email is being sent.
    • Verified - User has verified his email.
  • ConsentStatus - Get consent for specific key - custom consent (GDPR). Accessing this property will be done using the following method accountStatus.getConsentForKey(String key) on Android and accountStatus.consent(for key: String) on iOS
  • CopilotUserAnalysisConsent - The ConsentStatus for Copilot.cx user analysis consent.

Result error

Below are the possible errors you can receive in case of FetchMeError type 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .fetchMe()
        .build()
        .execute { (response) in
            switch response {
            case .success(let userMe):
                break
                
            case .failure(error: let fetchMeError):
                switch(fetchMeError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .fetchMe()
        .build()
        .execute(new RequestListener<UserMeModel, FetchMeError>() {
            @Override
            public void success(UserMeModel userMeModel) {
                // That's how you can retrieve custom user settings. You can find below examples for primitives, custom objects and custom objects collection.
                if (userMeModel != null) {
                    User user = userMeModel.getUser();
                    if (user != null) {
                        Boolean myBooleanKey = (Boolean) user.getCustomValueForKey("my_boolean_property_key", Boolean.class);
                        String myStringKey = (String) user.getCustomValueForKey("my_string_property_key", String.class);
                        MyCustomObject myCustomObject = (MyCustomObject) user.getCustomValueForKey("my_custom_object_key", MyCustomObject.class);
                        ArrayList<MyCustomObject> myCustomObjectsCollection = (ArrayList<MyCustomObject>) user.getCustomListValueForKey("my_custom_collection_key", MyCustomObject[].class);
                    }
                }
            }

            @Override
            public void error(FetchMeError error) {
                switch (error) {
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .fetchMe()
        .build()
        .execute(object : RequestListener<UserMeModel?, FetchMeError?> {
            override fun success(userMeModel: UserMeModel?) {
                // That's how you can retrieve custom user settings. You can find below examples for primitives,custom objects and custom objects collection.
                if (userMeModel != null) {
                    val user = userMeModel.user
                    if (user != null) {
                        val myBooleanKey = user.getCustomValueForKey("my_boolean_property_key", Boolean::classjava) as Boolean
                        val myStringKey = user.getCustomValueForKey("my_string_property_key", String::classjava) as String
                        val myCustomObject: MyCustomObject =
                            user.getCustomValueForKey("my_custom_object_key", MyCustomObject::class.java) asMyCustomObject
                        val myCustomObjectsCollection: ArrayList<MyCustomObject> = user.getCustomListValueForKey(
                            "my_custom_collection_key",
                            Array<MyCustomObject>::class.java
                        ) as ArrayList<MyCustomObject>
                    }
                }
            }

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

Update user

Updating the user object can be done in the following use cases:

• Update user basic details : First name / Last name / custom settings.
• Update user’s agreement status on the “terms of use” document.
• Update user’s GDPR consent status.
• Update user's email - change email.
• Update user's password - change password.

Update user details

These are the user details fields for which can be updated:

• FirstName
• LastName
• CustomSettings - Custom settings can be used as a storage of simple key-value pairs. Those values can be retrieved by the fetch user details command. For example : end-user preferences for their mobile application or account, like using celsius or fahrenheit for temperature, metric or imperial for distance etc. Custom settings supports the following data types:
  • Primitive data types: Boolean, String, Integer, Float, Double.
  • Array of primitive or custom objects.
  • Dictionary of primitive or custom objects.

💡 Setting a custom setting value can be chained - meaning using one command call you can set multiple custom setting values. Please refer the example below.

💡 In order to remove custom setting use removeCustomValue(String) - Android or removeValue(forKey: String) - iOS.

Result model

Result of type UserMe contains:

• User
  • ID- User’s ID.
  • Email - User’s supplied email address for identification.
  • UserInfo - Contains the following properties (all of those properties can be modified - please refer the update user section.
    • FirstName - User’s first name.
    • LastName - User’s last name.
  • CustomSettings - Custom settings stored specifically for this user. Accessing those custom properties will be done using
• AccountStatus - Contains the following properties:
  • TermsOfUseApproved - Boolean value indicating whether the user approved the “terms of use”.
  • CredentialsType - User registration type (email / anonymous). For more details please refer the email registration and anonymous registration sections.
  • ConsentStatus - Get consent for specific key - custom consent (GDPR). Accessing this property will be done using the following method accountStatus.getConsentForKey(String key) on Android and accountStatus.consent(for key: String) on iOS
  • CopilotUserAnalysisConsent - The ConsentStatus for Copilot.cx user analysis consent.

Result error

Below are the possible errors you can receive in case of UpdateUserError (iOS) \ UpdateUserDetailsError(Android) type failure:

• InvalidParameters - One or more of provided parameters is missing or invalid.
• 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .updateMe()
        .with(firstname: "Clark")
        .with(lastname: "Kent")
        .with(customValue: true, forKey: "sensibleToKryptonite")
        .with(customValue: "Kalel", forKey: "birthName")
        .with(customValue: ["Martha Kent", "Jonathan Kent"], forKey: "adoptiveParents")
        .with(customValue: ["planet": "Krypton"], forKey: "origin")
        .build()
        .execute { (response) in
            switch response {
            case .success(let userMe):
                break
                
            case .failure(error: let updateUserDetailsError):
                switch(updateUserDetailsError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                }
            }
    }

ArrayList<String> parents = new ArrayList<>();
parents.add("Martha Kent");
parents.add("Jonathan Kent");

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .withFirstName("Clark")
        .withLastName("Kent")
        .withCustomValue("sensibleToKryptonite", true)
        .withCustomValue("birthName", "Kalel")
        .withCustomValue("adoptiveParents", parents)
        .removeCustomValue("KeyToRemove")
        .build()
        .execute(new RequestListener<UserMeModel, UpdateUserError>() {
            @Override
            public void success(UserMeModel response) {
                // User has been updated with success
            }
            @Override
            public void error(UpdateUserError error) {
                switch (error){
                    case InvalidParameters:
                        break;
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

val parents = listOf(
    "Martha Kent",
    "Jonathan Kent"
)

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .withFirstName("Clark")
        .withLastName("Kent")
        .withCustomValue("sensibleToKryptonite", true)
        .withCustomValue("birthName", "Kalel")
        .withCustomValue("adoptiveParents", parents)
        .removeCustomValue("KeyToRemove")
        .build()
        .execute(object : RequestListener<UserMeModel?, UpdateUserError?> {
            override fun success(response: UserMeModel?) {
                // User has been updated with success
            }
            override fun error(error: UpdateUserError?) {
                when (error) {
                    UpdateUserError.InvalidParameters -> {}
                    UpdateUserError.RequiresRelogin -> {}
                    UpdateUserError.ConnectivityError -> {}
                    UpdateUserError.GeneralError -> {}
                }
            }
        })

Approve terms of use

Managing terms and conditions approval over Copilot.cx is done by passing the latest terms version, and executing the approveTermsOfUse command. This allows you to compare the user’s last approved version with the required version as set by Copilot.cx Admin in the web user interface.

💡 You can fetch the terms of use document URL and its version using the fetch of the current terms of use from using the Application FetchConfiguration command.

Result model

Void

Result error

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

• InvalidParameters - One or more of provided parameters is missing or invalid.
• 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .updateMe()
        .approveTermsOfUse(forVersion: "17")
        .build()
        .execute { (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let updateMeError):
                switch(updateMeError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .approveTermsOfUse("17")
        .build()
        .execute(new RequestListener<Void, ApproveTermsOfUseError>() {
            @Override
            public void success(Void response) {
                // Updated user's terms of use approval with success
            }
            @Override
            public void error(ApproveTermsOfUseError error) {
                switch (error){
                    case InvalidParameters:
                        break;
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .approveTermsOfUse("17")
        .build()
        .execute(object : RequestListener<Void?, ApproveTermsOfUseError?> {
            override fun success(response: Void?) {
                // Updated user's terms of use approval with success
            }
            override fun error(error: ApproveTermsOfUseError?) {
                when (error) {
                    ApproveTermsOfUseError.InvalidParameters -> {}
                    ApproveTermsOfUseError.RequiresRelogin -> {}
                    ApproveTermsOfUseError.ConnectivityError -> {}
                    ApproveTermsOfUseError.GeneralError -> {}
                }
            }
        })

Update user's consent

Using Copilot.cx SDK in a GDPR compliant application means you should ask the user for explicit consent for each item of data collected.

• Copilot.cx SDK requires a default consent for collecting analytics.
• To that you should add the relevant custom consent requests that apply to your application and product.

💡 Users may revoke their consent to each of the items they have consented to in the past. You should expose this possibility in your application settings, and in case a consent status changes, call the consent endpoint again with the new status.

Result model

Void

Result error

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

• InvalidParameters - One or more of provided parameters is missing or invalid.
• 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .updateMe()
        .allowCopilotUserAnalysis(true)
        .withCustomConsent("analyseUseOfXRayVision", value: true)
        .build()
        .execute { (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let updateConsentError):
                switch(updateConsentError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", true)
        .build()
        .execute(new RequestListener<Void, UpdateUserConsentError>() {
            @Override
            public void success(Void response) {
                // Updated user's consents with success
            }
            @Override
            public void error(UpdateUserConsentError error) {
                switch (error){
                    case InvalidParameters:
                        break;
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .withCopilotAnalysisConsent(true)
        .withCustomConsent("analyseUseOfXRayVision", true)
        .build()
        .execute(object : RequestListener<Void?, UpdateUserConsentError?> {
            override fun success(response: Void?) {
                // Updated user's consents with success
            }
            override fun error(error: UpdateUserConsentError?) {
                when (error) {
                    UpdateUserConsentError.InvalidParameters -> {}
                    UpdateUserConsentError.RequiresRelogin -> {}
                    UpdateUserConsentError.ConnectivityError -> {}
                    UpdateUserConsentError.GeneralError -> {}
                }
            }
        })

Change email

Users might want to change their email of an existing user. In order to do so, run the withEmail command with the new email address.

💡 Important: When changing the user's email address, please note the following:

• The new email address will not be immediately reflected in the me response if your application requires the user to verify their email. The user must verify their email address before it is updated in the system.
• Until the user verifies their email, they will not be able to log in using the new email address. They will still be able to log in with their old email address.
• After verifying the new email, the old login will no longer be valid, and only the new email will be used for login.
• The request to change the email may expire if the user does not verify the new email within a specified timeframe.

Result model

Result of type UserMe contains:

• User
  • ID- User’s ID.
  • Email - User’s supplied email address for identification.
  • UserInfo - Contains the following properties (all of those properties can be modified - please refer the update user section.
    • FirstName - User’s first name.
    • LastName - User’s last name.
  • CustomSettings - Custom settings stored specifically for this user. Accessing those custom properties will be done using
• AccountStatus - Contains the following properties:
  • TermsOfUseApproved - Boolean value indicating whether the user approved the “terms of use”.
  • CredentialsType - User registration type (email / anonymous). For more details please refer the email registration and anonymous registration sections.
  • ConsentStatus - Get consent for specific key - custom consent (GDPR). Accessing this property will be done using the following method accountStatus.getConsentForKey(String key) on Android and accountStatus.consent(for key: String) on iOS
  • CopilotUserAnalysisConsent - The ConsentStatus for Copilot.cx user analysis consent.

Result Error

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

• RequiresRelogin - Session expired and cannot be regained, please relogin.
• InvalidEmail - The provided email is not a legal email.
• EmailAlreadyExists - A user with the provided email already exists.
• 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.
• emailCannotBeChangedForAnonymousUser - Tried changing email for anonymous user

Code sample

iOS

Android (Java)

Android (kotlin)

Copilot.instance
                    .manage
                    .sphere
                    .user
                    .updateMe()
                    .withEmail("ck@dailyplanet.com")
                    .build()
                    .execute { response in
                switch response {
                    case .success(let userMe):
                        // A request to change user's email was successfully made.
                    break
                case .failure(error: let error):
                    switch error {
                    case .invalidEmail(debugMessage: let error):
                        break
                    case .emailAlreadyExists(debugMessage: let error):
                        break
                    case .requiresRelogin(debugMessage: let error):
                        break
                    case .connectivityError(debugMessage: let error):
                        break
                    case .missingField(debugMessage: let error):
                        break
                    case .generalError(debugMessage: let debugMessage):
                        break
                    }
                    break
                }
            }

Copilot.getInstance()
                .Manage
                .Sphere
                .User
                .updateMe()
                .withEmail("ck@dailyplanet.com")
                .build().execute(new RequestListener<UserMeModel, ChangeEmailError>() {
                    @Override
                    public void success(UserMeModel response) {
                        // A request to change user's email was successfully made.
                    }

                    @Override
                    public void error(ChangeEmailError error) {
                        switch (error) {
                            case RequiresRelogin:
                                break;
                            case ConnectivityError:
                                break;
                            case EmailAlreadyExists:
                                break;
                            case InvalidEmail:
                                break;
                            case MissingField:
                                break;
                            case GeneralError:
                                break;
                        }
                    }
                });

Copilot.getInstance().Manage.Sphere.User
            .updateMe()
            .withEmail("ck@dailyplanet.com")
            .build().execute(object : RequestListener<UserMeModel?, ChangeEmailError?> {


                override fun success(response: UserMeModel?) {
                    // A request to change user's email was successfully made.
                }

                override fun error(error: ChangeEmailError?) {
                    when (error) {
                        ChangeEmailError.RequiresRelogin -> {}
                        ChangeEmailError.ConnectivityError -> {}
                        ChangeEmailError.EmailAlreadyExists -> {}
                        ChangeEmailError.InvalidEmail -> {}
                        ChangeEmailError.MissingField -> {}
                        ChangeEmailError.GeneralError -> {}
                    }
                }
            })

Change password

Users might want to change their login password when they are logged in to the application. In order to do so use the change password command providing the oldPassword and the newPassword.

💡 The new password must comply with the password policy. For more details, please refer the fetchPasswordPolicy section.

Result model

Void

Result error

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

• CannotChangePasswordToAnonymousUser - Currently logged in user is an anonymous user without a password.
• InvalidCredentials - The provided old password is incorrect.
• PasswordPolicyViolation - The provided new password violates the password policy. Password should be validated locally before executing the change password command.
• InvalidParameters - One or more of provided parameters is missing or invalid.
• 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .updateMe()
        .withNewPassword("ManOfSteel1234", verifyWithOldPassword: "Superman1234")
        .build()
        .execute{ (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let updatePasswordError):
                switch(updatePasswordError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                case .invalidCredentials(let debugMessage):
                    break
                case .passwordPolicyViolation(let debugMessage):
                    break
                case .cannotChangePasswordToAnonymousUser(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .withNewPassword("TheManOfSteel1234", "Superman1234")
        .build()
        .execute(new RequestListener<Void, ChangePasswordError>() {
            @Override
            public void success(Void response) {
                // Password was changed
            }

            @Override
            public void error(ChangePasswordError error) {
                switch (error){
                    case CannotChangePasswordToAnonymousUser:
                        break;
                    case InvalidCredentials:
                        break;
                    case PasswordPolicyViolation:
                        break;
                    case InvalidParameters:
                        break;
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });
}

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .updateMe()
        .withNewPassword("TheManOfSteel1234", "Superman1234")
        .build()
        .execute(object: RequestListener<Void, ChangePasswordError> {
            override fun success(response: Void?) {
                // Password was changed
            }
            override fun error(error: ChangePasswordError?) {
                when (error) {
                    ChangePasswordError.CannotChangePasswordToAnonymousUser -> {}
                    ChangePasswordError.InvalidCredentials -> {}
                    ChangePasswordError.PasswordPolicyViolation -> {}
                    ChangePasswordError.InvalidParameters -> {}
                    ChangePasswordError.RequiresRelogin -> {}
                    ChangePasswordError.ConnectivityError -> {}
                    ChangePasswordError.GeneralError -> {}
                }
            }
        })
}

Delete User

Deleting the user can be done by calling the deleteMe command

Result model

Void

Result error

Below are the possible errors you can receive in case of DeleteUserError type 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .deleteMe()
        .build()
        .execute { response in
            switch response {
            case .success():
                // User has been deleted successfully
                break

            case .failure(error: let error):
                switch error {
                case .requiresRelogin:
                    break
                case .connectivityError:
                    break
                case .generalError:
                    break
                }
            }
        }

Copilot.getInstance()
        .Manage
        .Sphere
        .User.deleteMe()
        .build()
        .execute(new RequestListener<Void, DeleteUserError>() {
            @Override
            public void success(Void response) {
                // User has been deleted successfully
            }

            @Override
            public void error(DeleteUserError error) {
                switch (error) {
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .deleteMe()
        .build()
        .execute(object : RequestListener<Void?, DeleteUserError?> {
            override fun success(response: Void?) {
                // User has been deleted successfully
            }

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

Send verification email

You may require users to verify their email per your business and application needs or requirements: you can enable/disable features for users who verified/unverified their emails. In case your Copilot.cx Cloud is configured to send verification emails, the verification email will be sent upon registration of the user using email and password. This command will re-send the email verification link to user's inbox. In order to fetch user's verification status please refer the UserMe.AccountStatus.EmailVerificationStatus property of currently logged in user.

Code Sample - email verification status property

iOS

Android (Java)

Android (Kotlin)

    userMe.accountStatus.emailVerificationStatus

    userMeModel.getAccountStatus().getEmailVerificationStatus();

    userMeModel.getAccountStatus().getEmailVerificationStatus()

💡 Consecutive invocations of the Send verification email command are limited in time. Please refer the RetryRequired error for more details.

💡 This command requires specific configuration on Copilot.cx Cloud. Please contact Customer Success for more details.

Result model

Void

Result error

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

• RetryRequired - Command cannot be executed. Command can be retried in RetryRequired.getRetryAfterInSeconds() seconds.
• UserAlreadyVerified - User already verified his mail.
• 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .sendVerificationEmail()
        .build()
        .execute{ (response) in
            switch response{
            case .success():
                break
                
            case .failure(error: let sendVerificationEmailError):
                switch(sendVerificationEmailError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                case .retryRequired(let retryInSeconds, let debugMessage):
                    break
                case .userAlreadyVerified(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .sendVerificationEmail()
        .build()
        .execute(new RequestListener<Void, SendVerificationEmailError>() {
            @Override
            public void success(Void response) { }

            @Override
            public void error(SendVerificationEmailError error) {
                switch (error){
                    case RetryRequired:
                        break;
                    case UserAlreadyVerified:
                        break;
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .sendVerificationEmail()
        .build()
        .execute(object : RequestListener<Void?, SendVerificationEmailError?> {
            override fun success(response: Void?) {}
            override fun error(error: SendVerificationEmailError?) {
                when (error) {
                    SendVerificationEmailError.RetryRequired -> {}
                    SendVerificationEmailError.UserAlreadyVerified -> {}
                    SendVerificationEmailError.RequiresRelogin -> {}
                    SendVerificationEmailError.ConnectivityError -> {}
                    SendVerificationEmailError.GeneralError -> {}
                }
            }
        })

Reset password

Users might want to reset their login password when they forget it and wish to login to the application. Reset password is handled by Copilot.cx sending the user a reset link (to the email provided in registration) and changing the password through a designated secure web page after authenticating the user.

💡 In case email verification is enabled for your application, a user with unverified email won't be able to reset thier password.

Result model

Void

💡 For security reasons, if the email requested does not exist, the system will still return 'success' without sending out a Reset Password email.

Result error

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

• InvalidParameters - Email field is missing or invalid.
• EmailIsNotVerified - Provided email is not verified. Please refer the Send verification email 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .resetPassword(for: "ck@dailyplanet.com")
        .build()
        .execute { (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let resetPasswordError):
                switch(resetPasswordError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                case .emailIsNotVerified(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .resetPassword("ck@dailyplanet.com")
        .build()
        .execute(new RequestListener<Void, ResetPasswordError>() {
            @Override
            public void success(Void response) {
                // A request to change user's password was successfully made.
            }
            @Override
            public void error(ResetPasswordError error) {
                switch (error) {
                    case EmailIsNotVerified:
                        break;
                    case InvalidParameters:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .resetPassword("ck@dailyplanet.com")
        .build()
        .execute(object : RequestListener<Void?, ResetPasswordError?> {
            override fun success(response: Void?) {
                // A request to change user's password was successfully made.
            }
            override fun error(error: ResetPasswordError?) {
                when (error) {
                    ResetPasswordError.EmailIsNotVerified -> {}
                    ResetPasswordError.InvalidParameters -> {}
                    ResetPasswordError.ConnectivityError -> {}
                    ResetPasswordError.GeneralError -> {}
                }
            }
        })

Elevate anonymous user

Users who register anonymously could be elevated to email authenticated users at any stage by providing additional details.

💡 An Email registration means that the user has access to their custom settings and their information from any device once authenticated.

💡 Collecting users’ emails allows them to receive user engagement emails over Copilot.

Since anonymous users already exist in Copilot.cx user management, elevation means adding their information including account email and first and last name.

Result model

Void

Result error

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

• CannotElevateANonAnonymousUser - This user is not anonymous anymore and cannot be elevated.
• InvalidEmail - The provided email is not a legal email
• 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.
• UserAlreadyExists - The user with the provided email already exists.
• InvalidParameters - One or more of provided parameters is missing or invalid.
• 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.

Code sample

iOS

Android (Java)

Android (Kotlin)

Copilot.instance
        .manage
        .sphere
        .user
        .elevate()
        .with(email: "ck@dailyplanet.com", password: "Superman1234", firstname: "Clark", lastname: "Kent")
        .build()
        .execute { (response) in
            switch response {
            case .success():
                break
                
            case .failure(error: let elevateError):
                switch(elevateError) {
                case .generalError(let debugMessage):
                    break
                case .connectivityError(let debugMessage):
                    break
                case .invalidParameters(let debugMessage):
                    break
                case .requiresRelogin(let debugMessage):
                    break
                case .cannotElevateANonAnonymousUser(let debugMessage):
                    break
                case .userAlreadyExists(let debugMessage):
                    break
                case .passwordPolicyViolation(let debugMessage):
                    break
                case .invalidEmail(let debugMessage):
                    break
                }
            }
    }

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .elevateAnonymousUser()
        .withEmailPassword("ck@dailyplanet.com","Superman1234","Clark","Kent")
        .build()
        .execute(new RequestListener<Void, ElevateAnonymousUserError>() {
            @Override
            public void success(Void response) {
                // User was elevated successfully
            }
            @Override
            public void error(ElevateAnonymousUserError error) {
                switch (error) {
                    case CannotElevateANonAnonymousUser:
                        break;
                    case InvalidEmail:
                        break;
                    case PasswordPolicyViolation:
                        break;
                    case UserAlreadyExists:
                        break;
                    case InvalidParameters:
                        break;
                    case RequiresRelogin:
                        break;
                    case ConnectivityError:
                        break;
                    case GeneralError:
                        break;
                }
            }
        });
        

Copilot.getInstance()
        .Manage
        .Sphere
        .User
        .elevateAnonymousUser()
        .withEmailPassword("ck@dailyplanet.com", "Superman1234", "Clark", "Kent")
        .build()
        .execute(object : RequestListener<Void?, ElevateAnonymousUserError?> {
            override fun success(response: Void?) {
                // User was elevated successfully
            }
            override fun error(error: ElevateAnonymousUserError?) {
                when (error) {
                    ElevateAnonymousUserError.CannotElevateANonAnonymousUser -> {}
                    ElevateAnonymousUserError.InvalidEmail -> {}
                    ElevateAnonymousUserError.PasswordPolicyViolation -> {}
                    ElevateAnonymousUserError.UserAlreadyExists -> {}
                    ElevateAnonymousUserError.InvalidParameters -> {}
                    ElevateAnonymousUserError.RequiresRelogin -> {}
                    ElevateAnonymousUserError.ConnectivityError -> {}
                    ElevateAnonymousUserError.GeneralError -> {}
                }
            }
        })