-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Include error handling part of the Asgardeo Android SDK to the …
…documentation.
- Loading branch information
Achintha Isuru
committed
Aug 16, 2024
1 parent
9023aec
commit 30b86cc
Showing
7 changed files
with
187 additions
and
10 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,33 @@ | ||
| <!-- | ||
| * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com). | ||
| * | ||
| * WSO2 LLC. licenses this file to you under the Apache License, | ||
| * Version 2.0 (the "License"); you may not use this file except | ||
| * in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, | ||
| * software distributed under the License is distributed on an | ||
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| * KIND, either express or implied. See the License for the | ||
| * specific language governing permissions and limitations | ||
| * under the License. | ||
| --> | ||
|
|
||
| # Best Practices when using the Asgardeo Android SDK | ||
|
|
||
| This guide provides best practices to follow when using the Asgardeo Android SDK. Following these best practices will help you to integrate the SDK seamlessly into your Android application. | ||
|
|
||
| ## Use the latest version of the SDK | ||
|
|
||
| Always use the latest version of the Asgardeo Android SDK to ensure that you have access to the latest features and bug fixes. You can find the latest version of the SDK in the [Maven Repository](https://central.sonatype.com/artifact/io.asgardeo/asgardeo-android). | ||
|
|
||
| ## MVVM architecture | ||
|
|
||
| When integrating the Asgardeo Android SDK into your application, it is recommended to use the [Model-View-ViewModel (MVVM) architecture](https://www.geeksforgeeks.org/mvvm-model-view-viewmodel-architecture-pattern-in-android/). This architecture helps to separate the UI logic from the business logic and provides a clean and maintainable codebase. | ||
|
|
||
| ## Use `Dispatchers.IO` | ||
|
|
||
| Suspended functions in the SDK are designed to be optimized for `Dispatchers.IO` context. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,131 @@ | ||
| <!-- | ||
| * Copyright (c) 2024, WSO2 LLC. (https://www.wso2.com). | ||
| * | ||
| * WSO2 LLC. licenses this file to you under the Apache License, | ||
| * Version 2.0 (the "License"); you may not use this file except | ||
| * in compliance with the License. | ||
| * You may obtain a copy of the License at | ||
| * | ||
| * http://www.apache.org/licenses/LICENSE-2.0 | ||
| * | ||
| * Unless required by applicable law or agreed to in writing, | ||
| * software distributed under the License is distributed on an | ||
| * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | ||
| * KIND, either express or implied. See the License for the | ||
| * specific language governing permissions and limitations | ||
| * under the License. | ||
| --> | ||
|
|
||
| # Error Handling in the Asgardeo Android SDK | ||
|
|
||
| Error handling is an important aspect of any application. It is crucial to handle errors gracefully and provide meaningful error messages to the user. This guide provides details on error handling in the Asgardeo Android SDK. | ||
|
|
||
| As mentioned in the [Start the Authentication Process](./start.md) guide, the `AuthenticationState.Error` state is triggered when an error occurs during the authentication process. This state provides an error message that can be displayed to the user. | ||
|
|
||
| ### How to Capture Errors in the Authentication Process | ||
| The above mentioned error state is triggered when an error occurs during the authentication process, and throws a `FlowManagerException`. You can capture this error and handle it as shown below: | ||
|
|
||
| ```kotlin | ||
| .. | ||
| is AuthenticationState.Error -> { | ||
| when (it.throwable::class.java.simpleName) { | ||
| "FlowManagerException" -> { | ||
| // Handle the error | ||
| } | ||
| } | ||
| } | ||
| .. | ||
| ``` | ||
|
|
||
| You can handle this error by displaying a meaningful error message to the user like a toast message or a snackbar. | ||
|
|
||
| ```kotlin | ||
| .. | ||
| is AuthenticationState.Error -> { | ||
| when (it.throwable::class.java.simpleName) { | ||
| "FlowManagerException" -> { | ||
| Toast.makeText(context, "An error occurred during the authentication process", Toast.LENGTH_SHORT).show() | ||
| } | ||
| } | ||
| } | ||
| .. | ||
| ``` | ||
|
|
||
| Also if you want to show an error message in the TextFields, you have to navigate to the login component and show the error message. | ||
|
|
||
| > [!NOTE] | ||
| > There is an issue in the SDK that the exact error message provided from Asgardeo is not correctly passed to the `FlowManagerException`. This is a known issue that is tracked in the [GitHub repository](https://github.com/asgardeo/mobile-ui-sdks/issues/44). | ||
| ### Authenticator Not Found Error | ||
|
|
||
| If the used authenticator is not found in current authentication step, the `AuthenticationState.Error` state is triggered with a `AuthenticatorProviderException` that contains the error message `Authenticator not found`. You can capture this error and handle it as shown below: | ||
|
|
||
| ```kotlin | ||
| .. | ||
| is AuthenticationState.Error -> { | ||
| when (it.throwable::class.java.simpleName) { | ||
| "AuthenticatorProviderException" -> { | ||
| // Handle the error | ||
| } | ||
| } | ||
| } | ||
| .. | ||
| ``` | ||
|
|
||
| But the best approach is to avoid this error by checking the availability of the authenticator before using it. This can be done by dynamically checking the availability of the authenticator as shown in the [Start the Authentication Process](./start.md) guide. | ||
|
|
||
| ### Authenticator Specific Errors | ||
|
|
||
| #### Redirect Based Authentication Errors | ||
|
|
||
| If the authenticator is a redirect-based authenticator, the `AuthenticationState.Error` state is triggered with a `RedirectAuthenticationException` that contains the error messages like `Redirect URI not found`. You can capture this error and handle it as shown below: | ||
|
|
||
| ```kotlin | ||
| .. | ||
| is AuthenticationState.Error -> { | ||
| when (it.throwable::class.java.simpleName) { | ||
| "RedirectAuthenticationException" -> { | ||
| // Handle the error | ||
| } | ||
| } | ||
| } | ||
| .. | ||
| ``` | ||
|
|
||
| You can see all the error messages that can be thrown by the redirect-based authenticator in the <a href="/mobile-ui-sdks/android/api/core-auth-direct/io.asgardeo.android.core_auth_direct.models.exceptions/-redirect-authentication-exception/-companion/index.html" target="_blank">RedirectAuthenticationException</a> from here. | ||
|
|
||
| #### Google Authentication Error (Legacy & New) | ||
|
|
||
| If the authenticator is Google, the `AuthenticationState.Error` state is triggered with a `GoogleNativeAuthenticationException` that contains the error messages like `Google Web Client ID is not set`. You can capture this error and handle it as shown below: | ||
|
|
||
| ```kotlin | ||
| .. | ||
| is AuthenticationState.Error -> { | ||
| when (it.throwable::class.java.simpleName) { | ||
| "GoogleNativeAuthenticationException" -> { | ||
| // Handle the error | ||
| } | ||
| } | ||
| } | ||
| .. | ||
| ``` | ||
|
|
||
| You can see all the error messages that can be thrown by the Google authenticator in the <a href="/mobile-ui-sdks/android/api/core-auth-direct/io.asgardeo.android.core_auth_direct.models.exceptions/-google-native-authentication-exception/-companion/index.html" target="_blank">GoogleNativeAuthenticationException</a> from here. | ||
|
|
||
| #### Passkey Authentication Error | ||
|
|
||
| If the authenticator is Passkey, the `AuthenticationState.Error` state is triggered with a `PasskeyAuthenticationException` that contains the error messages like `Passkey Authentication is not supported`. You can capture this error and handle it as shown below: | ||
|
|
||
| ```kotlin | ||
| .. | ||
| is AuthenticationState.Error -> { | ||
| when (it.throwable::class.java.simpleName) { | ||
| "PasskeyAuthenticationException" -> { | ||
| // Handle the error | ||
| } | ||
| } | ||
| } | ||
| .. | ||
| ``` | ||
|
|
||
| You can see all the error messages that can be thrown by the Passkey authenticator in the <a href="/mobile-ui-sdks/android/api/core-auth-direct/io.asgardeo.android.core_auth_direct.models.exceptions/-passkey-authentication-exception/-companion/index.html" target="_blank">PasskeyAuthenticationException</a> from here. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters