From 32b0e2edfed631674b62269e8232db209b1211bc Mon Sep 17 00:00:00 2001 From: Jan Kobersky Date: Mon, 12 Feb 2024 14:11:03 +0100 Subject: [PATCH] Docs fixes --- docs/Language-Configuration.md | 2 +- docs/Logging.md | 8 ++--- docs/Operation-Expiration.md | 12 +++---- docs/SDK-Integration.md | 3 +- docs/Using-Inbox-Service.md | 10 +++--- docs/Using-Operations-Service.md | 57 ++++++++++++++++---------------- docs/Using-Push-Service.md | 10 +++--- docs/_Sidebar.md | 3 ++ 8 files changed, 55 insertions(+), 50 deletions(-) diff --git a/docs/Language-Configuration.md b/docs/Language-Configuration.md index 2e0d1e6..cc9c592 100644 --- a/docs/Language-Configuration.md +++ b/docs/Language-Configuration.md @@ -1,6 +1,6 @@ # Language Configuration -Before using any methods from this SDK that call the backend, a proper language should be set. A properly translated content is served based on this configuration. The property that stores language settings is not persisted. You need to set `acceptLanguage` every time that the application boots. +Before using any methods from this SDK that call the backend, a proper language should be set. A properly translated content is served based on this configuration. The property that stores language settings does not persist. You need to set `acceptLanguage` every time that the application boots. Note: Content language capabilities are limited by the implementation of the server - it must support the provided language. diff --git a/docs/Logging.md b/docs/Logging.md index 2210b06..39d098b 100644 --- a/docs/Logging.md +++ b/docs/Logging.md @@ -1,6 +1,6 @@ # Logging -For logging purposes, WMT uses `Logger` class inside the `com.wultra.android.mtokensdk.common` package that prints to the console. +For logging purposes, WMT uses the `Logger` class inside the `com.wultra.android.mtokensdk.common` package that prints to the console. Note that `Logger` is internally using `android.util.Log` class with verbosity ERROR, WARNING, and DEBUG and is subjected to its internal logic. @@ -8,7 +8,7 @@ Note that `Logger` is internally using `android.util.Log` class with verbosity E ### Verbosity Level -You can limit the amount of logged information via `verboseLevel` static property. +You can limit the amount of logged information via the `verboseLevel` static property. | Level | Description | | --- | --- | @@ -27,8 +27,8 @@ Logger.verboseLevel = Logger.VerboseLevel.DEBUG ### Networking Logs -All requests and responses are logged in `DEBUG` level. +All requests and responses are logged in the `DEBUG` level. -In case that you provided your own OkHttp instance, you need to setup your own logging for monitoring the traffic via the OkHttp interceptors. +In case you provided your own OkHttp instance, you need to set up your own logging for monitoring the traffic via the OkHttp interceptors. diff --git a/docs/Operation-Expiration.md b/docs/Operation-Expiration.md index 5865fa8..d35126a 100644 --- a/docs/Operation-Expiration.md +++ b/docs/Operation-Expiration.md @@ -14,14 +14,14 @@ If you're creating your own custom operation by implementing the `IOperation` in If the device is [registered to receive push notifications](Using-Push-Service.md), it will receive an [`PushMessageOperationFinished `](https://github.com/wultra/mtoken-sdk-android/blob/develop/library/src/main/java/com/wultra/android/mtokensdk/push/PushParser.kt#L80#docucheck-keep-link) notification with the [`TIMEOUT `](https://github.com/wultra/mtoken-sdk-android/blob/develop/library/src/main/java/com/wultra/android/mtokensdk/push/PushParser.kt#L115#docucheck-keep-link) result when the operation expires. -Operation list should be refreshed on such notification. +The operation list should be refreshed on such notification. Please be aware that push notifications are not guaranteed to be received. There are several scenarios where push notification delivery will fail, such as: - user didn't grant notification permission to your app - network error occurred -- notification token has expired and is waiting for renewal +- the notification token has expired and is waiting for renewal - ... other situations not under the developer's control ## Local Handling @@ -32,7 +32,7 @@ Server and client device time could differ! You should never remove the operatio ### OperationExpirationWatcher -Utility class that will observe operations and informs you when it expired. +Utility class that will observe operations and inform you when it expires. #### Sample Implementation @@ -44,12 +44,12 @@ class OperationsManager(private val ops: IOperationsService) { init { operationWatcher.listener = object : OperationExpirationWatcherListener { - // operationsExpired is called on main thread + // operationsExpired is called on the main thread override fun operationsExpired(expiredOperations: List) { // some operation expired, refresh the list launchFetchOperations() // this behavior could be improved for example with - // checking if the expired operations is currently displayed etc.. + // checking if the expired operations are currently displayed etc.. } } } @@ -57,7 +57,7 @@ class OperationsManager(private val ops: IOperationsService) { fun launchFetchOperations() { ops.getOperations(object : IGetOperationListener { override fun onSuccess(operations: List) { - // simplified but working example how operations can be observed for expiration + // simplified but working example of how operations can be observed for expiration operationWatcher.removeAll() operationWatcher.add(operations) // process operations diff --git a/docs/SDK-Integration.md b/docs/SDK-Integration.md index 0d16a85..3bf1990 100644 --- a/docs/SDK-Integration.md +++ b/docs/SDK-Integration.md @@ -25,6 +25,7 @@ implementation "com.wultra.android.powerauth:powerauth-sdk:1.x.y" |-------------------|---| | `1.0.x` - `1.2.x` | `1.0.x` - `1.5.x` | | `1.3.x` - `1.4.x` | `1.6.x` | -| `1.5.x` - `1.6.x` | `1.7.x` | +| `1.5.x` - `1.7.x` | `1.7.x` | +| `1.8.x` - `1.9.x` | `1.8.x` | diff --git a/docs/Using-Inbox-Service.md b/docs/Using-Inbox-Service.md index aa8814e..6b91b2d 100644 --- a/docs/Using-Inbox-Service.md +++ b/docs/Using-Inbox-Service.md @@ -16,7 +16,7 @@ Inbox Service is responsible for managing messages in the Inbox. The inbox is a simple one way delivery system that allows you to deliver messages to the user. -Note: Before using Inbox Service, you need to have a `PowerAuthSDK` object available and initialized with a valid activation. Without a valid PowerAuth activation, service will return an error. +Note: Before using Inbox Service, you need to have a `PowerAuthSDK` object available and initialized with a valid activation. Without a valid PowerAuth activation, the service will return an error. ## Creating an Instance @@ -31,7 +31,7 @@ fun PowerAuthSDK.createInboxService(appContext: Context, baseURL: String, strate - `appContext` - application context - `baseURL` - address, where your operations server can be reached -- `strategy` - strategy used when validating HTTPS requests. Following strategies can be used: +- `strategy` - a strategy used when validating HTTPS requests. The following strategies can be used: - `SSLValidationStrategy.default` - `SSLValidationStrategy.noValidation` - `SSLValidationStrategy.sslPinning` @@ -76,7 +76,7 @@ inboxService.getUnreadCount { } ``` -### Get List of Messages +### Get a List of Messages The Inbox Service provide a paged list of messages: @@ -112,7 +112,7 @@ inboxService.getAllMessages { ### Get Message Detail -Each message has its unique identifier. To get the body of message, use the following code: +Each message has its unique identifier. To get the body of the message, use the following code: ```kotlin let messageId = messagesList.first!.id @@ -129,7 +129,7 @@ inboxService.getMessageDetail(messageId) { ### Set Message as Read -To mark message as read by the user, use the following code: +To mark the message as read by the user, use the following code: ```kotlin let messageId = messagesList.first!.id diff --git a/docs/Using-Operations-Service.md b/docs/Using-Operations-Service.md index bea8a60..f090732 100644 --- a/docs/Using-Operations-Service.md +++ b/docs/Using-Operations-Service.md @@ -18,7 +18,7 @@ ## Introduction -Operations Service is responsible for fetching the operation list and for approving or rejecting operations. +The Operations Service is responsible for fetching the operation list and for approving or rejecting operations. An operation can be anything you need to be approved or rejected by the user. It can be for example money transfer, login request, access approval, ... @@ -40,7 +40,7 @@ fun PowerAuthSDK.createOperationsService(appContext: Context, baseURL: String, s - `appContext` - application context - `baseURL` - address, where your operations server can be reached -- `strategy` - strategy used when validating HTTPS requests. Following strategies can be used: +- `strategy` - a strategy used when validating HTTPS requests. The following strategies can be used: - `SSLValidationStrategy.default` - `SSLValidationStrategy.noValidation` - `SSLValidationStrategy.sslPinning` @@ -81,7 +81,7 @@ operationsService.getOperations { } ``` -After you retrieve the pending operations, you can render them in the UI, for example, as a list of items with a detail of operation shown after a tap. +After you retrieve the pending operations, you can render them in the UI, for example, as a list of items with a detail of the operation shown after a tap. Note: The language of the UI data inside the operation depends on the configuration of the `IOperationsService.acceptLanguage`. @@ -122,7 +122,7 @@ operationsService.listener = object: IOperationsServiceListener { ## Approve an Operation -To approve an operation use `IOperationsService.authorizeOperation`. You can simply use it with following examples: +To approve an operation use `IOperationsService.authorizeOperation`. You can simply use it with the following examples: ```kotlin // Approve operation with password @@ -139,7 +139,7 @@ fun approve(operation: IOperation, password: String) { } ``` -To approve offline operations with biometry, your PowerAuth instance [need to be configured with biometry factor](https://github.com/wultra/powerauth-mobile-sdk/blob/develop/docs/PowerAuth-SDK-for-Android.md#biometric-authentication-setup). +To approve offline operations with biometry, your PowerAuth instance [needs to be configured with biometry factor](https://github.com/wultra/powerauth-mobile-sdk/blob/develop/docs/PowerAuth-SDK-for-Android.md#biometric-authentication-setup). ```kotlin // Approve operation with biometry @@ -182,7 +182,7 @@ fun approveWithBiometry(operation: IOperation) { ## Reject an Operation -To reject an operation use `IOperationsService.rejectOperation`. Operation rejection is confirmed by possession factor so there is no need for creating `PowerAuthAuthentication ` object. You can simply use it with the following example. +To reject an operation use `IOperationsService.rejectOperation`. Operation rejection is confirmed by the possession factor so there is no need for creating `PowerAuthAuthentication ` object. You can simply use it with the following example. ```kotlin // Reject operation with some reason @@ -199,7 +199,7 @@ fun reject(operation: IOperation, reason: RejectionData) { ## Operation detail -To get a detail of the operation based on operation ID use `IOperationsService.getDetail`. Operation detail is confirmed by the possession factor so there is no need for creating `PowerAuthAuthentication` object. The returned result is the operation and its current status. +To get a detail of the operation based on operation ID use `IOperationsService.getDetail`. Operation detail is confirmed by the possession factor so there is no need for creating a `PowerAuthAuthentication` object. The returned result is the operation and its current status. ```kotlin // Retrieve operation details based on the operation ID. @@ -218,9 +218,9 @@ fun getDetail(operationId: String) { To claim a non-persolized operation use `IOperationsService.claim`. -A non-personalized operation refers to an operation that is initiated without a specific operationId. In this state, the operation is not tied to a particular user and lacks a unique identifier. +A non-personalized operation refers to an operation that is initiated without a specific userId. In this state, the operation is not tied to a particular user. -Operation claim is confirmed by the possession factor so there is no need for creating `PowerAuthAuthentication` object. Returned result is the operation and its current status. You can simply use it with the following example. +Operation claim is confirmed by the possession factor so there is no need for creating a `PowerAuthAuthentication` object. The returned result is the operation and its current status. You can simply use it with the following example. ```kotlin // Assigns the 'non-personalized' operation to the user @@ -260,7 +260,7 @@ Note that the operation history availability depends on the backend implementati ## Off-line Authorization -In case the user is not online, you can use off-line authorizations. In this operation mode, the user needs to scan a QR code, enter PIN code or use biometry, and rewrite the resulting code. Wultra provides a special format for [the operation QR codes](https://github.com/wultra/powerauth-webflow/blob/develop/docs/Off-line-Signatures-QR-Code.md), that are automatically processed with the SDK. +In case the user is not online, you can use off-line authorizations. In this operation mode, the user needs to scan a QR code, enter a PIN code, or use biometry, and rewrite the resulting code. Wultra provides a special format for [the operation QR codes](https://github.com/wultra/powerauth-webflow/blob/develop/docs/Off-line-Signatures-QR-Code.md), which are automatically processed with the SDK. ### Processing Scanned QR Operation @@ -281,7 +281,7 @@ fun onQROperationScanned(scannedCode: String): QROperation { ### Authorizing Scanned QR Operation -An offline operation needs to be __always__ approved with __2-factor scheme__ (password or biometry). +An offline operation needs to be __always__ approved with __a 2-factor scheme__ (password or biometry). @@ -326,7 +326,7 @@ fun approveQROperation(operation: QROperation, password: String) { #### With Biometry -To approve offline operations with biometry, your PowerAuth instance [need to be configured with biometry factor](https://github.com/wultra/powerauth-mobile-sdk/blob/develop/docs/PowerAuth-SDK-for-Android.md#biometric-authentication-setup). +To approve offline operations with biometry, your PowerAuth instance [needs to be configured with biometry factor](https://github.com/wultra/powerauth-mobile-sdk/blob/develop/docs/PowerAuth-SDK-for-Android.md#biometric-authentication-setup). To determine if biometry can be used for offline operation authorization, use `QROperation.flags.biometryAllowed`. @@ -397,18 +397,18 @@ All available methods and attributes of `IOperationsService` API are: - `fun authorizeOfflineOperation(operation: QROperation, authentication: PowerAuthAuthentication, uriId: String)` - Sign offline (QR) operation - `operation` - Offline operation retrieved via `QROperationParser.parse` method. - `authentication` - PowerAuth authentication object for operation signing. - - `uriId` - Custom signature URI ID of the operation. Use URI ID under which the operation was created on the server. Default value is `/operation/authorize/offline`. + - `uriId` - Custom signature URI ID of the operation. Use the URI ID under which the operation was created on the server. The default value is `/operation/authorize/offline`. - `signOfflineOperationWithBiometry(biometry: ByteArray, offlineOperation: QROperation)` - Sign offline (QR) operation with biometry data. - - `biometry` - Biometry data retrieved from `powerAuthSDK.authenticateUsingBiometry` call. + - `biometry` - Biometry data retrieved from the `powerAuthSDK.authenticateUsingBiometry` call. - `offlineOperation` - Offline operation retrieved via `processOfflineQrPayload` method. ## UserOperation -Operations objects retrieved through the `getOperations` API method (like `getOperations` method in `IOperationsService`) are called "user operations". +Operations objects retrieved through the `getOperations` API method (like the `getOperations` method in `IOperationsService`) are called "user operations". Under this abstract name, you can imagine for example "Login operation", which is a request for signing in to the online account in a web browser on another device. **In general, it can be any operation that can be either approved or rejected by the user.** -Visually, the operation should be displayed as an info page with all the attributes (rows) of such operation, where the user can decide if he wants to approve or reject it. +Visually, the operation should be displayed as an info page with all the attributes (rows) of such an operation, where the user can decide if he wants to approve or reject it. Definition of the `UserOperations`: @@ -477,7 +477,7 @@ class FormData { /** * Other attributes. * - * Each attribute presents one line in the UI. Attributes are differentiated by type property + * Each attribute presents one line in the UI. Attributes are differentiated by `type` property * and specific classes such as NoteAttribute or AmountAttribute. */ val attributes: List @@ -486,13 +486,13 @@ class FormData { Attributes types: - `AMOUNT` like "100.00 CZK" -- `KEY_VALUE` any key value pair +- `KEY_VALUE` any key-value pair - `NOTE` just like `KEY_VALUE`, emphasizing that the value is a note or message - `HEADING` single highlighted text, written in a larger font, used as a section heading - `PARTY_INFO` providing structured information about third-party data (for example known e-shop) -- `AMOUNT_CONVERSION` providing data about Money conversion +- `AMOUNT_CONVERSION` provides data about Money conversion - `IMAGE` image row -- `UNKNOWN` fallback option when unknown attribute type is passed. Such attribute only contains the label. +- `UNKNOWN` fallback option when an unknown attribute type is passed. Such an attribute only contains the label. Definition of `OperationUIData`: @@ -535,7 +535,7 @@ Definition of `ProximityCheck`: ```kotlin class ProximityCheck { - /** The actual Time-based one time password */ + /** The actual Time-based one-time password */ val totp: String /** Type of the Proximity check */ @@ -548,7 +548,7 @@ class ProximityCheck { ProximityCheckType types: -- `QR_CODE` TOTP was scanned from QR code +- `QR_CODE` TOTP was scanned from the QR code - `DEEPLINK` TOTP was delivered to the app via Deeplink ## Creating a Custom Operation @@ -594,7 +594,7 @@ When the `UserOperation` contains a `PreApprovalScreen.QR_SCAN`, the app should When the app is launched via a deeplink, preserve the data from the deeplink and extract the relevant data. When operations are loaded compare the operation ID from the deeplink data to the operations within the app to find a match. - Assign TOTP and Type to the Operation - Once the QR code is scanned or match from the deeplink is found, create a `WMTProximityCheck` with: + Once the QR code is scanned or a match from the deeplink is found, create a `WMTProximityCheck` with: - `totp`: The actual Time-Based One-Time Password. - `type`: Set to `ProximityCheckType.QR_CODE` or `ProximityCheckType.DEEPLINK`. - `timestampReceived`: The timestamp when the QR code was scanned (by default, it is created as the current timestamp when the object is instantiated). @@ -603,7 +603,8 @@ When the app is launched via a deeplink, preserve the data from the deeplink and When authorizing, the SDK will by default add `timestampSent` to the `ProximityCheck` object. This timestamp indicates when the operation was sent. ### PACUtils -- For convenience, utility class for parsing and extracting data from QR codes and deeplinks used in the PAC (Proximity Anti-fraud Check), is provided. + +- For convenience, a utility class for parsing and extracting data from QR codes and deeplinks used in the PAC (Proximity Anti-fraud Check), is provided. ```kotlin /** Data payload which is returned from the parser */ @@ -612,15 +613,15 @@ data class PACData( /** The ID of the operation associated with the TOTP */ val operationId: String, - /** The actual Time-based one time password */ + /** The actual Time-based one-time password */ val totp: String? ) ``` - two methods are provided: - - `parseDeeplink(uri: Uri): PACData?` - uri is expected to be in format `"scheme://code=$JWT"` or `scheme://operation?oid=5b753d0d-d59a-49b7-bec4-eae258566dbb&potp=12345678}` + - `parseDeeplink(uri: Uri): PACData?` - URI is expected to be in the format `"scheme://code=$JWT"` or `scheme://operation?oid=5b753d0d-d59a-49b7-bec4-eae258566dbb&potp=12345678}` - `parseQRCode(code: String): PACData?` - code is to be expected in the same format as deeplink formats or as a plain JWT - - mentioned JWT should be in format `{“typ”:”JWT”, “alg”:”none”}.{“oid”:”5b753d0d-d59a-49b7-bec4-eae258566dbb”, “potp”:”12345678”} ` + - mentioned JWT should be in the format `{“typ”:”JWT”, “alg”:”none”}.{“oid”:”5b753d0d-d59a-49b7-bec4-eae258566dbb”, “potp”:”12345678”} ` - Accepted formats: - - notice that totp key in JWT and in query shall be `potp`! \ No newline at end of file + - notice that the totp key in JWT and in query shall be `potp`! \ No newline at end of file diff --git a/docs/Using-Push-Service.md b/docs/Using-Push-Service.md index 3b61d66..39bb0ec 100644 --- a/docs/Using-Push-Service.md +++ b/docs/Using-Push-Service.md @@ -12,7 +12,7 @@ Push Service is responsible for registering the device for the push notifications about the Operations that are tied to the current PowerAuth activation. -Note: Before using Push Service, you need to have a `PowerAuthSDK` object available and initialized with a valid activation. Without a valid PowerAuth activation, service will return an error. +Note: Before using Push Service, you need to have a `PowerAuthSDK` object available and initialized with a valid activation. Without a valid PowerAuth activation, the service will return an error. Push Service communicates with [Mobile Push Registration API](https://github.com/wultra/powerauth-webflow/blob/develop/docs/Mobile-Push-Registration-API.md). @@ -29,7 +29,7 @@ fun PowerAuthSDK.createPushService(appContext: Context, baseURL: String, strateg - `appContext` - application context - `baseURL` - address, where your operations server can be reached -- `strategy` - strategy used when validating HTTPS requests. Following strategies can be used: +- `strategy` - a strategy used when validating HTTPS requests. The following strategies can be used: - `SSLValidationStrategy.default` - `SSLValidationStrategy.noValidation` - `SSLValidationStrategy.sslPinning` @@ -65,7 +65,7 @@ All available methods of the `IPushService` API are: To register an app to push notifications, you can simply call the `register` method: ```kotlin -// first, retrieve FireBase token +// first, retrieve the Firebase token FirebaseInstanceId.getInstance().instanceId.addOnCompleteListener { task -> if (task.isSuccessful) { task.result?.token?.let { token -> @@ -87,7 +87,7 @@ To be able to successfully process notifications, you need to register the app t ## Receiving WMT Push Notifications -To process the raw notification obtained from Firebase Cloud Messaging service (FCM), you can use `PushParser` helper class that will parse the notification into a `PushMessage` result. +To process the raw notification obtained from the Firebase Cloud Messaging service (FCM), you can use the `PushParser` helper class that will parse the notification into a `PushMessage` result. The `PushMessage` is an abstract class that is implemented by following classes for concrete results @@ -95,7 +95,7 @@ The `PushMessage` is an abstract class that is implemented by following classes - `id` of the operation - `name` of the operation - `originalData` - data on which was the push message constructed -- `PushMessageOperationFinished` - an operation was finished, successfully or non-successfully with following properties +- `PushMessageOperationFinished` - an operation was finished, successfully or non-successfully with the following properties - `id` of the operation - `name` of the operation - `result` of the operation (for example that the operation was canceled by the user). diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md index 356fac4..9f2d177 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -6,4 +6,7 @@ - [Using Inbox Service](./Using-Inbox-Service.md) - [Error Handling](./Error-Handling.md) - [Language Configuration](./Language-Configuration.md) + +**Other** + - [Changelog](./Changelog.md)