Documentation improvements

wultra · Mar 6, 2024 · 096e9c1 · 096e9c1
1 parent b607879
commit 096e9c1
Show file tree

Hide file tree

Showing 4 changed files with 59 additions and 74 deletions.
diff --git a/docs/Changelog.md b/docs/Changelog.md
@@ -1,10 +1,15 @@
 # Changelog
 
-## 1.1.0 (Mar 4, 2023)
+## 1.1.1 (Mar 6, 2024)
+
+- Minor fixes
+- Improved error handling
+
+## 1.1.0 (Mar 4, 2024)
 
 - Using PowerAuth SDK `1.8.x`
 
-## 1.0.3 (Mar 4, 2023)
+## 1.0.3 (Mar 4, 2024)
 
 - Documentation improvements
 - Logs improvements

diff --git a/docs/Device-Activation.md b/docs/Device-Activation.md
@@ -53,7 +53,7 @@ If the process was started, you can verify its status by calling the `status` fu
  *
  * @param callback Callback with the result.
  */
-fun status(callback: (Result<Status>) -> Unit)
+fun status(callback: (ActivationResult<Status>) -> Unit)
 ```
 
 `Status` possible values.
@@ -127,7 +127,7 @@ To start the activation, use the `start` function.
  * @param credentials Object with credentials. Which credentials are needed should be provided by a system/backend provider.
  * @param callback Callback with the result.
  */
-fun <T> start(credentials: T, callback: (Result<Unit>) -> Unit)
+fun <T> start(credentials: T, callback: (ActivationResult<Unit>) -> Unit)
 ```
 
 ### Example
@@ -173,7 +173,7 @@ Use the `activate` function to create the activation.
 fun activate(
     otp: String,
     activationName: String = Build.MODEL,
-    callback: (Result<CreateActivationResult>) -> Unit
+    callback: (ActivationResult<CreateActivationResult>) -> Unit
 )
 ```
 
@@ -215,7 +215,7 @@ To cancel the process, just call the `cancel` function.
  * @param forceCancel When true, the process will be canceled in the SDK even when fails on the backend. `true` by default.
  * @param callback Callback with the result.
  */
-fun cancel(forceCancel: Boolean = true, callback: (Result<Unit>) -> Unit) 
+fun cancel(forceCancel: Boolean = true, callback: (ActivationResult<Unit>) -> Unit) 
 ```
 
 ## OTP resend
@@ -232,20 +232,20 @@ In some cases, you need to resent the OTP:
  *
  * @param callback Callback with the result.
  */
-fun resendOtp(callback: (Result<Unit>) -> Unit)
+fun resendOtp(callback: (ActivationResult<Unit>) -> Unit)
  ```
 
 ## Errors
 
-All functions that can return an exception. The networking exceptions are by the type of `ApiErrorException` - more about these errors can be found in [the networking library documentation](https://github.com/wultra/networking-android).
+All functions that can return an exception are of type `ActivationService.Fail` that contains `cause: ApiError` - more about these `ApiError` errors can be found in [the networking library documentation](https://github.com/wultra/networking-android).
 
 There are 3 custom exceptions that this service is adding:
 
-| Custom `WPNErrorReason` |      Description          |  
-|--------------|---------------------|
-| `ActivationInProgressException`  |  Activation is already in progress.         | 
-| `ActivationNotRunningException`  |  Activation was not started. | 
-| `CannotActivateException`  |  PowerAuth instance cannot start the activation (probably already activated). | 
+| Custom `Exception` in the `cause` | Description                                                                  |  
+|-----------------------------------|------------------------------------------------------------------------------|
+| `ActivationInProgressException`   | Activation is already in progress.                                           | 
+| `ActivationNotRunningException`   | Activation was not started.                                                  | 
+| `CannotActivateException`         | PowerAuth instance cannot start the activation (probably already activated). | 
 
 ## Read next
 - [Verifying User With Document Scan And Genuine Presence Check](Verifying-User.md)
diff --git a/docs/SDK-Integration.md b/docs/SDK-Integration.md
@@ -20,7 +20,7 @@ repositories {
 Then add a dependency
 
 ```kotlin
-implementation("com.wultra.android.digitalonboarding:wultra-digital-onboarding:1.0.2")
+implementation("com.wultra.android.digitalonboarding:wultra-digital-onboarding:1.1.1")
 ```
 
 ## Guaranteed PowerAuth Compatibility

diff --git a/docs/Verifying-User.md b/docs/Verifying-User.md
@@ -59,18 +59,18 @@ The service can return the state via the `status()` method or various other call
 ### Intro
 
 | `VerificationState` value | `VerificationStateData` class |  
-|--------------|---------------------|
-| `INTRO`  |  `VerificationStateIntroData` | 
+|---------------------------|-------------------------------|
+| `INTRO`                   | `VerificationStateIntroData`  | 
 
 Show the verification introduction screen where the user can start the activation.
 
 The next step should be calling the `getConsentText()`.
 
 ### Consent
 
-| `VerificationState` value | `VerificationStateData` class |  
-|--------------|---------------------|
-| `CONSENT`  |  `VerificationStateConsentData` with `val consentHtml: String` property | 
+| `VerificationState` value | `VerificationStateData` class                                          |  
+|---------------------------|------------------------------------------------------------------------|
+| `CONSENT`                 | `VerificationStateConsentData` with `val consentHtml: String` property | 
 
 Show approve/cancel user consent.
 
@@ -80,18 +80,18 @@ The next step should be calling the `consentApprove()`
 
 ### Select documents to scan
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `DOCUMENTS_TO_SCAN_SELECT`  |  `VerificationStateDocumentsToScanSelectData` | 
+| `VerificationState`        | `VerificationStateData` class                |  
+|----------------------------|----------------------------------------------|
+| `DOCUMENTS_TO_SCAN_SELECT` | `VerificationStateDocumentsToScanSelectData` | 
 
 Show document selection to the user. Which documents are available and how many can the user select is up to your backend configuration.  
 The next step should be calling the `documentsSetSelectedTypes`.
 
 ### Scan document
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `SCAN_DOCUMENT`  |  `VerificationStateScanDocumentData` with `val scanDocumentProcess: VerificationScanProcess` property | 
+| `VerificationState` | `VerificationStateData` class                                                                        |  
+|---------------------|------------------------------------------------------------------------------------------------------|
+| `SCAN_DOCUMENT`     | `VerificationStateScanDocumentData` with `val scanDocumentProcess: VerificationScanProcess` property | 
 
 User should scan documents - display UI for the user to scan all necessary documents.
 
@@ -101,19 +101,19 @@ The next step should be calling the `documentsSubmit`.
 
 ### Processing
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `PROCESSING`  |  `VerificationStateProcessingData` with `val processingItem: ProcessingItem` property | 
+| `VerificationState` | `VerificationStateData` class                                                        |  
+|---------------------|--------------------------------------------------------------------------------------|
+| `PROCESSING`        | `VerificationStateProcessingData` with `val processingItem: ProcessingItem` property | 
 
 The system is processing data - show loading with text hint from provided `ProcessingItem`.
 
 The next step should be calling the `status`.
 
 ### Presence check
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `PRESENCE_CHECK`  |  `VerificationStatePresenceCheckData` | 
+| `VerificationState` | `VerificationStateData` class        |  
+|---------------------|--------------------------------------|
+| `PRESENCE_CHECK`    | `VerificationStatePresenceCheckData` | 
 
 The user should be presented with a presence check.  
 
@@ -123,9 +123,9 @@ The next step should be calling the `presenceCheckInit` to start the check and `
 
 ### OTP
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `OTP`  |  `VerificationStateOtpData` with `val remainingAttempts: Int?` property | 
+| `VerificationState` | `VerificationStateData` class                                          |  
+|---------------------|------------------------------------------------------------------------|
+| `OTP`               | `VerificationStateOtpData` with `val remainingAttempts: Int?` property | 
 
 Show enter OTP screen with the resend button. `remainingAttempts` property contains a number of OTP attempts a user can try.
 
@@ -134,28 +134,28 @@ The next step should be calling the `verifyOTP` with the user-entered OTP. The O
 ### Failed
 
 | `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `FAILED`  |  `VerificationStateFailedData` | 
+|---------------------|-------------------------------|
+| `FAILED`            | `VerificationStateFailedData` | 
 
 Verification failed and can be restarted
 
 The next step should be calling the `restartVerification` or `cancelWholeProcess` based on the user's decision if he wants to try it again or cancel the process.
 
 ### Endstate
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `ENDSTATE`  |  `VerificationStateEndstateData` with `val endstateReason: EndstateReason` property | 
+| `VerificationState` | `VerificationStateData` class                                                      |  
+|---------------------|------------------------------------------------------------------------------------|
+| `ENDSTATE`          | `VerificationStateEndstateData` with `val endstateReason: EndstateReason` property | 
 
 Verification is canceled and the user needs to start again with a new PowerAuth activation. To explain why that happened, you can show additional information to the user based on the `endstateReason` property.
 
 The next step should be calling the `PowerAuthSDK.removeActivationLocal()` and starting activation from scratch.
 
 ### Success
 
-| `VerificationState` | `VerificationStateData` class |  
-|--------------|---------------------|
-| `SUCCESS`  |  `VerificationStateSuccessData` | 
+| `VerificationState` | `VerificationStateData` class  |  
+|---------------------|--------------------------------|
+| `SUCCESS`           | `VerificationStateSuccessData` | 
 
 Verification was successfully ended. Continue into your app's regular "log-in" scenario.
 
@@ -199,15 +199,10 @@ verification.status { result ->
     result.onSuccess { stateData ->
         // handle `VerificationService.Success` state and navigate to the expected screen
     }.onFailure { 
-        if (it is VerificationService.Fail) {
-            if (it.state != null) {
-                // show expected screen based on the state
-            } else {
-                // navigate to error screen and show the error in
-                // it.cause
-            }
+        if (it.state != null) {
+            // show expected screen based on the state
         } else {
-            // generic exception handling
+            // navigate to error screen and show the error in `it.reason`
         }
     }
 }
@@ -225,15 +220,10 @@ verification.consentGet { result ->
             // handle consent state
         }
     }.onFailure {
-        if (it is VerificationService.Fail) {
-            if (it.state != null) {
-                // show expected screen based on the state
-            } else {
-                // navigate to error screen and show the error in
-                // it.cause
-            }
+        if (it.state != null) {
+            // show expected screen based on the state
         } else {
-            // generic exception handling
+            // navigate to error screen and show the error in `it.reason`
         }
     }
 }
@@ -255,15 +245,10 @@ verification.consentApprove { result ->
             // handle consent state
         }
     }.onFailure {
-        if (it is VerificationService.Fail) {
-            if (it.state != null) {
-                // show expected screen based on the state
-            } else {
-                // navigate to error screen and show the error in
-                // it.cause
-            }
+        if (it.state != null) {
+            // show expected screen based on the state
         } else {
-            // generic exception handling
+            // navigate to error screen and show the error in `it.reason`
         }
     }
 }
@@ -284,15 +269,10 @@ verification.documentsSetSelectedTypes(list) { result ->
             // handle consent state
         }
     }.onFailure {
-        if (it is VerificationService.Fail) {
-            if (it.state != null) {
-                // show expected screen based on the state
-            } else {
-                // navigate to the error screen and show the error in
-                // it.cause
-            }
+        if (it.state != null) {
+            // show expected screen based on the state
         } else {
-            // generic exception handling
+            // navigate to error screen and show the error in `it.reason`
         }
     }
 }