From fa3808bf266cca11fc955af110285c4a1487449d Mon Sep 17 00:00:00 2001 From: Jan Kobersky <5406945+kober32@users.noreply.github.com> Date: Mon, 12 Feb 2024 15:00:37 +0100 Subject: [PATCH] Improved documentation (#147) --- docs/Error-Handling.md | 51 ++------------------------ docs/Language-Configuration.md | 15 ++++---- docs/Operation-Expiration.md | 8 ++--- docs/SDK-Integration.md | 1 + docs/Using-Inbox-Service.md | 12 +++---- docs/Using-Operations-Service.md | 62 ++++++++++++++++---------------- docs/Using-Push-Service.md | 10 +++--- docs/_Sidebar.md | 3 ++ 8 files changed, 61 insertions(+), 101 deletions(-) diff --git a/docs/Error-Handling.md b/docs/Error-Handling.md index e89508f..6034044 100644 --- a/docs/Error-Handling.md +++ b/docs/Error-Handling.md @@ -1,56 +1,11 @@ # Error Handling -Every error produced by this library is of a `WMTError` type. This error contains the following information: +Errors produced by this library are of type `WPNError` that comes from our networking layer. For more information visit [the library documentation](https://github.com/wultra/networking-apple). -- `reason` - A specific reason, why the error happened. For more information see [WMTErrorReason chapter](#wmterrorreason). -- `nestedError` - Original exception/error (if available) that caused this error. -- `httpStatusCode` - If the error is networking error, this property will provide HTTP status code of the error. -- `httpUrlResponse` - If the error is networking errror, this will hold original HTTP response that was recieved from the backend. -- `restApiError` - If the error is a "well-known" API error, it will be filled here. For more information see [Known REST API Error codes](#known-rest-api-error-codes). -- `networkIsNotReachable` - Convenience property, informs about a state where the network is not available (based on the error type). -- `networkConnectionIsNotTrusted` - Convenience property, informs about a TLS error. -- `powerAuthErrorResponse` - If the error was caused by the PowerAuth error, you can retrieve it here. -- `powerAuthRestApiErrorCode` - If the error was caused by the PowerAuth error, the error code of the original error will be available here. -## Known REST API Error codes +## Custom Error Reasons -| Error Code | Description | -|---|---| -|`authenticationFailure`|General authentication failure (wrong password, wrong activation state, etc...)| -|`invalidRequest`|Invalid request sent - missing request object in the request| -|`invalidActivation`|Activation is not valid (it is different from configured activation)| -|`pushRegistrationFailed`|Error code for a situation when registration to push notification fails| -|`operationAlreadyFinished`|Operation is already finished| -|`operationAlreadyFailed`|Operation is already failed| -|`operationAlreadyCancelled`|Operation is canceled| -|`operationExpired`|Operation is expired| -|`operationFailed`|Default operation action failure| - -## WMTErrorReason - -Each `WMTError` has a `reason` property why the error was created. Such reason can be useful when you're creating for example a general error handling or reporting, or when you're debugging the code. - -### General errors - -| Option Name | Description | -|---|---| -|`unknown`|Unknown fallback reason| -|`missingActivation`|PowerAuth instance is missing an activation.| - -### Network errors - -| Option Name | Description | -|---|---| -|`network_unknown`|When unknown (usually logic error) happened during networking.| -|`network_generic`|When generic networking error happened.| -|`network_errorStatusCode`|HTTP response code was different than 200 (success).` -|`network_invalidResponseObject`|An unexpected response from the server.| -|`network_invalidRequestObject`|Request is not valid. Such an object is not sent to the server.| -|`network_signError`|When the signing of the request failed.| -|`network_timeOut`|Request timed out| -|`network_noInternetConnection`|Not connected to the internet.| -|`network_badServerResponse`|Bad (malformed) HTTP server response. Probably an unexpected HTTP server error.| -|`network_sslError`|SSL error. For detailed information, see the attached error object when available.| +In addition to pre-defined error reasons available in the networking library, we offer more reasons to further offer better error handling. ### Operation errors diff --git a/docs/Language-Configuration.md b/docs/Language-Configuration.md index ae3ec65..d4e0be1 100644 --- a/docs/Language-Configuration.md +++ b/docs/Language-Configuration.md @@ -1,12 +1,5 @@ # 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. - - -Note: Content language capabilities are limited by the implementation of the server - it must support the provided language. - - - ### Usage Both `WMTOperations` and `WMTPush` contain an `acceptLanguage` property that should be set to the user's preferred language. @@ -14,3 +7,11 @@ Both `WMTOperations` and `WMTPush` contain an `acceptLanguage` property that sho ### Format The default value is always `en`. With other languages, we use values compliant with standard RFC [Accept-Language](https://tools.ietf.org/html/rfc7231#section-5.3.5). + + +The language properties are just a wrap-around of the underlying networking language configuration described in [our networking library documentation](https://github.com/wultra/networking-apple). + + + +Note: Content language capabilities are limited by the implementation of the server - it must support the provided language. + \ No newline at end of file diff --git a/docs/Operation-Expiration.md b/docs/Operation-Expiration.md index 0462f5c..c38c898 100644 --- a/docs/Operation-Expiration.md +++ b/docs/Operation-Expiration.md @@ -14,7 +14,7 @@ If you're creating your own custom operation by implementing the `WMTOperation` If the device is [registered to receive push notifications](Using-Push-Service.md), it will receive an [`operationFinished`](https://github.com/wultra/mtoken-sdk-ios/blob/develop/WultraMobileTokenSDK/Push/WMTPushParser.swift#L77#docucheck-keep-link) notification with the [`timeout`](https://github.com/wultra/mtoken-sdk-ios/blob/develop/WultraMobileTokenSDK/Push/WMTPushParser.swift#L86#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: @@ -31,7 +31,7 @@ Server and client device time could differ! You should never remove the operatio ### WMTOperationExpirationWatcher -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 @@ -64,7 +64,7 @@ class MyOperationsService: WMTOperationsDelegate, WMTOperationExpirationWatcherD } func operationsChanged(operations: [UserOperation], removed: [UserOperation], added: [UserOperation]) { - // simplified but working example how operations can be observed for expiration + // simplified but working example of how operations can be observed for expiration expirationWatcher.removeAll() expirationWatcher.add(operations) @@ -78,7 +78,7 @@ class MyOperationsService: WMTOperationsDelegate, WMTOperationExpirationWatcherD // some operation expired, refresh the list refreshOperations() // 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.. } } ``` diff --git a/docs/SDK-Integration.md b/docs/SDK-Integration.md index 0e83070..6eb5668 100644 --- a/docs/SDK-Integration.md +++ b/docs/SDK-Integration.md @@ -62,6 +62,7 @@ Note: If you want to use only operations, you can omit the Push dependency and i | `1.6.x` | `1.7.x` | | `1.7.x` | `1.7.x` | | `1.8.x` | `1.8.x` | +| `1.9.x` | `1.8.x` | ## Xcode Compatibility diff --git a/docs/Using-Inbox-Service.md b/docs/Using-Inbox-Service.md index d58af65..59ed925 100644 --- a/docs/Using-Inbox-Service.md +++ b/docs/Using-Inbox-Service.md @@ -13,10 +13,10 @@ ## Introduction -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. +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 @@ -63,9 +63,9 @@ inboxService.getUnreadCount { result in } ``` -### Get List of Messages +### Get a List of Messages -The Inbox Service provide a paged list of messages: +The Inbox Service provides a paged list of messages: ```swift // First page is 0, next 1, etc... @@ -101,7 +101,7 @@ inboxService.getAllMessages { result in ### 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: ```swift let messageId = messagesList.first!.id @@ -119,7 +119,7 @@ inboxService.getMessageDetail(messageId: messageId) { result in ### 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: ```swift let messageId = messagesList.first!.id diff --git a/docs/Using-Operations-Service.md b/docs/Using-Operations-Service.md index 304f6be..4da3192 100644 --- a/docs/Using-Operations-Service.md +++ b/docs/Using-Operations-Service.md @@ -19,7 +19,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, ... @@ -59,7 +59,7 @@ The `pollingOptions` parameter is used for polling feature configuration. The de ### With custom WMTUserOperation objects -To retreive custom user operations, both `createWMTOperations` methods offer optional parameter `customUserOperationType` where you can setup requested type. +To retrieve custom user operations, both `createWMTOperations` methods offer the optional parameter `customUserOperationType` where you can set up the requested type. ```swift // networkingService is instance of WPNNetworkingService @@ -88,10 +88,10 @@ DispatchQueue.main.async { } ``` -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: Language of the UI data inside the operation depends on the configuration of the `WMTOperation.acceptLanguage`. +Note: The language of the UI data inside the operation depends on the configuration of the `WMTOperation.acceptLanguage`. ## Start Periodic Polling @@ -150,7 +150,7 @@ Polling behavior can be adjusted by the `pollingOptions` parameter when [creatin ## Approve an Operation -To approve an operation use `WMTOperations.authorize`. You can simply use it with following examples: +To approve an operation use `WMTOperations.authorize`. You can simply use it with the following examples: ```swift import WultraMobileTokenSDK @@ -171,7 +171,7 @@ func approve(operation: WMTOperation, 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-iOS.md#biometry-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-iOS.md#biometry-setup). ```swift import WultraMobileTokenSDK @@ -239,9 +239,9 @@ func getDetail(operationId: String) { To claim a non-persolized operation use `WMTOperations.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. The returned result is the operation and its current status and also the claimed operation **is inserted into the operation list**. 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 and also the claimed operation **is inserted into the operation list**. You can simply use it with the following example. ```swift import WultraMobileTokenSDK @@ -292,7 +292,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 is 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), that is automatically processed with the SDK. ### Processing Scanned QR Operation @@ -308,20 +308,20 @@ case .success(let op): // failed to verify signature return } - // opeartion is parsed and verify + // operation is parsed and verify case .failure(let error): - // failed to parse. See error for more info. + // failed to parse. See the error for more info. } ``` ### 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). -Each offline operation created on the server has an __URI ID__ to define its purpose and configuration. The default value used here is `/operation/authorize/offline` and can be modified with the `uriId` parameter in the `authrorize` method. +Each offline operation created on the server has an __URI ID__ to define its purpose and configuration. The default value used here is `/operation/authorize/offline` and can be modified with the `uriId` parameter in the `authorize` method. #### With Password @@ -375,7 +375,7 @@ func approveQROperation(operation: WMTQROperation, 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-iOS.md#biometry-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-iOS.md#biometry-setup). ```swift import WultraMobileTokenSDK @@ -413,10 +413,10 @@ All available methods and attributes of `WMTOperations` API are: - `isLoadingOperations` - Indicates if the service is loading pending operations. - `refreshOperations` - Async "fire and forget" request to refresh pending operations. - `getOperations(completion: @escaping GetOperationsCompletion)` - Retrieves pending operations from the server. - - `completion` - Called when operation finishes. Always called on the main thread. + - `completion` - Called when the operation finishes. Always called on the main thread. - `isPollingOperations` - If the app is periodically polling for the operations from the server. - `pollingOptions` - Configuration of the polling feature - - `pauseWhenOnBackground` - Polling will be paused when your app is on the background. + - `pauseWhenOnBackground` - Polling will be paused when your app is in the background. - `startPollingOperations(interval: TimeInterval, delayStart: Bool)` - Starts the periodic operation polling. - `interval` - How often should operations be refreshed. - `delayStart` - When true, polling starts after the first `interval` time passes. @@ -438,7 +438,7 @@ All available methods and attributes of `WMTOperations` API are: - `completion` - Called when authentication finishes. Always called on the main thread. - `authorize(qrOperation: WMTQROperation, uriId: String, authentication: PowerAuthAuthentication, completion: @escaping(Result) -> Void)` - Sign offline (QR) operation. - `qrOperation ` - Offline operation that can be retrieved via `WMTQROperationParser.parse` method. - - `uriId` - Custom signature URI ID of the operation. Use URI ID under which the operation was created on the server. Usually something like `/confirm/offline/operation`. + - `uriId` - Custom signature URI ID of the operation. Use the URI ID under which the operation was created on the server. Usually something like `/confirm/offline/operation`. - `authentication` - PowerAuth authentication object for operation signing. - `completion` - Called when authentication finishes. Always called on the main thread. @@ -448,7 +448,7 @@ Operations objects retrieved through the `getOperations` API method are called " 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 `WMTUserOperation`: @@ -508,7 +508,7 @@ public class WMTOperationFormData { /// 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 WMTOperationAttributeNote or WMTOperationAttributeAmount. public let attributes: [WMTOperationAttribute] } @@ -516,13 +516,13 @@ public class WMTOperationFormData { 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 `WMTOperationUIData`: @@ -562,7 +562,7 @@ Definition of `WMTProximityCheck`: ```swift public class WMTProximityCheck: Codable { - /// Tha actual Time-based one time password + /// The actual Time-based one-time password public let totp: String /// Type of the Proximity check public let type: WMTProximityCheckType @@ -573,7 +573,7 @@ public class WMTProximityCheck: Codable { WMTProximityCheckType types: -- `qrCode` TOTP was scanned from QR code +- `qrCode` TOTP was scanned from the QR code - `deeplink` TOTP was delivered to the app via Deeplink @@ -623,7 +623,7 @@ opsService.getOperations { result in In some specific scenarios, you might need to approve or reject an operation that you received through a different channel than `getOperations`. In such cases, you can implement the `WMTOperation` protocol in your custom class and then feed created objects to both `authorize` and `reject` methods. -You can use concrete convenient class `WMTLocalOperation`, that implements the `WMTOperation` protocol. +You can use the concrete convenient class `WMTLocalOperation`, which implements the `WMTOperation` protocol. Definition of the `WMTOperation`: @@ -666,16 +666,16 @@ When the `WMTUserOperation` contains a `WMTPreApprovalScreen.qr`, 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 `WMTProximityCheckType.qrCode` or `WMTProximityCheckType.deeplink`. - `timestampReceived`: The timestamp when the QR code was scanned (by default, it is created as the current timestamp). - Authorizing the WMTProximityCheck -When authorization, the SDK will by default add `timestampSent` to the `WMTProximityCheck` object. This timestamp indicates when the operation was signed. +When authorized, the SDK will by default add `timestampSent` to the `WMTProximityCheck` object. This timestamp indicates when the operation was signed. ### WMTPACUtils -- 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. ```swift /// Data which is returned from parsing PAC code @@ -684,15 +684,15 @@ public struct WMTPACData: Decodable { /// The ID of the operation associated with the PAC public let operationId: String - /// Time-based one time password used for Proximity antifraud check + /// Time-based one-time password used for Proximity antifraud check public let totp: String? } ``` - two methods are provided: - - `parseDeeplink(url: URL) -> WMTPACData?` - uri is expected to be in format `"scheme://code=$JWT"` or `scheme://operation?oid=5b753d0d-d59a-49b7-bec4-eae258566dbb&potp=12345678}` + - `parseDeeplink(url: URL) -> WMTPACData?` - 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) -> WMTPACData?` - 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`! diff --git a/docs/Using-Push-Service.md b/docs/Using-Push-Service.md index 43b20f7..1065b93 100644 --- a/docs/Using-Push-Service.md +++ b/docs/Using-Push-Service.md @@ -14,7 +14,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). @@ -46,11 +46,11 @@ let pushService = networkingService.createWMTPush() All available methods of the `WMTPush` API are: -- `pushNotificationsRegisteredOnServer` - If there was already made an successful request. +- `pushNotificationsRegisteredOnServer` - If there was already made a successful request. - `acceptLanguage` - Language settings, that will be sent along with each request. - `registerDeviceTokenForPushNotifications(token: Data, completionHandler: @escaping (_ success: Bool, _ error: WMTError?) -> Void)` - Registers push token on the backend. - `token` - token data retrieved from APNS. - - `completionHandler` - Called when request finishes. Always called on the main thread. + - `completionHandler` - Called when the request finishes. Always called on the main thread. ## Registering to WMT Push Notifications @@ -74,7 +74,7 @@ The above method will get called only if you registered the app to receive push ## Receiving WMT Push Notifications -To process the raw notification obtained from Apple Push Notification service (APNs), you can use `WMTPushParser` helper class that will parse the notification into a `WMTPushMessage` result. +To process the raw notification obtained from the Apple Push Notification Service (APNS), you can use `WMTPushParser` helper class that will parse the notification into a `WMTPushMessage` result. The `WMTPushMessage` can be following values @@ -83,7 +83,7 @@ The `WMTPushMessage` can be following values - `name` of the operation - `content` _(optional)_ of the message presented to the user. - `originalData` - data on which was the push message constructed -- `operationFinished` - an operation was finished, successfully or non-successfully with following parameters +- `operationFinished` - an operation was finished, successfully or non-successfully with the following parameters - `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 42e6671..4fc1112 100644 --- a/docs/_Sidebar.md +++ b/docs/_Sidebar.md @@ -7,4 +7,7 @@ - [Error Handling](./Error-Handling.md) - [Language Configuration](./Language-Configuration.md) - [Logging](./Logging.md) + +**Other** + - [Changelog](./Changelog.md) \ No newline at end of file