Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved documentation #147

Merged
merged 2 commits into from
Feb 12, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 3 additions & 48 deletions docs/Error-Handling.md
Original file line number Diff line number Diff line change
@@ -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

Expand Down
15 changes: 8 additions & 7 deletions docs/Language-Configuration.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
# 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.

<!-- begin box warning -->
Note: Content language capabilities are limited by the implementation of the server - it must support the provided language.
<!-- end -->


### Usage

Both `WMTOperations` and `WMTPush` contain an `acceptLanguage` property that should be set to the user's preferred language.

### 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).

<!-- begin box info -->
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).
<!-- end -->

<!-- begin box warning -->
Note: Content language capabilities are limited by the implementation of the server - it must support the provided language.
<!-- end -->
8 changes: 4 additions & 4 deletions docs/Operation-Expiration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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

Expand Down Expand Up @@ -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)

Expand All @@ -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..
}
}
```
1 change: 1 addition & 0 deletions docs/SDK-Integration.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
12 changes: 6 additions & 6 deletions docs/Using-Inbox-Service.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,10 +13,10 @@
## Introduction
<!-- end -->

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.

<!-- begin box warning -->
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.
<!-- end -->

## Creating an Instance
Expand Down Expand Up @@ -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...
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
Loading
Loading