diff --git a/CHANGES.md b/CHANGES.md index 8c10320816..0bb48c4f8c 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -23,7 +23,7 @@ Test: - Other changes: - - + - Add documentation on LoginWizard and RegistrationWizard (#3303) Changes in Element 1.1.7 (2021-05-12) =================================================== diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/AuthenticationService.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/AuthenticationService.kt index a7f5163774..5e35917243 100644 --- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/AuthenticationService.kt +++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/AuthenticationService.kt @@ -51,11 +51,15 @@ interface AuthenticationService { /** * Return a LoginWizard, to login to the homeserver. The login flow has to be retrieved first. + * + * See [LoginWizard] for more details */ fun getLoginWizard(): LoginWizard /** * Return a RegistrationWizard, to create an matrix account on the homeserver. The login flow has to be retrieved first. + * + * See [RegistrationWizard] for more details. */ fun getRegistrationWizard(): RegistrationWizard diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/login/LoginWizard.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/login/LoginWizard.kt index 9c96cba40c..da6eb0c3ac 100644 --- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/login/LoginWizard.kt +++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/login/LoginWizard.kt @@ -17,34 +17,46 @@ package org.matrix.android.sdk.api.auth.login import org.matrix.android.sdk.api.session.Session -import org.matrix.android.sdk.api.util.Cancelable +/** + * Set of methods to be able to login to an existing account on a homeserver. + * + * More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signin.md + */ interface LoginWizard { - /** - * @param login the login field - * @param password the password field + * Login to the homeserver. + * + * @param login the login field. Can be a user name, or a msisdn (email or phone number) associated to the account + * @param password the password of the account * @param deviceName the initial device name - * @param callback the matrix callback on which you'll receive the result of authentication. - * @return a [Cancelable] + * @return a [Session] if the login is successful */ suspend fun login(login: String, password: String, deviceName: String): Session /** - * Exchange a login token to an access token + * Exchange a login token to an access token. + * + * @param loginToken login token, obtain when login has happen in a WebView, using SSO + * @return a [Session] if the login is successful */ suspend fun loginWithToken(loginToken: String): Session /** - * Reset user password + * Ask the homeserver to reset the user password. The password will not be reset until + * [resetPasswordMailConfirmed] is successfully called. + * + * @param email an email previously associated to the account the user wants the password to be reset. + * @param newPassword the desired new password */ suspend fun resetPassword(email: String, newPassword: String) /** * Confirm the new password, once the user has checked their email + * When this method succeed, tha account password will be effectively modified. */ suspend fun resetPasswordMailConfirmed() } diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/registration/RegistrationWizard.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/registration/RegistrationWizard.kt index f059bf26c4..2fcb501f26 100644 --- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/registration/RegistrationWizard.kt +++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/api/auth/registration/RegistrationWizard.kt @@ -16,32 +16,92 @@ package org.matrix.android.sdk.api.auth.registration +/** + * Set of methods to be able to create an account on a homeserver. + * + * More documentation can be found in the file https://github.com/vector-im/element-android/blob/main/docs/signup.md + */ interface RegistrationWizard { - + /** + * Call this method to get the possible registration flow of the current homeserver. + * It can be useful to ensure that your application implementation supports all the stages + * required to create an account. If it is not the case, you will have to use the web fallback + * to let the user create an account with your application. + * See [org.matrix.android.sdk.api.auth.AuthenticationService.getFallbackUrl] + */ suspend fun getRegistrationFlow(): RegistrationResult + /** + * Can be call to check is the desired userName is available for registration on the current homeserver. + * It may also fails if the desired userName is not correctly formatted or does not follow any restriction on + * the homeserver. Ex: userName with only digits may be rejected. + * @param userName the desired username. Ex: "alice" + */ + suspend fun registrationAvailable(userName: String): RegistrationAvailability + + /** + * This is the first method to call in order to create an account and start the registration process. + * + * @param userName the desired username. Ex: "alice" + * @param password the desired password + * @param initialDeviceDisplayName the device display name + */ suspend fun createAccount(userName: String?, password: String?, initialDeviceDisplayName: String?): RegistrationResult + /** + * Perform the "m.login.recaptcha" stage. + * + * @param response the response from ReCaptcha + */ suspend fun performReCaptcha(response: String): RegistrationResult + /** + * Perform the "m.login.terms" stage. + */ suspend fun acceptTerms(): RegistrationResult + /** + * Perform the "m.login.dummy" stage. + */ suspend fun dummy(): RegistrationResult + /** + * Perform the "m.login.email.identity" or "m.login.msisdn" stage. + * + * @param threePid the threePid to add to the account. If this is an email, the homeserver will send an email + * to validate it. For a msisdn a SMS will be sent. + */ suspend fun addThreePid(threePid: RegisterThreePid): RegistrationResult + /** + * Ask the homeserver to send again the current threePid (email or msisdn). + */ suspend fun sendAgainThreePid(): RegistrationResult + /** + * Send the code received by SMS to validate a msisdn. + * If the code is correct, the registration request will be executed to validate the msisdn. + */ suspend fun handleValidateThreePid(code: String): RegistrationResult + /** + * Useful to poll the homeserver when waiting for the email to be validated by the user. + * Once the email is validated, this method will return successfully. + * @param delayMillis the SDK can wait before sending the request + */ suspend fun checkIfEmailHasBeenValidated(delayMillis: Long): RegistrationResult - suspend fun registrationAvailable(userName: String): RegistrationAvailability - + /** + * This is the current ThreePid, waiting for validation. The SDK will store it in database, so it can be + * restored even if the app has been killed during the registration + */ val currentThreePid: String? - // True when login and password has been sent with success to the homeserver + /** + * True when login and password have been sent with success to the homeserver, i.e. [createAccount] has been + * called successfully. + */ val isRegistrationStarted: Boolean }