diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 00000000..7f46f3a7 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,5 @@ +name: client-sdk-android +title: Ost Client (Mobile Wallet) SDK Android +version: '1.0' +nav: +- modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/_attributes.adoc b/docs/modules/ROOT/_attributes.adoc new file mode 100644 index 00000000..e69de29b diff --git a/docs/modules/ROOT/assets/attachments/.gitkeep b/docs/modules/ROOT/assets/attachments/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/modules/ROOT/assets/images/.gitkeep b/docs/modules/ROOT/assets/images/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/modules/ROOT/assets/images/Card.png b/docs/modules/ROOT/assets/images/Card.png new file mode 100644 index 00000000..88d5bd2a Binary files /dev/null and b/docs/modules/ROOT/assets/images/Card.png differ diff --git a/docs/modules/ROOT/assets/images/DeviceListLabelTypes.png b/docs/modules/ROOT/assets/images/DeviceListLabelTypes.png new file mode 100644 index 00000000..50a3c8d0 Binary files /dev/null and b/docs/modules/ROOT/assets/images/DeviceListLabelTypes.png differ diff --git a/docs/modules/ROOT/assets/images/NavBar.png b/docs/modules/ROOT/assets/images/NavBar.png new file mode 100644 index 00000000..9e27a32d Binary files /dev/null and b/docs/modules/ROOT/assets/images/NavBar.png differ diff --git a/docs/modules/ROOT/assets/images/PinView.png b/docs/modules/ROOT/assets/images/PinView.png new file mode 100644 index 00000000..68e174aa Binary files /dev/null and b/docs/modules/ROOT/assets/images/PinView.png differ diff --git a/docs/modules/ROOT/assets/images/PinViewLabelTypes.png b/docs/modules/ROOT/assets/images/PinViewLabelTypes.png new file mode 100644 index 00000000..e568784e Binary files /dev/null and b/docs/modules/ROOT/assets/images/PinViewLabelTypes.png differ diff --git a/docs/modules/ROOT/assets/images/ProvideMnemonics.png b/docs/modules/ROOT/assets/images/ProvideMnemonics.png new file mode 100644 index 00000000..85169e95 Binary files /dev/null and b/docs/modules/ROOT/assets/images/ProvideMnemonics.png differ diff --git a/docs/modules/ROOT/assets/images/ScanQR.png b/docs/modules/ROOT/assets/images/ScanQR.png new file mode 100644 index 00000000..1f72fdf5 Binary files /dev/null and b/docs/modules/ROOT/assets/images/ScanQR.png differ diff --git a/docs/modules/ROOT/assets/images/ShowQR.png b/docs/modules/ROOT/assets/images/ShowQR.png new file mode 100644 index 00000000..5c8ccfce Binary files /dev/null and b/docs/modules/ROOT/assets/images/ShowQR.png differ diff --git a/docs/modules/ROOT/assets/images/TextField.png b/docs/modules/ROOT/assets/images/TextField.png new file mode 100644 index 00000000..4d89a911 Binary files /dev/null and b/docs/modules/ROOT/assets/images/TextField.png differ diff --git a/docs/modules/ROOT/assets/images/VerifyDevice.png b/docs/modules/ROOT/assets/images/VerifyDevice.png new file mode 100644 index 00000000..4ed535e1 Binary files /dev/null and b/docs/modules/ROOT/assets/images/VerifyDevice.png differ diff --git a/docs/modules/ROOT/assets/images/VerifyTX.png b/docs/modules/ROOT/assets/images/VerifyTX.png new file mode 100644 index 00000000..a3e23089 Binary files /dev/null and b/docs/modules/ROOT/assets/images/VerifyTX.png differ diff --git a/docs/modules/ROOT/assets/images/ViewMnemonicsLabelTypes.png b/docs/modules/ROOT/assets/images/ViewMnemonicsLabelTypes.png new file mode 100644 index 00000000..493378a1 Binary files /dev/null and b/docs/modules/ROOT/assets/images/ViewMnemonicsLabelTypes.png differ diff --git a/docs/modules/ROOT/examples/.gitkeep b/docs/modules/ROOT/examples/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/modules/ROOT/examples/OstSdkMessages-CustomLoader.json b/docs/modules/ROOT/examples/OstSdkMessages-CustomLoader.json new file mode 100644 index 00000000..1f48a902 --- /dev/null +++ b/docs/modules/ROOT/examples/OstSdkMessages-CustomLoader.json @@ -0,0 +1,105 @@ +{ + "ACTIVATE_USER": { + "SUCCESS_MESSAGE": "User activated" + }, + "ADD_SESSION": { + "SUCCESS_MESSAGE": "Session added" + }, + "GET_DEVICE_MNEMONICS": { + }, + "PERFORM_QR_ACTION": { + "SUCCESS_MESSAGE": "Workflow completed!" + }, + "AUTHORIZE_DEVICE_WITH_QR_CODE": { + "SUCCESS_MESSAGE": "Device authorized" + }, + "AUTHORIZE_DEVICE_WITH_MNEMONICS": { + "SUCCESS_MESSAGE": "Device authorized" + }, + "INITIATE_DEVICE_RECOVERY": { + "SUCCESS_MESSAGE": "Recovery initiated" + }, + "ABORT_DEVICE_RECOVERY": { + "SUCCESS_MESSAGE": "Aborted recovery" + }, + "RESET_PIN": { + "SUCCESS_MESSAGE": "PIN has been successfully reset" + }, + "LOGOUT_ALL_SESSIONS": { + "SUCCESS_MESSAGE": "User Activated Successfully" + }, + "UPDATE_BIOMETRIC_PREFERENCE": { + "SUCCESS_MESSAGE": "Biometric updated" + }, + "EXECUTE_TRANSACTION": { + "SUCCESS_MESSAGE": "Tranasction executed" + }, + "__DEFAULT_CONTEXT": { + "USER_UNAUTHORIZED": "Device is not authorized. Please authorize device again.", + "DEVICE_OUT_OF_SYNC": "Device time is out of sync. Please check the time on your device reflects current date and time.", + "NETWORK_ERROR": "Request could not be executed due to cancellation, a connectivity problem or timeout.", + "INVALID_MNEMONICS": "The 12 word passphrase you provided is incorrect. ", + "INVALID_QR_TRANSACTION_DATA": "The QR code for executing a transaction is not well formed. To know the data definition for QR code based on type of operations please visit https://dev.ost.com/platform ", + "INVALID_USER_PASSPHRASE": "The 6 digit PIN you entered is not correct.", + "MAX_PASSPHRASE_VERIFICATION_LIMIT_REACHED": "The maximum number of 'authenticating with PIN' attempts has been reached. Please try again a bit later.", + "DEVICE_CAN_NOT_BE_AUTHORIZED": "Unable to authorize this device. Please ensure the device is 'Registered' for this user with OST platform. Only a registered device can be authorized.", + "SESSION_NOT_FOUND": "The device doesn't has any active session. Please authorize a session before doing any transaction. Workflow details provided at https://dev.ost.com/platform/docs/sdk/references ", + "INVALID_QR_CODE": "Incorrect QR code.", + "RECOVERY_KEY_GENERATION_FAILED": "Failed to generate Recovery key. Inspect if a correct input values required are being sent and re-submit the request. ", + "OUT_OF_MEMORY_ERROR": "Device is running low on memory. Reduce the number of App running on your device and re-enter the pin", + "WORKFLOW_FAILED": "Something went wrong, please try again", + "WORKFLOW_VIEW_DESTROYED": "The application interrupted the workflow. The view got terminated while performing the workflow", + "DEVICE_UNAUTHORIZED": "Unable to perform the operation as the device not authorized. For details on how to authorize a device please visit https://dev.ost.com/platform/docs/sdk/references ", + "DEVICE_CAN_NOT_BE_REVOKED": "Cannot complete the revoke device operation. Only an authorized device can be revoked. Please ensure you are trying to revoke a valid device and re-submit the request.", + "WORKFLOW_CANCELED": "WORKFLOW_CANCELLED", + "WORKFLOW_CANCELLED": "WORKFLOW_CANCELLED" + }, + "__DEVELOPER_ERROR_MSG": { + "SDK_ERROR": "An internal SDK error has occurred.", + "INVALID_CERTIFICATE": "Certificate provided by Ost platform is invalid Or it has been compromised. Please re-try in some other network and if the problem persists contact support@ost.com .", + "INVALID_USER_ID": "Unable to recognize the user id. Please inspect for what is being sent, rectify and re-submit.", + "INVALID_API_END_POINT": "Invalid OST server url", + "INVALID_NETWORK_SECURITY_CONFIG": "Invalid network_security_config file", + "INVALID_WORKFLOW_CALLBACK": "Callback is essential for a workflow to continue running, it cannot be null.", + "API_RESPONSE_ERROR": "OST Platform Api ed error.", + "CONFIG_READ_FAILED": "Failed to read config file. Please place the ost-sdk config file in main/assets folder.", + "INVALID_BLOCK_GENERATION_TIME": "Invalid configuration 'BLOCK_GENERATION_TIME'. It must be an Integer greater than zero", + "INVALID_PIN_MAX_RETRY_COUNT": "Invalid configuration 'PIN_MAX_RETRY_COUNT'. It must be an Integer greater than zero", + "INVALID_SESSION_BUFFER_TIME": "Invalid configuration 'SESSION_BUFFER_TIME'. It must be long greater than or equal to zero", + "INVALID_PRICE_POINT_CURRENCY_SYMBOL": "Unable to recognize 'PRICE_POINT_CURRENCY_SYMBOL'. For details on how supported currencies please vist https://dev.ost.com/platform/docs/api ", + "INVALID_REQUEST_TIMEOUT_DURATION": "Invalid configuration 'REQUEST_TIMEOUT_DURATION'. It must be Integer greater than zero.", + "INVALID_NO_OF_SESSIONS_ON_ACTIVATE_USER": "Invalid configuration 'NO_OF_SESSIONS_ON_ACTIVATE_USER'. It must be an Integer greater than zero and less than 6", + "INVALID_API_RESPONSE": "Unable to recognize the API response object sent and so cannot be executed.", + "INVALID_JSON_STRING": "The provided json string is invalid.", + "INVALID_JSON_ARRAY": "The provided json array string is invalid.", + "INVALID_REVOKE_DEVICE_ADDRESS": "Unable to recognise revoke device address. Please ensure you are sending a null value and re-submit the request.", + "NO_PENDING_RECOVERY": "Could not find any pending device recovery request. For details on how to check the status of the recovery please vist https://dev.ost.com/platform/docs/sdk ", + "EIP712_FAILED": "Unable to sign parameters using EIP 712 and verify the signature.", + "RULES_NOT_FOUND": "Unable to recognize the Rule. Please inspect a valid rule name that exists in your economy is passed and its not null.", + "DEVICE_NOT_SETUP": "Unable to recognize the device. Please setup this device for the user using workflow provided at https://dev.ost.com/platform/docs/sdk/references", + "DEVICE_NOT_REGISTERED": "Device is not registered. To make any api to OST server device need to be registered", + "POLLING_TIMEOUT": "Polling timeout. This can be intermittent event with a request failing followed by successful one.", + "INVALID_TOKEN_ID": "The token id sent in Transaction QR code is not matching with the current user's token id. Rectify the value is being sent in token Id field and re-submit the request.", + "INVALID_RECOVER_DEVICE_ADDRESS": "Invalid device address. This address can not be recovered.", + "INVALID_SESSION_EXPIRY_TIME": "The expiry time provided is invalid", + "INVALID_SESSION_SPENDING_LIMIT": "The spending limit provided is invalid should be more than 0", + "RECOVERY_OWNER_ADDRESS_NOT_FOUND": "Recovery owner is not set for this user. This address is set during user activation. Please verify the user has been successfully activated.", + "INSUFFICIENT_DATA": "The device does not have sufficient data to perform this action.", + "INVALID_SESSION_ADDRESS": "Unable to recognize the session address. Inspect if a correct value is being sent and its not null. ", + "FAILED_TO_SIGN_DATA": "Unable to sign data. Visit https://dev.ost.com/platform/docs/sdk for detailed SDK references. Please ensure the input is well formed and re-submit the request.", + "INVALID_DEVICE_ADDRESS": "Incorrect device address. Please inspect the value being sent is correct and not null, rectify and re-submit.", + "GENERATE_PRIVATE_KEY_FAIL": "This is a generic error that occurs when sdk fails to generate any one of Api Key, Device Key or Session Key. This can be intermittent issue, please re-start the workflow. If Problem persists contact support@ost.com .", + "INVALID_PASSPHRASE_PREFIX": "Unable to recognize the Passphrase prefix. Please ensure Passphrase prefix is not null or it's string length is not less than 30. ", + "USER_NOT_ACTIVATED": "The user is not activated yet. Please setup user's wallet to enable their participation in your economy. ", + "USER_ALREADY_ACTIVATED": "The User is already activated", + "USER_ACTIVATING": "User activation flow is already in progress. Please check the status a bit later", + "WORKFLOW_CANCELLED": "Workflow got cancelled, possibly because one or more input parameters require a different type of information.", + "INVALID_NEW_USER_PASSPHRASE": "The new 6 digit PIN you entered is not correct.", + "INVALID_ADDRESS_TO_TRANSFER": "INVALID_ADDRESS_TO_TRANSFER", + "INVALID_AMOUNT": "INVALID_AMOUNT", + "INVALID_WORKFLOW": "INVALID_WORKFLOW", + "INVALID_RECOVERY_ADDRESS": "INVALID_RECOVERY_ADDRESS", + "USER_PASSPHRASE_VALIDATION_LOCKED": "Can not validate user passphrase because of too many wrong attempts.", + "UNKNOWN": "Unknown error" + } +} \ No newline at end of file diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 00000000..9b25ba0a --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,8 @@ +* xref:index.adoc[Overview] +* xref:OstJsonApi.adoc[Ost JSON API] +* xref:OstWalletUI.adoc[Ost Wallet UI] +* xref:ContentConfig.adoc[UI Content Config] +* xref:ThemeConfig.adoc[UI Theme Config] +* xref:OstCustomLoader.adoc[Ost Custom Loader] +* xref:TrustKitPublickeyPinning.adoc[TrustKit Public Key Pinning] +* xref:CHANGELOG.adoc[Change Log] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/CHANGELOG.adoc b/docs/modules/ROOT/pages/CHANGELOG.adoc new file mode 100644 index 00000000..7d7f5a87 --- /dev/null +++ b/docs/modules/ROOT/pages/CHANGELOG.adoc @@ -0,0 +1,149 @@ += OST Wallet SDK Changelog + +== Version 2.4.1 + +=== Feature + +* User can authorize external session by scanning QR-Code. +* User can pass QR-Code payload to perform QR-Code actions without opening Scanner in OstWalletUI. +This functionality is available for `scanQRCodeToAuthorizeSession`, `scanQRCodeToExecuteTransaction`, `scanQRCodeToAuthorizeDevice`. + +== Version 2.4.0 + +=== Feature + +* `getRedeemableSkus` and `getRedeemableSkuDetails` apis added in `OstJsonApi`. + +== Version 2.3.8 + +=== Changes: + +* Reduced recovery key generation time substantially by leveraging on NDK. + +=== Bug Fix: + +* In OstWalletSDK UI workflows progress bar crashes in background. + +== Version 2.3.7 + +=== Bug Fix: + +* Inaccurate error is thrown when application runs out of memory during recover device workflow. + +== Version 2.3.6 + +=== Changes: + +* Added support for custom loader for OstWalletSDK UI workflows. +* OstWalletSDK now uses custom annotations to provide AndroidX compatibility. ++ +=== Bug Fix: +* Rectified OST_PLATFORM_ERROR error message. + +== Version 2.3.5 + +=== Security Enhancements: + +* Use of FLAG_SECURE flag to protect show mnemonices view against screen recording and screen shotting. +* Use of filterTouchesWhenObscured security flag in base view to protects against tapjacking attacks. + +== Version 2.3.4 + +=== Bug Fixes: + +* Device list inconsistency fix in manage devices. +* User entity current device caching fix. +* Converted Toast error message of enter mnemonics view to inline error message + +== Version 2.3.3 + +=== Changes: + +* Proguard usage to remove verbose and debug logs. + +== Version 2.3.2 + +=== Bug Fixes: + +* Fixed a bug where some android phones were not able to provide pin. + +== Version 2.3.1 + +=== Feature: + +* OstWalletUI now supports + ** get add device QR-Code + ** scan QR-Code to authorize device + ** scan QR-Code to execute transaction + ** authorize current device with mnemonics +* Api provided to fetch current device from OstPlatform. +* Now supports getting active sessions from Sdk. + +== Version 2.3.0 + +=== Feature: + +* OstWalletSdk now contains UI. +* UI components can be modified. +* Languages for UI workflow components can be modified. +* OstWalletUI now supports + ** activate user + ** create session + ** get device mnemonics + ** revoke device + ** reset pin + ** initiate device recovery + ** abort device recovery + ** update biometric preference + +== Version 2.2.2 + +=== Bug Fix: + +* Crash fixes in OstWallet + +=== Security Enhancements + +* Trustkit reinitialization check + +== Version 2.2.1 + +=== Bug Fix: + +* Add `No Network Access` error to OstApiError + +=== Security Enhancements + +* Implemented public-key pinning for api.ost.com + +== Version v2.2.0 + +=== Changes: + +* Added Multi Currency Feature which allows developers to specify fiat-currency at runtime while executing a transaction. +* Added OstJsonApi that allows developers to fetch data from Ost Platform. +Please see README.MD for supported Api(s). + +== Version 2.1.0 + +=== Changes: + +* Biometric preferences are now saved in the SDK +* Remove hard-coding of OST as the value token that backs Brand Tokens +* Now supports device access revocation via API + +== Version 2.0.1 + +=== Changes: + +* Added CHANGELOG.md +* Removed OstBaseWorkFlow.loadCurrentDevice method and changed it's usage in OstResetPin +* Removed OstBaseWorkFlow.loadUser method and changed it's usage in OstResetPin +* Removed OstBaseWorkFlow.loadToken method +* Removed OstBaseWorkFlow(String userId, Handler handler, OstWorkFlowCallback callback) constructor +* Removed unused method OstUser.sign() +* Removed OstSdkCrypto class & OstCrypto interface +* Removed utils.KeyGenProcess class & KeyGenProcessTest test-case +* Use a deterministic password along with Mnemonics to generate keys. +Using a deterministic password not only increases security, but also ensures that no two users can accidentally generate the same key +* `USE_SEED_PASSWORD` configuration added to support backwards compatibility with v2.0.0 diff --git a/docs/modules/ROOT/pages/ContentConfig.adoc b/docs/modules/ROOT/pages/ContentConfig.adoc new file mode 100644 index 00000000..a7f8aba4 --- /dev/null +++ b/docs/modules/ROOT/pages/ContentConfig.adoc @@ -0,0 +1,443 @@ += OST Wallet UI Content Config + +App developers can configure the text shown on various views displayed by OstWalletUI. + +To configure the content, the sdk needs to be provided with https://developer.android.com/reference/org/json/JSONObject[`JSON`]. + +The default configuration can be found link:../ostsdk/src/main/assets/ost-content-config.json[here]. + +== Dictionary Data Structure + +Here is the small sample `json` representation of the configuration. + +[source,js] +---- +{ + "activate_user": { + "create_pin": { + "title_label": { + "text": "Activate Your Wallet" + } + } + } +} +---- + +In the above example: + +* The first-level key `activate_user` corresponds to `Activate User` workflow. +* The second-level key `create_pin` corresponds to `Create Pin` view. +* The third-level key `title_label` corresponds to label that displays the title of the view. +* The fourth-level key `text` is corresponds to diplay text to the title label. + +== Supported Workflows + +OstWalletUI supports 8 workflows + +[cols=",^"] +|=== +| Configuration Keys | Workflows + +| activate_user +| Activate User + +| add_session +| Add Session + +| initiate_recovery +| Initialize Recovery + +| abort_recovery +| Abort Device Recovery + +| revoke_device +| Revoke Device + +| biometric_preference +| Update Biometric Preference + +| reset_pin +| Reset a User's PIN + +| view_mnemonics +| Get Mnemonic Phrase + +| show_add_device_qr +| Get current Device QR code + +| add_current_device_with_mnemonics +| Authorize device using mnemonics + +| scan_qr_to_authorize_device +| Authorize device by scanning QR + +| scan_qr_to_execute_transaction +| Execute transaction by scanning QR +|=== + +== Supported Views + +=== Activate User Workflow Views + +|=== +| Configuration Keys | Views + +| create_pin +| Create Pin View where user sets the pin for first time + +| confirm_pin +| Confirm Pin View where user confirms the pin again +|=== + +=== Add Session Views + +|=== +| Configuration Keys | Views + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Initialize Recovery Views + +|=== +| Configuration Keys | Views + +| device_list +| Displays list of authorized devices for user to choose from + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Abort Device Recovery Views + +|=== +| Configuration Keys | Views + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Revoke Device Views + +|=== +| Configuration Keys | Views + +| device_list +| Displays list of authorized devices for user to choose from + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Update Biometric Preferences Views + +|=== +| Configuration Keys | Views + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Reset a User's PIN Views + +|=== +| Configuration Keys | Views + +| get_pin +| Get Pin View where user provides current pin + +| set_new_pin +| View where user sets the new pin + +| confirm_new_pin +| Confirm Pin View where user confirms the new pin again +|=== + +=== Get Mnemonic Phrase Views + +|=== +| Configuration Keys | Views + +| get_pin +| Get Pin View where user provides pin for authentication + +| show_mnemonics +| Displays 12 word mnemonics of device +|=== + +=== Show Add Device QR View + +|=== +| Configuration Keys | Views + +| show_qr +| Displays QR code of device +|=== + +=== Add Current Device With Mnemonics Views + +|=== +| Configuration Keys | Views + +| provide_mnemonics +| Display View to get 12 word mnemonics from user + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Authorize Device Via QR Views + +|=== +| Configuration Keys | Views + +| scan_qr +| View to scan Device QR + +| verify_device +| View which displays Device data to be verified + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +=== Execute Transaction Via QR Views + +|=== +| Configuration Keys | Views + +| scan_qr +| View to scan Transaction QR + +| verify_transaction +| View which displays Transaction data to be verified + +| get_pin +| Get Pin View where user provides pin for authentication +|=== + +== Loader Content View Components + +In every workflow we support three loaders with text configuration: + +* initial_loader
Loader shown before workflow request construct +* loader
Loader shown after workflow request construct +* acknowledge
Loader shown after workflow request acknowledged + +== Supported UI Components in PIN Input Views + +Here, we refer follwing views as 'Pin Input' views: + +* create_pin +* confirm_pin +* get_pin +* set_new_pin +* confirm_new_pin + +The following UI components are supported by PIN Input views. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| title_label +| label + +| lead_label +| label + +| info_label +| label + +| terms_and_condition_label +| label +|=== + +Here is an example of what the PIN Input View looks like: + +image::images/PinViewLabelTypes.png[copy-framework-file] + +=== Adding links to `terms_and_condition_label` + +`terms_and_condition_label` is a special label that supports inline links using `placeholder` within the text. + +Below is a sample configuration to achive the same: + +[source,js] +---- +{ + "activate_user": { + "create_pin": { + "terms_and_condition_label": { + "text": "Please refer our {{t_and_c}} and {{privacy_policy}}" + }, + "placeholders": { + "t_and_c": { + "url": "https://ost.com/terms", + "text": "Terms and Conditions", + "color": "#0076FF" + }, + "privacy_policy": { + "url": "https://ost.com/privacy", + "text": "Privacy Policy", + "color": "#0076FF" + } + } + } + } +} +---- + +==== NOTE + +---- +As of now, `placeholder` is only applicable to `terms_and_condition_label` +and is NOT supported by other labels. +---- + +== Supported UI Components in Device List Views (device_list) + +The following UI components are supported by Device List Views. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| title_label +| label + +| info_label +| label + +| action_button +| button text +|=== + +Here is an example fo what the Device List View looks like: + +image::images/DeviceListLabelTypes.png[copy-framework-file] + +== Supported UI Components in Show Mnemonics Views(show_mnemonics) + +The following UI components are supported by Show Mnemonics Views. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| title_label +| label + +| info_label +| label + +| bottom_label +| label +|=== + +image::images/ViewMnemonicsLabelTypes.png[copy-framework-file] + +== Supported UI Components in Show QR-Code to Authorize Deivce (show_qr) + +The following UI components are supported by Show QR-Code to Authorize Deivce. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| title_label +| label + +| lead_label +| label + +| action_button +| button text +|=== + +image::images/ShowQR.png[copy-framework-file] + +== Supported UI Components in Provide Mnemonics (provide_mnemonics) + +The following UI components are supported by Provide Mnemonics. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| title_label +| label + +| info_label +| label + +| bottom_label +| label + +| action_button +| button text + +| placeholder +| label +|=== + +image::images/ProvideMnemonics.png[copy-framework-file] + +== Supported UI Components in Scan QR (scan_qr) + +The following UI components are supported by Scan QR. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| title_label +| label +|=== + +image::images/ScanQR.png[copy-framework-file] + +== Supported UI Components in Verify Device (verify_device) + +The following UI components are supported by Verify Device. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| lead_label +| label + +| accept_button +| button text + +| reject_button +| button text +|=== + +image::images/VerifyDevice.png[copy-framework-file] + +== Supported UI Components in Verify Transaction (verify_transaction) + +The following UI components are supported by Verify Transaction. + +[cols=",^"] +|=== +| Configuration Keys | Component Type + +| lead_label +| label + +| info_label +| label + +| accept_button +| button text + +| reject_button +| button text +|=== + +image::images/VerifyTX.png[copy-framework-file] diff --git a/docs/modules/ROOT/pages/OstCustomLoader.adoc b/docs/modules/ROOT/pages/OstCustomLoader.adoc new file mode 100644 index 00000000..db277181 --- /dev/null +++ b/docs/modules/ROOT/pages/OstCustomLoader.adoc @@ -0,0 +1,193 @@ += OstWalletUI Custom Loader + +Developer can set application loader instead of OstWalletSdk default loader while using OstWalletUI + +== Setup + +=== Set Loader Manager + +==== Creade Loader Manager Object + +[source,java] +---- +import com.ost.walletsdk.ui.loader.OstLoaderDelegate; + +class LoaderManager implements OstLoaderDelegate { + + private LoaderManager(){ + + } + + @Override + public OstLoaderFragment getLoader(OstWorkflowContext.WORKFLOW_TYPE workflowType) { + //Returns Custom Loader Implemtation which inherits OstLoaderFragment. + } + + @Override + public boolean waitForFinalization(OstWorkflowContext.WORKFLOW_TYPE workflowType) { + // Returns boolean flag, which determine whether loader should be shown till workflow completion. + } +} +---- + +==== Set Loader Manager Object + +Loader manager object could be the plan `java` class. +OstWalletUI holds reference of it. +Caution: + +[source,java] +---- +OstWalletUI.setLoaderManager(new LoaderManager()); +---- + +____ +*Caution* + Implementing OstLoaderDelegate to Activities or fragment may cause memory leak. ++ +____ + +==== Create Application loader Fragment + +Loader Fragment should be subclass of `OstLoaderFragment`. + +* onInitLoader: method gets called when OstWalletUI is processing +* onPostAuthentication: OstWalletUI call this method after user enters pin +* onAcknowledge: method gets called after request is submitted for confirmation +* onSuccess: This method gets called after workflow confirmation +* onFailure: After failure of workflow, sdk calls onFailure + +____ +*Note* + Developer should call `dismissWorkflow` of `OstLoaderCompletionDelegate` to close Loader UI. ++ Not calling delegate `dismissWorkflow` will keep the workflow Acitivty on the screen. +____ + +[source,java] +---- +import com.ost.walletsdk.ui.loader.OstLoaderFragment; +import com.ost.walletsdk.ui.loader.OstWorkflowLoader; +import com.ost.walletsdk.ui.workflow.OstLoaderCompletionDelegate; +import com.ost.walletsdk.workflows.OstContextEntity; +import com.ost.walletsdk.workflows.OstWorkflowContext; +import com.ost.walletsdk.workflows.errors.OstError; + +import org.json.JSONObject; + + +public class AppLoaderFragment extends OstLoaderFragment implements OstWorkflowLoader { + + public static AppLoaderFragment newInstance() { + return new AppLoaderFragment(); + } + + + @Override + public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, + @Nullable Bundle savedInstanceState) { + mViewGroup = (ViewGroup) inflater.inflate(R.layout.fragment_app_loader, container, false); + return mViewGroup; + } + + public void setLoaderString(String loaderString) { + StringConfig stringConfig = StringConfig.instance(contentConfig.optJSONObject("initial_loader")); + mLoaderTextView.setText(stringConfig.getString()); + //Method gets called from SDK to set String for the loader + } + + @Override + public void onInitLoader(JSONObject contentConfig) { + //Method gets called from SDK after workflow launch + StringConfig stringConfig = StringConfig.instance(contentConfig.optJSONObject("loader")); + mLoaderTextView.setText(stringConfig.getString()); + } + + @Override + public void onPostAuthentication(JSONObject contentConfig) { + //Method gets called from SDK after authentication through pin or biometric + StringConfig stringConfig = StringConfig.instance(contentConfig.optJSONObject("acknowledge")); + mLoaderTextView.setText(stringConfig.getString()); + } + + @Override + public void onAcknowledge(JSONObject contentConfig) { + //Method gets called from SDK after request is submitted to the Ost platform successfully + StringConfig stringConfig = StringConfig.instance(contentConfig.optJSONObject("acknowledge")); + mLoaderTextView.setText(stringConfig.getString()); + } + + @Override + public void onSuccess(OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity, JSONObject contentConfig ,final OstLoaderCompletionDelegate delegate) { + //Method get called when the worflow has completed successfully, show success dialog here. + //To close workflow, call delegate method dismissWorkflow + delegate.dismissWorkflow(); + } + + @Override + public void onFailure(OstWorkflowContext ostWorkflowContext, OstError ostError, JSONObject contentConfig, final OstLoaderCompletionDelegate delegate) { + //Method get called when the worflow has failed, show failure dialog here. + //To close workflow, call delegate method dismissWorkflow + delegate.dismissWorkflow(); + } +} +---- + += Custom Loader Usage + +== Setup + +. Application project should have `ost-wallet-sdk-android` dependency. +. Copy `customloader` directory in Application project `src` directory. +. Define `customloader` resources and assets directory in application build.gradle. ++ +---- +android { + sourceSets { + main.java.srcDirs += 'src/customloader/src' + main.assets.srcDirs += 'src/customloader/assets' + main.res.srcDirs += 'src/customloader/res' + } +} +---- + +. Add resource import statements in `GIFView.java` and `OstMockLoaderFragment.java` ++ +---- +import .R +---- + +. Set LoaderManager of Custom loader in your application onCreate method ++ +[source,java] +---- +public class App extends Application { + @Override + public void onCreate() { + super.onCreate(); + /* Add below line in you application onCreate */ + OstWalletUI.setLoaderManager(customloader.src.OstMockLoaderManager.getInstance()); + } +} +---- + +After performing above steps, you are good to go with custom loader. + +== Customize Loader + +You can customize icons and text for custom loader as per application need. + +=== 1. Loader gif: + +To modfiy loader, Add your `.gif` file and rename as `ost_progress_image.gif`. +After that, replace it with `src/customloader/res/drawable/ost_progress_image.gif` + + +=== 2. Success and Failure Icon: + +To modify Icons, open `src/customloader/res/drawable/` and replace `ost_success_icon.png` and `ost_failure_icon` with your application icons. + +=== 3. Modify success message: + +Developer can modify success message by modifying `SUCCESS_MESSAGE` value in `src/customloader/assets/OstSdkMessages.json` file + +=== 4. Modify loader text: + +To modify loader text, update language for key `text` under `initial_loader`, `loader` and `acknowledge` in ost_content_config.json + ost_content_config is a file, which you set for `setContentConfig` function. + diff --git a/docs/modules/ROOT/pages/OstJsonApi.adoc b/docs/modules/ROOT/pages/OstJsonApi.adoc new file mode 100644 index 00000000..ba55b041 --- /dev/null +++ b/docs/modules/ROOT/pages/OstJsonApi.adoc @@ -0,0 +1,817 @@ += OST JSON APIs + +OST JSON APIs are a set of _asynchronous_ methods that make API calls to OST Platform servers. + +== Table of Contents + +* <> +* <> +* <> +* <> +* <> + ** <> + *** <> + *** <> + ** <> + *** <> + *** <> + ** <> + *** <> + *** <> + ** <> + *** <> + *** <> + ** <> + *** <> + *** <> + *** <> + ** <> + *** <> + *** <> +* <> + ** <> + *** <> + *** <> + ** <> + *** <> + *** <> + ** <> + *** <> + *** <> + +++++++++++++ + +== Before We Begin + +* Although it is *NOT RECOMMENDED*, but if your app needs to allow multiple users to login on same device, the app must: + ** ensure to pass the `userId` of the currently *logged-in and authenticated* user. + ** ensure that the user has not logged-out *before* processing/displaying the response. +* App must link:../README.md#vii-initialize-the-wallet-sdk[initialize] the sdk _*before*_ initiating any JSON API. +* App must perform link:../README.md#1-setupdevice[setupDevice] workflow _*before*_ initiating any JSON API. +* All `OstJsonApi` methods expect `userId` as first parameter because all requests need to be signed by the user's API key. +* It's always good to check if the device can make API calls by calling `OstSdk.getCurrentDeviceForUserId` method. + ** Any device with status `REGISTERED`, `AUTHORIZING`, `AUTHORIZED`, `RECOVERING` or `REVOKING` can make this API call. + +++++++++++++ + +== JSON API Types + +The JSON APIs can be categorized into 2 groups. + +* <> - The APIs that get entities (e.g. +current-device, price-point, balance etc.) +* <> - The APIs that get list of entities and support pagination (e.g. +device list, transactions) + +++++++++++++ + +== Importing OstJsonApi + +Use the following code to import `OstSdk` + +---- +import com.ost.walletsdk.OstSdk; +---- + +++++++++++++ + +== Ost Json Api Delegate + +Developer need to pass object of OstJsonApiDelegate to get response. + +[source,java] +---- + class OstJsonApiCallbackImpl implements OstJsonApiCallback { + + @Override + public void onOstJsonApiSuccess(@Nullable JSONObject data) { + //Action on success response + } + + @Override + public void onOstJsonApiError(@Nonnull OstError err, @Nullable JSONObject data) { + //Action on failure response + } + } +---- + +++++++++++++ + +== Entity API + +++++++++++++ + +=== Get Current Device + +API to get user's current device. + +____ +While the equivalent getter method `OstSdk.getCurrentDeviceForUserId` gives the data stored in SDK's database, this method makes an API call to OST Platform. +____ + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get current user device. + * + * @param userId User Id of the current logged-in user. + * @param callback callback where to receive data/error. + */ +OstJsonApi.getCurrentDevice(userId, ostJsonApiCallback); +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "device": { + "updated_timestamp": 1566832473, + "status": "AUTHORIZED", + "api_signer_address": "0x674d0fc0d044f085a87ed742ea778b55e298b429", + "linked_address": "0x0000000000000000000000000000000000000001", + "address": "0x8d92cf567191f07e5c1b487ef422ff684ddf5dd3", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + }, + "result_type": "device" +} +---- + +++++++++++++ + +=== Get Balance + +API to get user's balance. + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get user balance. Balance of only current logged-in user can be fetched. + * + * @param userId User Id of the current logged-in user. + * @param callback callback where to receive data/error. + */ +OstJsonApi.getBalance(userId, ostJsonApiCallback); +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "balance": { + "updated_timestamp": 1566832497, + "unsettled_debit": "0", + "available_balance": "10000000", + "total_balance": "10000000", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + }, + "result_type": "balance" +} +---- + +++++++++++++ + +=== Get Price Point + +API to get price-points of token's staking currency (OST or USDC). + +____ +This API call is generally needed to compute the current fiat value to your brand-tokens. +E.g. +displaying user's balance in fiat. +____ + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get Price Points. + * + * @param userId User Id of the current logged-in user. + * @param callback callback where to receive data/error +*/ +OstJsonApi.getPricePoints(userId, ostJsonApiCallback); +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "price_point": { + "USDC": { + "updated_timestamp": 1566834913, + "decimals": 18, + "GBP": 0.8201717727, + "EUR": 0.9028162679, + "USD": 1.0025110673 + } + }, + "result_type": "price_point" +} +---- + +++++++++++++ + +=== Get Balance And Price Points + +This is a convenience method that makes `OstJsonApi.getBalanceForUserId` and `OstJsonApi.getPricePointForUserId` API calls and merges the response. + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get user balance and Price Points. Balance of only current logged-in user can be fetched. + * + * @param userId User Id of the current logged-in user. + * @param callback callback where to receive data/error. +*/ +OstJsonApi.getBalanceWithPricePoints(userId, ostJsonApiCallback); +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "balance": { + "updated_timestamp": 1566832497, + "unsettled_debit": "0", + "available_balance": "10000000", + "total_balance": "10000000", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + }, + "price_point": { + "USDC": { + "updated_timestamp": 1566834913, + "decimals": 18, + "GBP": 0.8201717727, + "EUR": 0.9028162679, + "USD": 1.0025110673 + } + }, + "result_type": "balance" +} +---- + +++++++++++++ + +=== Get Pending Recovery + +API to get user's pending recovery. +A pending recovery is created when the user recovers the device using their PIN. + +____ +This API will respond with `UNPROCESSABLE_ENTITY` API error code when user does not have any recovery in progress. +____ + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get pending ongoing recovery. + * + * @param userId User Id of the current logged-in user. + * @param callback callback where to receive data/error. +*/ + +OstJsonApi.getPendingRecovery(userId, ostJsonApiCallback); + +/* After receiving error for this api request, check for following: + if ("UNPROCESSABLE_ENTITY".equalIsIgnoreCase(err.internalCode)) { + // There is no pending recovery + } +*/ +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "devices": [ + { + "updated_timestamp": 1566902100, + "status": "REVOKING", + "api_signer_address": "0x903ad1a1017c14b8e6b0bb1dd32d3f65a8741732", + "linked_address": "0x73722b0c0a6b6418893737e0ca33dd567e33f6aa", + "address": "0x629e13063a2aa24e2fb2a49697ef871806071550", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + }, + { + "updated_timestamp": 1566902100, + "status": "RECOVERING", + "api_signer_address": "0x6f5b1b8df95cbc3bd8d18d6c378cef7c34644729", + "linked_address": "null", + "address": "0x33e736a4761bc07ed54b1ceb82e44dfb497f478c", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + } + ], + "result_type": "devices" +} +---- + +++++++++++++ + +.Sample Error + +The `getPendingRecoveryForUserId` API will respond with `UNPROCESSABLE_ENTITY` API error code when user does not have any recovery in progress. + +[source,json] +---- +{ + "api_error": { + "internal_id": "***********", + "error_data": [], + "msg": "Initiate Recovery request for user not found.", + "code": "UNPROCESSABLE_ENTITY" + }, + "is_api_error": 1, + "error_message": "OST Platform Api returned error.", + "internal_error_code": "***********", + "error_code": "API_RESPONSE_ERROR" +} +---- + +++++++++++++ + +=== Get Redeemable Sku Details + +API to get redeemable sku details. + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId and skuId as per your requirements. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; +String skuDetailId = "2"; +JSONObject requestPayload = new JSONObject(); +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get Details of single redeemable sku + * + * @param userId userId of user Logged in + * @param skuId Id of required Sku + * @param requestPayload extra params + * @param callback where to receive data/error. +*/ +OstJsonApi.getRedeemableSkuDetails(userId, skuDetailId, requestPayload, ostJsonApiCallback); +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "result_type":"redemption_product", + "redemption_product":{ + "status":"active", + "images":{ + "detail":{ + "original":{ + "size":90821, + "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-d-original.png", + "width":150, + "height":150 + } + }, + "cover":{ + "original":{ + "size":193141, + "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-c-original.png", + "width":320, + "height":320 + } + } + }, + "availability":[ + { + "country_iso_code":"USA", + "country":"USA", + "currency_iso_code":"USD", + "denominations":[ + { + "amount_in_wei":"49938358", + "amount_in_fiat":5 + }, + { + "amount_in_wei":"99876717", + "amount_in_fiat":10 + }, + ... + ] + }, + { + "country_iso_code":"CAN", + "country":"Canada", + "currency_iso_code":"CAD", + "denominations":[ + { + "amount_in_wei":"37547638", + "amount_in_fiat":5 + }, + { + "amount_in_wei":"75095276", + "amount_in_fiat":10 + }, + ... + ] + }, + { + "country_iso_code":"GBR", + "country":"United Kingdom", + "currency_iso_code":"GBP", + "denominations":[ + { + "amount_in_wei":"64855011", + "amount_in_fiat":5 + }, + { + "amount_in_wei":"129710022", + "amount_in_fiat":10 + }, + ... + ] + }, + { + "country_iso_code":"IND", + "country":"India", + "currency_iso_code":"INR", + "denominations":[ + { + "amount_in_wei":"1396", + "amount_in_fiat":0.01 + }, + { + "amount_in_wei":"139609", + "amount_in_fiat":1 + }, + ... + ] + } + ], + "id":"2", + "updated_timestamp":1582024811, + "description":{ + "text":null + }, + "name":"Starbucks" + } +} +---- + +++++++++++++ + +== List API + +All `List` APIs support pagination. +The response of all `List` APIs has an extra attribute `meta`. +To determine if next page is available, the app should look at `meta["next_page_payload"]`. +If `meta["next_page_payload"]` is an empty object (`{}`), next page is not available. + +++++++++++++ + +=== Get Transactions + +API to get user's transactions. + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; + +JSONObject nextPagePayload = null; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + + /** + * Api to get user transactions. Transactions of only current logged-in user can be fetched. + * + * @param userId User Id of the current logged-in user. + * @param requestPayload request payload. Such as next-page payload, filters etc. + * @param callback callback where to receive data/error. +*/ +OstJsonApi.getTransactions(userId, nextPagePayload, ostJsonApiCallback); + +/* After receiving data for this api request, check for following: + JSONObject dataJSONObject = parseJSONData(responseData); + JSONObject meta = dataJSONObject.optJSONObject("meta"); + if (null != meta) { + nextPagePayload = meta.optJSONObject("next_page_payload"); + } +*/ +---- + +++++++++++++ + +.Sample Response + +Please refer to the https://dev.ost.com/platform/docs/api/#transactions[Transactions Object] for a detailed description. + +[source,json] +---- +{ + "meta": { + "total_no": 14, + "next_page_payload": { + "pagination_identifier": "*****************************************************" + } + }, + "transactions": [ + { + "meta_property": { + "details": "Awesome Post", + "type": "user_to_user", + "name": "Like" + }, + "rule_name": "Direct Transfer", + "block_timestamp": 1566843589, + "block_confirmation": 969, + "transaction_fee": "94234000000000", + "gas_price": "1000000000", + "nonce": 613, + "from": "0x6ecbfdb2ebac8669c85d61dd028e698fd6403589", + "id": "4efa1b45-8890-4978-a5f4-8f9368044852", + "transfers": [ + { + "kind": "transfer", + "amount": "200000", + "to_user_id": "a87fdd7f-4ce5-40e2-917c-d80a8828ba62", + "to": "0xb29d32936280e8f05a5954bf9a60b941864a3442", + "from_user_id": "71c59448-ff77-484c-99d8-abea8a419836", + "from": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9" + } + ], + "block_number": 3581559, + "updated_timestamp": 1566843589, + "status": "SUCCESS", + "gas_used": 94234, + "value": "0", + "to": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9", + "transaction_hash": "0xee8033f9ea7e9bf2d74435f0b6cc172d9378670e513a2b07cd855ef7e41dd2ad" + }, + { + "meta_property": { + "details": "Nice Pic", + "type": "user_to_user", + "name": "Fave" + }, + "rule_name": "Direct Transfer", + "block_timestamp": 1566843547, + "block_confirmation": 983, + "transaction_fee": "109170000000000", + "gas_price": "1000000000", + "nonce": 612, + "from": "0x6ecbfdb2ebac8669c85d61dd028e698fd6403589", + "id": "7980ee91-7cf1-449c-bbaf-5074c2ba6b29", + "transfers": [ + { + "kind": "transfer", + "amount": "1600000", + "to_user_id": "a87fdd7f-4ce5-40e2-917c-d80a8828ba62", + "to": "0xb29d32936280e8f05a5954bf9a60b941864a3442", + "from_user_id": "71c59448-ff77-484c-99d8-abea8a419836", + "from": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9" + } + ], + "block_number": 3581545, + "updated_timestamp": 1566843549, + "status": "SUCCESS", + "gas_used": 109170, + "value": "0", + "to": "0xbf3df93b15c6933177237d9ed8400a2f41c8b8a9", + "transaction_hash": "0x3e3bb3e25ab3a5123d1eaf20e1c31ab88bd56500c5cdfd2e32025c4df32735b3" + }, + ... + ... + ], + "result_type": "transactions" +} +---- + +++++++++++++ + +=== Get Devices + +API to get user's devices. + +++++++++++++ + +.Usage +[source,Swift] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; +JSONObject nextPagePayload = null; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get Device list. Device list of only current logged-in user can be fetched. + * + * @param userId User Id of the current logged-in user. + * @param requestPayload request payload. Such as next-page payload, filters etc. + * @param callback callback where to receive data/error. +*/ +OstJsonApi.getDeviceList(userId, nextPagePayload, ostJsonApiCallback); + +/* After receiving data for this api request, check for following: + JSONObject dataJSONObject = parseJSONData(responseData); + JSONObject meta = dataJSONObject.optJSONObject("meta"); + if (null != meta) { + nextPagePayload = meta.optJSONObject("next_page_payload"); + } +*/ +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "meta": { + "next_page_payload": {} + }, + "devices": [ + { + "updated_timestamp": 1566832473, + "status": "AUTHORIZED", + "api_signer_address": "0x674d0fc0d044f085a87ed742ea778b55e298b429", + "linked_address": "0x73722b0c0a6b6418893737e0ca33dd567e33f6aa", + "address": "0x8d92cf567191f07e5c1b487ef422ff684ddf5dd3", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + }, + { + "updated_timestamp": 1566839512, + "status": "AUTHORIZED", + "api_signer_address": "0x2e12c4f6a27f7bdf8e58e628ec29bb4ce49c315e", + "linked_address": "0x0000000000000000000000000000000000000001", + "address": "0x73722b0c0a6b6418893737e0ca33dd567e33f6aa", + "user_id": "71c59448-ff77-484c-99d8-abea8a419836" + } + ], + "result_type": "devices" +} +---- + +++++++++++++ + +=== Get Redeemable Skus + +API to get redeemable skus. + +++++++++++++ + +.Usage +[source,java] +---- +/* + Please update userId as per your needs. + Since this userId does not belong to your economy, you will get an error if you do not change it. +*/ +String userId = "71c59448-ff77-484c-99d8-abea8a419836"; +JSONObject nextPagePayload = null; + +OstJsonApiCallbackImpl ostJsonApiCallback = new OstJsonApiCallbackImpl(); + +/** + * Api to get redeemable Skus from server + * + * @param userId userId of user Logged in + * @param nextPagePayload { + * paginationId (optional) + * limit (optional) + * ids (optional) + * } + * @param callback where to receive data/error. +*/ +OstJsonApi.getRedeemableSkus(userId, nextPagePayload, ostJsonApiCallback); + +/* After receiving data for this api request, check for following: + JSONObject dataJSONObject = parseJSONData(responseData); + JSONObject meta = dataJSONObject.optJSONObject("meta"); + if (null != meta) { + nextPagePayload = meta.optJSONObject("next_page_payload"); + } +*/ +---- + +++++++++++++ + +.Sample Response +[source,json] +---- +{ + "meta":{ + "next_page_payload":{ + } + }, + "result_type":"redemption_products", + "redemption_products":[ + { + "status":"active", + "updated_timestamp":1582024811, + "id":"2", + "description":{ + "text":null + }, + "images":{ + "detail":{ + "original":{ + "size":90821, + "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-d-original.png", + "width":150, + "height":150 + } + }, + "cover":{ + "original":{ + "size":193141, + "url":"https://dxwfxs8b4lg24.cloudfront.net/ost-platform/rskus/stag-starbucks-c-original.png", + "width":320, + "height":320 + } + } + }, + "name":"Starbucks" + }, + ... + ... + ] +} +---- diff --git a/docs/modules/ROOT/pages/OstWalletUI.adoc b/docs/modules/ROOT/pages/OstWalletUI.adoc new file mode 100644 index 00000000..c4caab91 --- /dev/null +++ b/docs/modules/ROOT/pages/OstWalletUI.adoc @@ -0,0 +1,696 @@ +===UI README=== + += OST Wallet UI Android + +== Introduction + +Wallet UI SDK is useful to integrate OstWalletSdk in application with available UI components. + +== Setup + +To setup OstWalletUI, please refer https://github.com/ostdotcom/ost-wallet-sdk-android#setup[setup]. + +== OstWalletUI SDK APIs + +To use OstWalletUI `import com.ost.walletsdk.ui.*;` + +=== Set Theme Config + +Theme for OstWalletUI can be initialized by calling `setThemeConfig` API, which setup OstWalletUI theme config + +*Parameters* +  __themeConfig: Config to use for UI__ + + +theme-config.json + +[source,json] +---- +{ + "nav_bar_logo_image": { + "asset_name": "nav_bar_logo" + } +} +---- + +Change "nav_bar_logo" with your drawable file name in resource folder, which you want to show in navigation bar. + +[source,java] +---- +JSONObject themeConfig = readFromFile("theme-config.json"); +OstWalletUI.setThemeConfig(themeConfig) +---- + +=== Set Content Config + +Content for OstWalletUI can be initialized by calling `setContentConfig` API, which setup OstWalletUI content config + +*Parameters* +  contentConfig: Config to use for UI_ + + +content-config.json + +[source,json] +---- +{ + "activate_user": { + "create_pin": { + "terms_and_condition_url": "https://ost.com/terms" + }, + "confirm_pin": { + "terms_and_condition_url": "https://ost.com/terms" + } + } +} +---- + +While activating user `create_pin["terms_and_condition_url"]` url is used to show terms and conditions. +Where as while confirming pin `terms_and_condition_url["terms_and_condition_url"]` url is used. + +[source,java] +---- +JSONObject contentConfig = readFromFile("content-config.json"); +OstWalletUI.setThemeConfig(contentConfig) +---- + +=== Activate User + +User activation refers to the deployment of smart-contracts that form the user's Brand Token wallet. +An activated user can engage with a Brand Token economy. ++ + *Parameters* +  __currentActivity: Current Activity instance on which Sdk UI activity to be launched__ +  __userId: OST Platform user id provided by application server__ +  __expireAfterInSec: Session key validat duration__ +  __spendingLimit: Spending limit in a transaction in atto BT__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from perticular workflow id)__ + + +[source,java] +---- +OstWalletUI.activateUser(@NonNull Activity currentActivity, String userId, long expiredAfterSecs, + String spendingLimit, OstUserPassphraseCallback userPassphraseCallback) +---- + +=== Initialize Recovery + +A user can control their Brand Tokens using their authorized devices. +If they lose their authorized device, they can recover access to their BrandTokens by authorizing a new device via the recovery process . + + *Parameters* +  __currentActivity: Current Activity instance on which Sdk UI activity to be launched__ +  __userId: OST Platform user id provided by application server__ +  __recoverDeviceAddress: Device address which wants to recover__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from perticular workflow id)__ + + +If application set `recoverDeviceAddress` then OstWalletUI ask for `pin` to initiate device recovery. +Else it displays authorized device list for given `userId` to select device from. + +[source,java] +---- +OstWalletUI.initiateDeviceRecovery(@NonNull Activity currentActivity, String userId, + @Nullable String recoverDeviceAddress, OstUserPassphraseCallback userPassphraseCallback) +---- + +=== Abort Device Recovery + +To abort initiated device recovery. ++ + *Parameters* +  __currentActivity: Current Activity instance on which Sdk UI activity to be launched__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from perticular workflow id)__ + + +[source,java] +---- +abortDeviceRecovery(@NonNull Activity currentActivity, String userId, + OstUserPassphraseCallback userPassphraseCallback) +---- + +=== Subscribe + +Subscribe to specified event of UI Workflow *Parameters* +  __workflowId: Id of the workflow as returned by methods of OstWalletUI__ +  __listner: Callback implementation object to listen events__ + + +[source,java] +---- +SdkInteract.getInstance().subscribe(String workflowId, SdkInteractListener listener) +---- + +=== Unsubscribe + +Unsubscribes the listner from the specified event of UI Workflow. +*Parameters* +  __workflowId: Id of the workflow as returned by methods of OstWalletUI__ +  __listner: Callback implementation object to remove from listing events__ + + +[source,java] +---- +SdkInteract.getInstance().unSubscribe(String workflowId, SdkInteractListener listener) +---- + +== Workflow Callbacks + +=== OstUserPassphraseCallback + +[source,java] +---- +/** Get passphrase prefix from application + * + * - Parameters: + * - userId: Ost user id + * - ostWorkflowContext: Workflow context + * - ostPassphraseAcceptor: Passphrase prefix accept callback + */ +void getPassphrase(String userId, OstWorkflowContext ostWorkflowContext, OstPassphraseAcceptor ostPassphraseAcceptor) +---- + +=== SdkInteractListener + +[source,java] +---- +/** Acknowledge user about the request which is going to make by SDK. + * + * - Parameters: + * - workflowId: Workflow id + * - ostWorkflowContext: A context that describes the workflow for which the callback was triggered. + * - ostContextEntity: Context Entity + */ +void requestAcknowledged(String workflowId, OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity); +---- + +[source,java] +---- +/** Inform SDK user the the flow is complete. + * + * - Parameters: + * - workflowId: Workflow id + * - ostWorkflowContext: A context that describes the workflow for which the callback was triggered. + * - ostContextEntity: Context Entity + */ +void flowComplete(String workflowId, OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity); +---- + +[source,java] +---- + /** Inform SDK user that flow is interrupted with errorCode. + * Developers should dismiss pin dialog (if open) on this callback. + * + * - Parameters: + * - workflowId: Workflow id + * - workflowContext: A context that describes the workflow for which the callback was triggered. + * - ostError: Error Entity + */ +void flowInterrupt(String workflowId, OstWorkflowContext ostWorkflowContext, OstError ostError); +---- + + +===OstWalletUI=== + + +--- + += OST Wallet UI Android + +== Introduction + +For quick and easy integration with SDK, developers can use built-in User Interface Components which are themeable and support content customization. + +== Setup + +To setup OstWalletUI, please refer link:../README.md#setup[setup]. + +== OstWalletUI SDK APIs + +=== Important Notes + +. App must link:../README.md#initialize-the-sdk[initialize] the sdk _*before*_ initiating any UI workflows. +. App must perform link:../README.md#set-up-the-device[setupDevice] workflow _*before*_ initiating any UI workflows. + +To use OstWalletUI + +[source,java] +---- +import com.ost.walletsdk.ui.OstWalletUI; +---- + +=== Set Theme Config + +Theme for OstWalletUI can be initialized by calling `setThemeConfig` API. +To define custom theme config, please refer xref:./ThemeConfig.adoc[ThemeConfig] documentation. + +*Parameters* +  __config: Config to use for UI__ + + +* Create config file by title `theme-config.json` in assets directory + +[source,java] +---- +try { + InputStream configInputStream = context.getAssets().open("theme-config.json"); + int size = configInputStream.available(); + byte[] buffer = new byte[size]; + + configInputStream.read(buffer); + configInputStream.close(); + + String json = new String(buffer, "UTF-8"); + JSONObject themeConfig = new JSONObject(json); + + } catch (Exception e) { + //Error handling + } +---- + +[source,java] +---- +OstWalletUI.setThemeConfig(themeConfig) +---- + +=== Get Theme Config + +Get currently applied theme config from sdk. + +[source,java] +---- +OstWalletUI.getThemeConfig() +---- + +=== Set Content Config + +Content for OstWalletUI can be initialized by calling `setContentConfig` API. +To define custom content config, please refer xref:./ContentConfig.adoc[ContentConfig] documentation. + +*Parameters* +  __config: Config to use for UI__ + + +* Create config file by title `content-config.json` in assets directory For detailed explaination of how to build Content Config. +xref:ContentConfig.adoc[Ref] + +[source,java] +---- +try { + InputStream configInputStream = context.getAssets().open("content-config.json"); + int size = configInputStream.available(); + byte[] buffer = new byte[size]; + + configInputStream.read(buffer); + configInputStream.close(); + + String json = new String(buffer, "UTF-8"); + JSONObject themeConfig = new JSONObject(json); + + } catch (Exception e) { + //Error handling + } +---- + +[source,java] +---- +OstWalletUI.setContentConfig(contentConfig) +---- + +=== Set Loader Manager + +Application loader for OstWalletUI can be initialized by calling `setLoaderManager` API. ++ To setup application loader, please refer xref:./OstCustomLoader.adoc[CustomLoader] documentation. + +*Parameters* +  __loaderManager: class which inherits `OstLoaderFragment` protocol__ + + +[source,java] +---- +OstWalletUI.setLoaderManager(loaderManager) +---- + +=== Activate User + +User activation refers to the deployment of smart-contracts that form the user's Brand Token wallet. +An activated user can engage with a Brand Token economy. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __expireAfterInSec: Session key valid duration__ +  __spendingLimit: Spending limit in a transaction in atto BT__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.activateUser(@NonNull Activity currentActivity, + String userId, + long expiredAfterSecs, + String spendingLimit, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Authorize session + +A session is a period of time during which a sessionKey is authorized to sign transactions under a pre-set limit on behalf of the user. +The device manager, which controls the tokens, authorizes sessions. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __expireAfterInSec: Session key validat duration__ +  __spendingLimit: Spending limit in a transaction in atto BT__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.createSession(@NonNull Activity currentActivity, + String userId, + long expireAfterInSec, + String spendingLimit, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Get Mnemonic Phrase + +The mnemonic phrase represents a human-readable way to authorize a new device. +This phrase is 12 words long. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.getDeviceMnemonics(@NonNull Activity currentActivity, + String userId, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Reset a User's PIN + +The user's PIN is set when activating the user. +This method supports re-setting a PIN and re-creating the recoveryOwner as part of that. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.resetPin(@NonNull Activity currentActivity, + String userId, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Initialize Recovery + +A user can control their Brand Tokens using their authorized devices. +If they lose their authorized device, they can recover access to their BrandTokens by authorizing a new device via the recovery process. +To use built-in device list UI, pass `recoverDeviceAddress` as `null`. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __recoverDeviceAddress: Device address which wants to recover. +When null is passed, the user is asked to choose a device.__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +If application set `recoverDeviceAddress` then OstWalletUI ask for `pin` to initiate device recovery. +Else it displays authorized device list for given `userId` to select device from. + +[source,java] +---- +OstWalletUI.initiateDeviceRecovery(@NonNull Activity currentActivity, + String userId, + @Nullable String recoverDeviceAddress, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Abort Device Recovery + +To abort initiated device recovery. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.abortDeviceRecovery(@NonNull Activity currentActivity, + String userId, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Revoke Device + +To revoke device access. +To use built-in device list UI, pass `revokeDeviceAddress` as `null`. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __revokeDeviceAddress: Device address to revoke. +When null is passed, the user is asked to choose a device.__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +If application set `revokeDeviceAddress` then OstWalletUI ask for `pin` to revoke device. +Else it displays authorized device list for given `userId` to select device from. + +[source,java] +---- +OstWalletUI.revokeDevice(@NonNull Activity currentActivity, + String userId, + @Nullable String revokeDeviceAddress, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Update Biometric Preference + +This method can be used to enable or disable the biometric. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __enable: Preference to use biometric__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.updateBiometricPreference(@NonNull Activity currentActivity, + String userId, + boolean enable, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Authorize Current Device With Mnemonics + +This workflow should be used to add a new device using 12 words recovery phrase. + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.authorizeCurrentDeviceWithMnemonics(@NonNull Activity currentActivity, + String userId, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Get Add Device QR Code + +This workflow shows QR Code to scan from another authorized device + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __userId: OST Platform user id provided by application server__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.getAddDeviceQRCode(@NonNull Activity currentActivity, + String userId, + ) -> String +---- + +=== Scan QR Code To Authorize Device + +This workflow can be used to authorize device by scanning QR Code. + +____ +The device to be authorized must be a `REGISTERED` device and must be associated with the same user. +To display the QR code on registered device, application can use `OstWalletUI.getAddDeviceQRCode` workflow. +____ + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __qrPayload: Payload same as QR payload, Passing this value will skip QR-code scanner.__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.scanQRCodeToAuthorizeDevice(@NonNull Activity currentActivity, + String qrPayload, + String userId, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Scan QR Code To Execute Transaction + +This workflow can be used to execute transaction by scanning transaction QR Code. + +QR Code Sample: + +[source,json] +---- +{ + "dd":"TX", + "ddv":"1.1.0", + "d":{ + "rn":"direct transfer", + "ads":[ + "0x7701af46018fc57c443b63e839eb24872755a2f8", + "0xed09dc167a72d939ecf3d3854ad0978fb13a8fe9" + ], + "ams":[ + "1000000000000000000", + "1000000000000000000" + ], + "tid": 1140, + "o":{ + "cs":"USD", + "s": "$" + } + }, + "m":{ + "tn":"comment", + "tt":"user_to_user", + "td":"Thanks for comment" + } +} +---- + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __qrPayload: Payload same as QR payload, Passing this value will skip QR-code scanner.__ +  __userId: OST Platform user id provided by application server__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.scanQRCodeToExecuteTransaction(@NonNull Activity currentActivity, + String qrPayload, + String userId, + ) -> String +---- + +=== Scan QR Code To Authorize Session + +This workflow can be used to authorize Session by scanning QR Code. + +QR-Code Sample: + +---- +as|2.0.0|2a421359d02132e8161cda9518aeaa62647b648e|5369b4d7e0e53e1159d6379b989a8429a7b2dd59|1|1583308559|4d40c46a7302974134a67ce77bdfae0e1f78ee518e87b6cda861ffc5847dfaca11a653651c6cdfadf0224574f6f07e1a78aabacdfed66d8c78e1fb2c9bc750161c +---- + +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ +  __qrPayload: Payload same as QR payload, Passing this value will skip QR-code scanner.__ +  __userId: OST Platform user id provided by application server__ +  __userPassphraseCallback: Callback implementation object to get passphrase prefix from application__ + + + __Returns: Workflow Id(use to subscribe object to listen callbacks from particular workflow id)__ + + +[source,java] +---- +OstWalletUI.scanQRCodeToAuthorizeSession(@NonNull Activity currentActivity, + String qrPayload, + String userId, + OstUserPassphraseCallback userPassphraseCallback + ) -> String +---- + +=== Subscribe + +Subscribe to specified event of UI Workflow *Parameters* +  __workflowId: Id of the workflow as returned by methods of OstWalletUI__ +  __listner: Callback implementation object to listen events__ + + +[source,java] +---- +OstWalletUI.subscribe(String workflowId, + OstWalletUIListener listener) +---- + +=== Unsubscribe + +Unsubscribes the listner from the specified event of UI Workflow. +*Parameters* +  __workflowId: Id of the workflow as returned by methods of OstWalletUI__ +  __listner: Callback implementation object to remove from listing events__ + + +[source,java] +---- +OstWalletUI.unsubscribe(String workflowId, + OstWalletUIListener listener) +---- + +=== View Component Sheet + +Component sheet is collection of all components present in OstWalletUI. +Developers can verify how components are going to look with provied theme. +*Parameters* +  __currentActivity: Context of current activity of the application from which workflow will initiate__ + + +[source,java] +---- +OstWalletUI.showComponentSheet(@NonNull Activity currentActivity) +---- + +== UI Workflow Delegates + +=== OstUserPassphraseCallback + +[source,java] +---- + /** + * Get passphrase prefix from application + * @param userId Ost user id + * @param ostWorkflowContext Workflow context + * @param ostPassphraseAcceptor Passphrase prefix accept callback + */ + void getPassphrase(String userId, + OstWorkflowContext ostWorkflowContext, + OstPassphraseAcceptor ostPassphraseAcceptor) + + /** + * To get workflowId call workflowContext.getWorkflowId() method. + * To identify the workflow type, use workflowContext.getWorkflowType() property. + */ +---- + +=== OstWalletUIListener + +This is a markup interface and does not define any methods. +The the interfaces defined below are extended from this interface. + +=== Request Acknowledged Listener + +Implement `RequestAcknowledgedListener` interface to get request acknowlege updates of UI workflow. + +[source,java] +---- + /** + * Acknowledge user about the request which is going to make by SDK. + * @param ostWorkflowContext A context that describes the workflow for which the callback was triggered with workflow id. + * @param ostContextEntity Context Entity + */ + void requestAcknowledged(OstWorkflowContext ostWorkflowContext, + OstContextEntity ostContextEntity) + + /** + * To get workflowId call workflowContext.getWorkflowId() method. + * To identify the workflow type, use workflowContext.getWorkflowType() property. + */ +---- + +=== Flow Complete Listener + +Implement `FlowCompleteListener` interface to get flow complete update of UI workflow + +[source,java] +---- + /** + * Inform SDK user that the flow is complete. + * @param ostWorkflowContext A context that describes the workflow for which the callback was triggered with workflow id. + * @param ostContextEntity Context Entity + */ + void flowComplete(OstWorkflowContext ostWorkflowContext, + OstContextEntity ostContextEntity); + + /** + * To get workflowId call workflowContext.getWorkflowId() method. + * To identify the workflow type, use workflowContext.getWorkflowType() property. + */ +---- + +=== Flow Interrupt Listener + +Implement `FlowInterruptListener` interface to get flow interrupt update of UI workflow + +[source,java] +---- + /** + * Inform SDK user that flow is interrupted with errorCode. + * @param ostWorkflowContext A context that describes the workflow for which the callback was triggered with workflow id. + * @param ostError Error Entity + */ + void flowInterrupt(OstWorkflowContext ostWorkflowContext, + OstError ostError); + + /** + * To get workflowId call workflowContext.getWorkflowId() method. + * To identify the workflow type, use workflowContext.getWorkflowType() property. + */ +---- \ No newline at end of file diff --git a/docs/modules/ROOT/pages/ThemeConfig.adoc b/docs/modules/ROOT/pages/ThemeConfig.adoc new file mode 100644 index 00000000..de9fe26f --- /dev/null +++ b/docs/modules/ROOT/pages/ThemeConfig.adoc @@ -0,0 +1,299 @@ += OST Wallet UI Theme Config + +App developers can configure the UI Components available in OstWalletUI. + +To configure the content, the sdk needs to be provided with https://developer.android.com/reference/org/json/JSONObject[`JSON`] + +The default configuration can be found link:../ostsdk/src/main/assets/ost-theme-config.json[here]. + +To support custom font for application, please add your font in ++++++/src/main/assets directory++++++ + +== Dictionary Data Structure + +Here is the small sample `json` representation of the configuration. + +[source,js] +---- +{ + "h1": { + "size": 20 + } +} +---- + +In the above example: + +* The first-level key `h1` corresponds to H1 Component. +* The second-level key `size` is corresponds to size of H1 label. + +____ +*important* + +. Application navigation bar logo image should be added in `assets` folder for iOS/android. +. Value for `+nav_bar_logo_image -> asset_name+` should be updated with _asset_name_ else OST placehoder image will be applied. +. Incase of missing properties, default values will be applied to respective components. +____ + +== Supported Components + +=== Label + +Here, we refer follwing components as 'Label': + +* H1 +* H2 +* H3 +* H4 +* C1 +* C2 + +The following UI components properties supported by label: + +[cols=",^"] +|=== +| Configuration Keys | Type + +| size +| number + +| font +| string + +| color +| hex value(String) + +| alignment +| string + +| system_font_weight +| string +|=== + +Supported Values for _alignment_ are: + +* left +* right +* center + +Supported Values for _system_font_weight_ are: + +* bold +* regular +* medium +* semi_bold + +=== Button + +Here, we refer follwing components as 'Button': + +* B1 +* B2 +* B3 +* B4 + +The following UI components properties supported by button: + +[cols=",^"] +|=== +| Configuration Keys | Type + +| size +| number + +| font +| string + +| color +| hex value(String) + +| background_color +| hex value(String) + +| system_font_weight +| string +|=== + +=== EditText + +The following UI component properties supported by EditText: + +[cols=",^"] +|=== +| Configuration Keys | Type + +| size +| number + +| color +| hex value(String) + +| background_color +| hex value(String) + +| system_font_weight +| string + +| placeholder +| JSON Object +|=== + +The following are the placeholder properties + +[cols=",^"] +|=== +| Configuration Keys | Type + +| size +| number + +| color +| hex value(String) + +| system_font_weight +| string +|=== + +=== Custom Fonts + +To support custom fonts in ThemeConfig json, Add object with key *fonts* having mapping of font with font relative path from asset directory. +To use custom font in component, add components with _font_ key with value pointing to custom font mapping object. +Refer below example + +[source,js] +---- +{ + "h1": { + size: 12, + font: "Lato-Bold" + }, + "fonts": { + "Lato-Bold": "font/Lato-Bold.ttf" + } +} +---- + +=== Navigation Bar + +The following UI components properties supported by navigation bar: + +[cols=",^"] +|=== +| Configurable component | Value to Modify + +| bar logo +| nav_bar_logo_image.asset_name + +| bar tint color +| navigation_bar.tint_color + +| bar title color +| navigation_bar_header.tint_color + +| close icon tint color +| icons.close.tint_color + +| back icon tint color +| icons.back.tint_color + +| back icon source +| icons.back.source +|=== + +=== Pin Input(pin_input) + +The following UI components properties supported by pin component: + +[cols=",^"] +|=== +| Configuration Keys | Type + +| empty_color +| hex value(String) + +| filled_color +| hex value(String) +|=== + +=== Cell Separator + +The following UI components properties supported by cell separator: + +|=== +| Configuration Keys | Type + +| color +| hex value(String) +|=== + +### Link + +The following UI components properties supported by link: + +|=== +| Configuration Keys | Type + +| size +| number + +| color +| hex value(String) + +| system_font_weight +| string + +| alignment +| string +|=== + +### status + +The following UI components properties supported by status: + +|=== +| Configuration Keys | Type + +| size +| number + +| color +| hex value(String) + +| system_font_weight +| string + +| alignment +| string +|=== + +### form_field + +The following UI components properties supported by status: + +|=== +| Configuration Keys | Type + +| size +| number + +| color +| hex value(String) + +| system_font_weight +| string + +| border_color +| hex value(String) + +| alignment +| string +|=== + +== UI Components + +image::images/NavBar.png[copy-framework-file] + +image::images/PinView.png[copy-framework-file] + +image::images/Card.png[copy-framework-file] + +image::images/TextField.png[copy-framework-file] diff --git a/docs/modules/ROOT/pages/TrustKitPublickeyPinning.adoc b/docs/modules/ROOT/pages/TrustKitPublickeyPinning.adoc new file mode 100644 index 00000000..44b965eb --- /dev/null +++ b/docs/modules/ROOT/pages/TrustKitPublickeyPinning.adoc @@ -0,0 +1,87 @@ += Public Key Pinning Using TrustKit + +OstSdk uses https://github.com/datatheorem/TrustKit-Android/tree/1.1.2[TrustKit v1.1.2] for public key pinning. +If your application also uses `TrustKit`, the application may crash. +This happens because ` TrustKit.initializeWithNetworkSecurityConfiguration` can be called only once during the application life-cycle. +Please read through this document so that both application and sdk can use TrustKit. +
+ +== Setup TrustKit + +Define your application's `network_security_config` file. + +____ +Do not use `ost_network_security_config` as file name. +Please use a different name. +____ + +== Add `api.ost.com` domain-config to `network_security_config` + +[source,xml] +---- + + + + + + + + + + api.ost.com + + s4vrk6by0cqKQ9p/mFOakoi0daivc7Le8q7fUuuo4/U= + MvVeCJ2tAuJZmbqoXMqSNP2mKh+VjGiljvqWytjzasU= + J+0IGhy08mkHR1Z1WbdrHEdHhXRohrdLHUYORlWGafA= + aF+lKYb0WChlCTx5uPBw5ZWze/98vAXSzBBIrVSZWJE= + efgWbb0q/zHFLub1SY5QpoQVlZp33QpLOj0EmhoK8tI= + + + + + +---- + +== Add the `networkSecurityConfig` to the application's `Manifest` file + +To resolve networkSecurityConfig error
+ +[source,java] +---- +java.lang.RuntimeException: Manifest merger failed : Attribute application@networkSecurityConfig value=(@xml/network_security_config) from AndroidManifest.xml:25:9-69 + is also present at [:ostsdk] AndroidManifest.xml:26:18-82 value=(@xml/ost_network_security_config). + Suggestion: add 'tools:replace="android:networkSecurityConfig"' to element at AndroidManifest.xml:17:5-55:19 to override. +---- + +App must add `tools:replace="android:networkSecurityConfig"` in mainfest: + +---- + + + + ... + + +---- + +== Initialize TrustKit before OST Wallet SDK + +[source,java] +---- +@Override +protected void onCreate(Bundle savedInstanceState) { + super.OnCreate(savedInstanceState); + + // Using the default path - res/xml/network_security_config.xml + TrustKit.initializeWithNetworkSecurityConfiguration(this); + + // OR using a resource (TrustKit can't be initialized twice) + TrustKit.initializeWithNetworkSecurityConfiguration(this, R.xml.network_security_config); + + // String BASE_URL = + // Initalize OstSdk + OstWalletUI.initialize(getApplicationContext(), BASE_URL); +} +---- diff --git a/docs/modules/ROOT/pages/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc new file mode 100644 index 00000000..e69de29b diff --git a/docs/modules/ROOT/pages/_partials/.gitkeep b/docs/modules/ROOT/pages/_partials/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..01e12fab --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,1490 @@ +===dev.ost.com Overview=== + += Android SDK Setup +:id: android +:sidebar_label: Android + +Please refer to our GitHub documentation for detailed information. +The following page gives an overview of how to get started with the Android Wallet SDK. + +== GitHub Links + +* https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/README.md[GitHub Readme] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/README.md#ost-sdk-methods[SDK Methods] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/README.md#workflows[SDK Workflows] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/README.md#getters[SDK Getters] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/README.md#ostworkflowcallback-interface[SDK Workflow Callback Interface] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/README.md#classes[SDK Classes] +* https://github.com/ostdotcom/ost-wallet-sdk-android/tree/develop/documentation[Additional GitHub documentation] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/documentation/OstJsonApi.md[OST JSON API] + ** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/documentation/OstWalletUI.md[OST Wallet UI (User Interface Components)] + *** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/documentation/ContentConfig.md[Content Config] + *** https://github.com/ostdotcom/ost-wallet-sdk-android/blob/develop/documentation/ThemeConfig.md[Theming: Theme Config] + +== 1. Interfaces and workflows + +Android Wallet SDK consists of an `interface` and `workflows`. + +=== *Interface* + +*Callback functions are used for communication between app and Wallet SDK* In Android Wallet SDK these callback functions are provided as an interface + +=== *Workflows* + +Workflows are functions that can be used to perform wallet related tasks. +App developers will call these functions to execute different tasks. + +=== Prerequisite + +Install and complete integration with one of our Server Side SDKs + +* link:/platform/docs/sdk/server-side-sdks/php/[PHP] +* link:/platform/docs/sdk/server-side-sdks/ruby/[Ruby] +* link:/platform/docs/sdk/server-side-sdks/nodejs/[Node.js] +* link:/platform/docs/sdk/server-side-sdks/java/[Java] + +== 2. Requirements + +[cols=",>"] +|=== +| Item | Supported Version + +| Android API +| 22 and above + +| Java Compile +| 1.7 +|=== + +:::warning Android Apps that support Android API versions 21 and below OST Wallet SDK cannot work in Android Apps with version 21 and below, the minimum Android API version it can work with is 22 (Android Lolipop). + +If your Android App supports minimum Android API version lower than Lolilop (Android API 22), the Wallet SDK will break for users running Android API versions lower than Lolipop (Android API 22). +::: + +:::note Android API versions 21 and below To use the SDK with an application that supports Android API below 22, please follow the steps below ::: + +. By default, when importing a library with a `minSdkVersion` value that's higher than the main manifest file, an error occurs and the library cannot be imported. +To make the merger tool ignore this conflict and import the library while keeping your App's lower `minSdkVersion` value, add the `overrideLibrary` attribute to the `` tag. + +[source,xml] +---- + + ... + ... + ... + + +---- + +. Use conditional initialization for Andriod API version 22 and above. + +[source,java] +---- +public static final String OST_PLATFORM_API_BASE_URL = "https://api.ost.com/testnet/v2"; + +if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) { + OstSdk.initialize(getApplicationContext(), OST_PLATFORM_API_BASE_URL); + } +---- + +== 3. Install Android Wallet SDK + +=== i) Update build.gradle files + +==== a). Setting minSdkVersion to 22 + +---- +android { + defaultConfig { + minSdkVersion 22 + ... + ... + ... + } +} +---- + +==== b). Adding compile options + +Add following code in your `build.gradle` file + +---- +compileOptions { + sourceCompatibility JavaVersion.VERSION_1_8 + targetCompatibility JavaVersion.VERSION_1_8 + } +---- + +==== c). Adding android wallet sdk package in dependencies + +---- +dependencies { + implementation 'com.ost:ost-wallet-sdk-android:2.1.0' + ... + ... + ... +} +---- + +=== Create config file named `ost-mobilesdk.json` file in `app/src/main/assets/` path of your android project. + +Paste following contents in `app/src/main/assets/ost-mobilesdk.json` file + +[source,json] +---- + { + "BLOCK_GENERATION_TIME": 3, + "PIN_MAX_RETRY_COUNT": 3, + "REQUEST_TIMEOUT_DURATION": 60, + "SESSION_BUFFER_TIME": 3600, + "PRICE_POINT_TOKEN_SYMBOL": "OST", + "PRICE_POINT_CURRENCY_SYMBOL": "USD", + "USE_SEED_PASSWORD": false + } +---- + +|=== +| Attribute | Description + +| BLOCK_GENERATION_TIME +| The time in seconds it takes to mine a block on auxiliary chain. + +| PIN_MAX_RETRY_COUNT +| Maximum retry count to get the wallet Pin from user. + +| REQUEST_TIMEOUT_DURATION +| Request timeout in seconds for https calls made by ostWalletSdk. + +| SESSION_BUFFER_TIME +| Buffer expiration time for session keys in seconds. + +| PRICE_POINT_TOKEN_SYMBOL +| This is the symbol of base currency. +So its value will be OST. + +| PRICE_POINT_CURRENCY_SYMBOL +| It is the symbol of quote currency used in price conversion. + +| USE_SEED_PASSWORD +| Uses mnemonics and password to generate seed. +|=== + +:::warning These configurations are MANDATORY for successful operation. +Failing to set them will significantly impact usage. +::: + +== 4. Initialize the Wallet SDK + +SDK initialization should happen before calling any other `workflow`. +To initialize the SDK, we need to call `initialize` method of Wallet SDK. + +*Recommended location to call init() is in Application sub-class.* + +---- +import android.app.Application; + +import com.ost.mobilesdk.OstWalletSdk; + +public class App extends Application { + + public static final String OST_PLATFORM_API_BASE_URL = "https://api.ost.com/testnet/v2"; + @Override + public void onCreate() { + super.onCreate(); + + OstWalletSdk.initialize(getApplicationContext(), OST_PLATFORM_API_BASE_URL); + } + +} +---- + +== 5. Setting up communication between app and Wallet SDK + +Wallet SDK provides `workflows` that can be called by any Android activity class or fragment class to perform wallet related actions. + +Communication between app and Wallet SDK happens through callback functions. +We need to pass these callback functions in `workflows` provided by SDK. +The group of callback functions for communication between app and Wallet SDK is provided in `OstWorkFlowCallback` interface. + +image::/platform/docs/sdk/assets/wallet-sdk-communication.png[walletSDKCommunication] + +{blank} + + +=== a). Implementing the `OstWorkFlowCallback` interface + +There are different ways to pass these callback functions in workflows. +We will create a `BaseFragment` for reusability purpose which will implement `OstWorkFlowCallback` interface. + +The Wallet SDK ++++++does not hold strong reference of workflow callbacks.++++++ It only has a ++++++weak reference of workflow callback.++++++ This is done to avoid any memory leaks. +The app should hold the reference of the callbacks as long as it needs. + +[source,java] +---- + +public class BaseFragment extends Fragment, OstWorkFlowCallback { + + @Override + public void flowComplete( + OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity) { + String workflowType = ostWorkflowContext.getWorkflow_type(); + String entity = ostContextEntity.getEntityType() + String completeString = String.format("Workflow %s complete entity %s ", workflowType, entity); + + Toast.makeText(OstWalletSdk.getContext(), "Work Flow Successful", Toast.LENGTH_SHORT).show(); + + } + + @Override + public void flowInterrupt( + OstWorkflowContext ostWorkflowContext, + OstError ostError) { + + String workflowType = ostWorkflowContext.getWorkflow_type(); + String errorMessage = ostError.getMessage(); + + String errorString = String.format("Work Flow %s Error: %s", workflowType, errorMessage); + + Toast.makeText(OstWalletSdk.getContext(), errorString, Toast.LENGTH_SHORT).show(); + + } + +// More callback functions definitions here +.... +.... + +} +---- + +=== b). Creating new fragment + +You can now create new fragment that will inherit `BaseFragment` and override definition of *callback functions*. +This new fragment can now call workflow function to perform any wallet related task. + +== OST Wallet App + +To provide developers with sample integration of Wallet SDK, https://github.com/ostdotcom/ost-wallet-sdk-android/tree/develop/ostwallet[OST Wallet Android app] is available on GitHub. + +== Next Steps + +. link:/platform/docs/guides/create-user-wallet/[Create Wallet Guide] +. link:/platform/docs/guides/execute-transactions/[Execute Transaction Guide] +. Android Wallet SDK link:/platform/docs/sdk/mobile-wallet-sdks/android/latest/methods/[Methods], link:/platform/docs/sdk/mobile-wallet-sdks/android/latest/interfaces/[Interfaces] and link:/platform/docs/sdk/mobile-wallet-sdks/android/latest/classes/[Classes] + +===GitHub Readme=== + += OST Wallet SDK Android + +== Introduction + +OST Android Wallet SDK is a mobile application development SDK that enables developers to integrate the functionality of a non-custodial crypto-wallet into consumer applications. + +OST Android Wallet SDK... + +* Safely generates and stores keys on the user's mobile device +* Signs data as defined by contracts using EIP-1077 and EIP-712 +* Enables users to recover access to their Brand Tokens in case the user loses their authorized device + +== Support + +* Java Compile version: 1.7 +* Android version support: 22 and above + +== Table of Contents + +* <> + ** <> + ** <> + ** <> + ** <> + ** <> +* <> + ** <> +* <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> +* <> + ** <> + ** <> + ** <> + ** <> + ** <> + ** <> +* <> + ** <> + ** <> + ** <> + ** <> + ** <> +* <> + ** <> + ** <> +* <> + ** <> + ** <> + *** <> + *** <> + *** <> + *** <> + *** <> + *** <> + *** <> + *** <> +* <> + ** <> + ** <> + ** <> + ** <> +* <> + ** <> + *** <> + ** <> + *** <> + ** <> + *** <> +* <> +* <> +* <> + +== Setup + +[discrete] +==== a). Setting minSdkVersion to 22 + +---- + +android { + defaultConfig { + minSdkVersion 22 + ... + ... + ... + } + +} +---- + +[discrete] +==== b). Adding compile options + +Add following code in your `build.gradle` file + +---- +compileOptions { + sourceCompatibility JavaVersion.VERSION_1_8 + targetCompatibility JavaVersion.VERSION_1_8 + } +---- + +[discrete] +==== c). Adding Android Wallet SDK package in dependencies + +---- +dependencies { + implementation 'com.ost:ost-wallet-sdk-android:2.4.1' + ... + ... + ... +} +---- + +Then sync your dependencies through gradle + *Note*: Gradle sync might fail for the first time due to build time. +Please retry if this happens. + +=== Add mobile SDK config file + +A config file is needed for application-specific configuration of OST SDK.
+ +* Create file "ost-mobilesdk.json" with application specific configurations using the JSON below as an example + +[source,json] +---- + { + "BLOCK_GENERATION_TIME": 3, + "PIN_MAX_RETRY_COUNT": 3, + "REQUEST_TIMEOUT_DURATION": 60, + "SESSION_BUFFER_TIME": 3600, + "PRICE_POINT_CURRENCY_SYMBOL": "USD", + "PRICE_POINT_TOKEN_SYMBOL": "OST", + "USE_SEED_PASSWORD": false, + "NO_OF_SESSIONS_ON_ACTIVATE_USER": 1 + } +---- + +. BLOCK_GENERATION_TIME: The time in seconds it takes to mine a block on auxiliary chain. +. PRICE_POINT_CURRENCY_SYMBOL: It is the symbol of quote currency used in price conversion. +. REQUEST_TIMEOUT_DURATION: Request timeout in seconds for https calls made by ostWalletSdk. +. PIN_MAX_RETRY_COUNT: Maximum retry count to get the wallet Pin from user. +. SESSION_BUFFER_TIME: Buffer expiration time for session keys in seconds. +Default value is 3600 seconds. +. USE_SEED_PASSWORD: The seed password is salt to PBKDF2 used to generate seed from the mnemonic. +When `UseSeedPassword` set to true, different deterministic salts are used for different keys. +. PRICE_POINT_TOKEN_SYMBOL: This is the symbol of base currency. +So its value will be `OST`. +. NO_OF_SESSIONS_ON_ACTIVATE_USER: No of session keys to be created and whitelisted while activating user. + +* Place the file under main directory's assets folder + ++ +File path example: app \-> src \-> main \-> assets \-> ost-mobilesdk.json
*NOTE: These configurations are MANDATORY for successful operation. +Failing to set them will significantly impact usage.* + +=== Initialize the Wallet SDK + +SDK initialization should happen before calling any other `workflow`. +To initialize the SDK, you need to call `initialize` method of Wallet SDK. + +*Recommended location to call init() is in Application sub-class.* + +[source,java] +---- +import android.app.Application; + +import com.ost.mobilesdk.OstWalletSdk; + +public class App extends Application { + + public static final String OST_PLATFORM_API_BASE_URL = "https://api.ost.com/testnet/v2"; + @Override + public void onCreate() { + super.onCreate(); + + OstWalletSdk.initialize(getApplicationContext(), OST_PLATFORM_API_BASE_URL); + } + +} +---- + +---- + void initialize(context, baseUrl) +---- + +|=== +| Parameter | Description + +| *context* + *ApplicationContext* +| Application context can be retrieved by calling *getApplicationContext()* + +| *baseUrl* + *String* +| OST Platform API endpoints: + 1. +Sandbox Environment: `+https://api.ost.com/testnet/v2/+` + 2. +Production Environment: `+https://api.ost.com/mainnet/v2/+` +|=== + +== OST SDK Methods + +=== Types of Methods + +. `Workflows`: Workflows are the core functions provided by wallet SDK to do wallet related actions. +Workflows can be called directly by importing the SDK. + ** Application must confirm to `OstWorkFlowCallback` interface. +The `OstWorkFlowCallback` interface defines methods that allow applications to interact with Android Wallet SDK. +. `Getters`: The SDK provides getter methods that applications can use for various purposes. +These methods provide the application with data as available in the device's database. +These functions are synchronous and will return the value when requested. +. `JSON APIs`: Allows application to access OST Platform APIs + +== Workflows + +=== setupDevice + +This workflow needs `userId` and `tokenId` so `setupDevice` should be called after your app login or signup is successful. +Using the mapping between userId in OST Platform and your app user, you have access to `userId` and `tokenId`. + +*If the user is logged in, then `setupDevice` should be called every time the app launches, this ensures that the current device is registered before communicating with OST Platform server.* + +---- +void setupDevice( String userId, + String tokenId, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *tokenId* + *String* +| Unique identifier for the token economy + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. ++ This should implement `registerDevice` function. +`registerDevice` will be called during the execution of this workflow. +|=== + +=== activateUser + +It `authorizes` the registered device and activates the user. +User activation deploys the TokenHolder and Device manager contracts on blockchain. +Session keys are also created and authorized during `activateUser` workflow. +So after `user activation`, users can perform wallet actions like executing transactions and reset PIN. + +---- +void activateUser(UserPassphrase passphrase, + long expiresAfterInSecs, + String spendingLimit, + OstWorkFlowCallback callback) +---- + +|=== +| Parameter | Description + +| *userPassPhrase* + *UserPassphrase* +| A simple struct to hold and transfer pin information via app and SDK. + +| *expiresAfterInSecs* + *long* +| Expire time of session key in seconds. + +| *spendingLimit* + *String* +| Spending limit of session key in https://dev.ost.com/platform/docs/guides/execute-transactions/[atto BT]. + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== addSession + +This workflow will create and authorize the session key that is needed to do the transactions. +This flow should be called if the session key is expired or not present. + +---- + void addSession( String userId, + long expireAfterInSecs, + String spendingLimit, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *expiresAfterInSecs* + *long* +| Expire time of session key in seconds. + +| *spendingLimit* + *String* +| Spending limit of session key in https://dev.ost.com/platform/docs/guides/execute-transactions/[atto BT]. + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== performQRAction + +This workflow will perform operations after reading data from a QRCode. +This workflow can used to add a new device and to execute transactions. + +---- + void performQRAction(String userId, + String data, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *data* + *String* +| JSON object string scanned from QR code. + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== getDeviceMnemonics + +To get the 12 words recovery phrase of the current device key. +Users will use it to prove that it is their wallet. + +---- + void getPaperWallet( String userId, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== executeTransaction + +To do `user-to-company` and `user-to-user` transactions. + +[source,java] +---- +void executeTransaction(String userId, + String tokenId, + List tokenHolderAddresses, + List amounts, + String ruleName, + Map meta, + Map options, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *tokenId* + *String* +| Unique identifier for the token economy + +| *tokenHolderAddresses* + *List* +| *TokenHolder* addresses of amount receiver + +| *amounts* + *List* +| Amount to be transferred in atto. + +| *ruleName* + *String* +| Rule name to be executed. + +| *meta* + *Map* +| Transaction Meta properties. ++ Example: + {"name": "transaction name", + "type": "user-to-user" (it can take one of the following values: `user_to_user`, `user_to_company` and `company_to_user`), + "details": "like"} + +| *options* + *Map* +| Optional settings parameters. +You can set following values: + 1. +`currency_code`: Currency code for the pay currency. ++ Example: `{"currency_code": "USD"}` + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== authorizeCurrentDeviceWithMnemonics + +To add a new device using 12 words recovery phrase. + +---- +void addDeviceUsingMnemonics( String userId, + byte[] mnemonics, + OstWorkFlowCallback ostWorkFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *mnemonics* + *byte[]* +| byte array of 12 words. + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== resetPin + +To change the PIN. + +*User will have to provide the current PIN in order to change it.* + +---- + void resetPin(String userId, + String appSalt, + String currentPin, + String newPin, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *appSalt* + *String* +| + +| *currentPin* + *String* +| Current PIN + +| *newPin* + *String* +| New PIN + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== initiateDeviceRecovery + +A user can control their tokens using their authorized device(s). +If a user loses their authorized device, the user can recover access to her tokens by authorizing a new device by initiating the recovery process. + +[source,java] +---- +void initiateDeviceRecovery(String userId, + UserPassphrase passphrase, + String deviceAddressToRecover, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *passphrase* + *UserPassphrase* +| A simple struct to hold and transfer pin information via app and SDK. + +| *deviceAddressToRecover* + *String* +| Address of device to recover + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== abortDeviceRecovery + +To abort the initiated device recovery. + +[source,java] +---- +void abortDeviceRecovery(String userId, + UserPassphrase passphrase, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *passphrase* + *UserPassphrase* +| A simple struct to hold and transfer pin information via app and SDK. + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +=== logoutAllSessions + +To revoke all the sessions associated with provided userId. + +[source,java] +---- +void logoutAllSessions(String userId, + OstWorkFlowCallback workFlowCallback) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *workFlowCallback* + *OstWorkFlowCallback* +| An object that implements the callback functions available in `OstWorkFlowCallback` interface. +These callback functions are needed for communication between app and wallet SDK. +Implement `flowComplete` and `flowInterrupt` callback functions to get the workflow status. +Details about other callback function can be found in <>. +|=== + +== Getters + +=== getAddDeviceQRCode + +This getter function will return the QRCode Bitmap that can be used to show on screen. +This QRCode can then be scanned to add the new device. + +---- +Bitmap getAddDeviceQRCode(String userId) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform +|=== + +=== getUser + +This returns the loggedin User entity. + +[source,java] +---- +OstUser getUser(userId) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform +|=== + +=== getCurrentDeviceForUserId + +Method to get user's current device by Id.
This is a synchronous method and must be used only after calling `setupDevice` workflow.
This method returns OstToken only if available with SDK. +Returns `null` otherwise.
It does NOT make any server side calls. + +[source,java] +---- +OstDevice getCurrentDeviceForUserId(String userId) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform +|=== + +=== getToken + +This returns the token entity. + +[source,java] +---- +OstToken getToken(tokenId) +---- + +|=== +| Parameter | Description + +| *tokenId* + *String* +| Unique identifier of token economy in OST Platform +|=== + +=== isBiometricEnabled + +To get the biometric preferneces call this function. + +[source,java] +---- +boolean isBiometricEnabled(userId) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform +|=== + +=== getActiveSessionsForUserId + +Method to get user's active sessions available in current device that can execute transactions of given spending limit.
This is a synchronous method and must be used only after calling `setupDevice` workflow. + +[source,java] +---- +List getActiveSessionsForUserId(@NonNull String userId, @Nullable String minimumSpendingLimitInWei) +---- + +|=== +| Parameter | Description + +| *userId* + *String* +| Unique identifier of the user stored in OST Platform + +| *minimumSpendingLimitInWei* + *String* +| Minimum spending limit of the sessions +|=== + +This can also be initialized without `minimumSpendingLimitInWei` + + +[source,java] +---- +List getActiveSessionsForUserId(@NonNull String userId) +---- + +== OST JSON APIs + +=== getBalance + +Api to get user balance. +Balance of only current logged-in user can be fetched. + +*Parameters* +   +parameter userId: User Id of the current logged-in user. ++   +parameter callback: callback where to receive data/error. ++   +*getBalance(userId, callback)* + + +[source,java] +---- +OstJsonApi.getBalance(userId, new OstJsonApiCallback() { + @Override + public void onOstJsonApiSuccess(@Nullable JSONObject data) { } + + @Override + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject response) { } + } +); +---- + +=== getPricePoints + +Api to get Price Points. +It will provide latest conversion rates of base token to fiat currency. + +*Parameters* +   +parameter userId: User Id of the current logged-in user. ++   +parameter callback: callback where to receive data/error. ++   +*getPricePoints(userId, callback)* + + +[source,java] +---- +OstJsonApi.getPricePoints(userId, new OstJsonApiCallback() { + @Override + public void onOstJsonApiSuccess(@Nullable JSONObject data) { } + + @Override + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject response) { } + } +); +---- + +=== getBalanceWithPricePoints + +Api to get user balance and Price Points. +Balance of only current logged-in user can be fetched. +It will also provide latest conversion rates of base token to fiat currency. + +*Parameters* +   +parameter userId: User Id of the current logged-in user. ++   +parameter callback: callback where to receive data/error. ++   +*getBalanceWithPricePoints(userId, callback)* + + +[source,java] +---- +OstJsonApi.getBalanceWithPricePoints(userId, new OstJsonApiCallback() { + @Override + public void onOstJsonApiSuccess(@Nullable JSONObject data) { } + + @Override + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject response) { } + } +); +---- + +=== getTransactions + +Api to get user transactions. +Transactions of only current logged-in user can be fetched. + +*Parameters* +   +parameter userId: User Id of the current logged-in user. ++   +parameter requestPayload: request payload. +Such as next-page payload, filters etc. +  +parameter callback: callback where to receive data/error. ++   +*getTransactions(userId, requestPayload, callback)* + + +[source,java] +---- +OstJsonApi.getTransactions(userId, requestPayload, new OstJsonApiCallback() { + @Override + public void onOstJsonApiSuccess(@Nullable JSONObject data) { } + + @Override + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject response) { } + } +); +---- + +=== getPendingRecovery + +Api to get status of pending ongoing recovery. + +*Parameters* +   +parameter userId: User Id of the current logged-in user. ++   +parameter callback: callback where to receive data/error. ++   +*getPendingRecovery(userId, callback)* + + +[source,java] +---- +OstJsonApi.getPendingRecovery(userId, new OstJsonApiCallback() { + @Override + public void onOstJsonApiSuccess(@Nullable JSONObject data) { } + + @Override + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject response) { } + } +); +---- + +== JSON API Response Callback + +  +Callbacks to be implemented by application before calling any of the above OstJsonApis. + +=== onOstJsonApiSuccess + +[source,java] +---- + /** + * Inform SDK user about Success of OstJsonApi + * @param data Response data + */ + public void onOstJsonApiSuccess(@Nullable JSONObject data) { } +---- + +| Argument | Description | |--|--| | *data* + *JSONObject* | Api Response data | + +=== onOstJsonApiError + +[source,java] +---- + /** + * Inform SDK user about Failure of OstJsonApi + * @param err OstError object containing error details + * @param response Api response + */ + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject response) { } +---- + +| Argument | Description | |--|--| | *err* + *OstError* | OstError object containing error details | | *response* + *JSONObject* | Api Response | + +== OST Workflow Callback Interface + +Android SDK provides an interface to be implemented by the Java class calling the `workflows`. + +The interface name is `OstWorkFlowCallback` + +=== Importing the interface + +---- +import com.ost.mobilesdk.workflows.interfaces.OstWorkFlowCallback; +---- + +image::https://dev.ost.com/platform/docs/sdk/assets/wallet-sdk-communication.png[walletSDKCommunication] + +=== Interface Functions + +==== flowComplete + +This function will be called by wallet SDK when a workflow is completed. +The details of workflow and the entity that was updated during the workflow will be available in arguments. + +---- +void flowComplete(OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity) +---- + +|=== +| Argument | Description + +| *ostWorkflowContext* + *OstWorkflowContext* +| Information about the workflow + +| *ostContextEntity* + *OstContextEntity* +| Information about the entity +|=== + +==== flowInterrupt + +This function will be called by wallet SDK when a workflow is cancelled. +The workflow details and error details will be available in arguments. + +---- +void flowInterrupt(OstWorkflowContext ostWorkflowContext, OstError ostError) +---- + +|=== +| Argument | Description + +| *ostWorkflowContext* + *OstWorkflowContext* +| Information about the workflow + +| *ostError* + *OstError* +| ostError object will have details about the error that interrupted the flow +|=== + +==== requestAcknowledged + +This function will be called by wallet SDK when the core API request was successful which happens during the execution of workflows. +At this stage the workflow is not completed but it shows that the main communication between the wallet SDK and OST Platform server is complete. ++ Once the workflow is complete the `app` will receive the details in `flowComplete` (described below) function. + +---- +void requestAcknowledged(OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity) +---- + +|=== +| Argument | Description + +| *ostWorkflowContext* + *OstWorkflowContext* +| Information about the workflow + +| *ostContextEntity* + *OstContextEntity* +| Information about the entity +|=== + +==== getPin + +This function will be called by wallet SDK when it needs to get the PIN from the `app` user to authenticate any authorised action. + +{blank} + *Expected Function Definition:* Developers of client company are expected to launch their user interface to get the PIN from the user and pass back this PIN to SDK by calling *ostPinAcceptInterface.pinEntered()* + +---- +void getPin(String userId, OstPinAcceptInterface ostPinAcceptInterface) +---- + +|=== +| Argument | Description + +| *userId* + *String* +| Unique identifier of the user + +| *ostPinAcceptInterface* + *OstPinAcceptInterface* +| *ostPinAcceptInterface.pinEntered()* should be called to pass the PIN back to SDK. ++ For some reason if the developer wants to cancel the current workflow they can do it by calling *ostPinAcceptInterface.cancelFlow()* +|=== + +==== pinValidated + +This function will be called by wallet SDK when the last entered PIN is validated. + +---- +void pinValidated(String userId) +---- + +|=== +| Argument | Description + +| *userId* + *String* +| Unique identifier of the user +|=== + +==== invalidPin + +This function will be called by wallet SDK when the last entered PIN was wrong and `app` user has to provide the PIN again. +Developers are expected to repeat the `getPin` method here and pass back the PIN again back to the SDK by calling *ostPinAcceptInterface.pinEntered()* . + +---- +void invalidPin(String userId, OstPinAcceptInterface ostPinAcceptInterface) +---- + +|=== +| Argument | Description + +| *userId* + *String* +| Unique identifier of the user + +| *ostPinAcceptInterface* + *OstPinAcceptInterface* +| *ostPinAcceptInterface.pinEntered()* should be called to again pass the PIN back to SDK. ++ For some reason if the developer wants to cancel the current workflow they can do it by calling *ostPinAcceptInterface.cancelFlow()* +|=== + +==== registerDevice + +This function will be called by wallet SDK to register the device. ++ *Expected Function Definition:* Developers of client company are expected to register the device by communicating with client company's server. +On client company's server they can use `Server SDK` to register this device in OST Platform. +Once the device is registered on OST Platform client company's server will receive the newly created `device` entity. +This device entity should be passed back to the `app`. ++ Finally they should pass back this newly created device entity back to the wallet SDK by calling *OstDeviceRegisteredInterface.deviceRegistered(JSONObject newDeviceEntity )*. + +---- +void registerDevice(JSONObject apiParams, OstDeviceRegisteredInterface ostDeviceRegisteredInterface) +---- + +|=== +| Argument | Description + +| *apiParams* + *JSONObject* +| Device information for registration + +| *ostDeviceRegisteredInterface* + *OstDeviceRegisteredInterface* +| *OstDeviceRegisteredInterface.deviceRegistered(JSONObject newDeviceEntity )* should be called to pass the newly created device entity back to SDK. ++ In case data is not verified the current workflow should be canceled by developer by calling *OstDeviceRegisteredInterface.cancelFlow()* +|=== + +==== verifyData + +This function will be called by wallet SDK to verify data during `performQRAction` workflow. + +---- +void verifyData(OstWorkflowContext ostWorkflowContext, OstContextEntity ostContextEntity, OstVerifyDataInterface ostVerifyDataInterface) +---- + +|=== +| Argument | Description + +| *ostWorkflowContext* + *OstWorkflowContext* +| Information about the current workflow during which this callback will be called + +| *ostContextEntity* + *OstContextEntity* +| Information about the entity + +| *ostVerifyDataInterface* + *OstVerifyDataInterface* +| *ostVerifyDataInterface.dataVerified()* should be called if the data is verified successfully. ++ In case data is not verified the current workflow should be canceled by developer by calling *ostVerifyDataInterface.cancelFlow()* +|=== + +== Application development supporting documentation + +=== Entities status on User Activities + +|User Activity |App State|User Status|Device Status|Session status| | -- | -- | :--: | :--: | :--: | |Installs app for the first time|Not Login|CREATED|UNREGISTED| `NA`| |Login in the app for the first time|Log In|CREATED|REGISTERED| `NA`| |Initiate Activate Wallet by entering pin|Activating Wallet|ACTIVATING|AUTHORIZING|INITIALIZING| |Activates Wallet after waiting|Activated Wallet|ACTIVATED|AUTHORIZED|AUTHORISED| |Performs transactions|Activated Wallet|ACTIVATED|AUTHORIZED|AUTHORISED| |Session get expired|Activated Wallet|ACTIVATED|AUTHORIZED|EXPIRED| |Logout all Sessions|Activated Wallet|ACTIVATED|AUTHORIZED|REVOKING \-> REVOKED| |Add Session|Activated Wallet|ACTIVATED|AUTHORIZED|INITIALIZING \-> AUTHORISED| |Log out from app|Not Login|ACTIVATED|AUTHORIZED|AUTHORISED| |Log in back to App|Activated Wallet|ACTIVATED|AUTHORIZED|AUTHORISED| |Reinstall the App|No Login|CREATED|UNREGISTED| `NA`| |Login in the app|Log In|ACTIVATED|REGISTERED| `NA`| |Recover Wallet Or Add Wallet|Activating Wallet|ACTIVATED|AUTHORIZING \-> AUTHORISED| `NA`| |Revoked Device from other device|Activated Wallet|ACTIVATED|REVOKING \-> REVOKED| `NA`| + +=== Get Entity Status Updates + +To get real time updates of entities like ongoing activation Or transactions, server side SDK's https://dev.ost.com/platform/docs/api/#webhooks[WebHooks] services can be used. + +=== Wallet Check on App Launch + +* Check whether User need Activation. +* Check whether Wallet need Device Addition Or Recovery. + ** For device addition, the current Device which is to be Authorized should used *OstSdk.getAddDeviceQRCode* to generate QR code And *OstSdk.performQRAction()* method should be used to process that QR from AUTHORIZED deivce. + ** Device can also be added through *OstSdk.authorizeCurrentDeviceWithMnemonics()* by passing AUTHORIZED device mnemonics. + ** Or Device can be recovered through *OstSdk.initiateDeviceRecovery()* by passing Device address of the Device to be recovered from. ++ +[source,java] +---- +if (!(ostUser.isActivated() || ostUser.isActivating())) { + //TODO:: Wallet need Activation +} else if (ostUser.isActivated() && ostUser.getCurrentDevice().canBeAuthorized()) { + //TODO:: Ask user whether he wants to Add device through QR or Mnemonics Or want to recover device. +} else { + //TODO:: App Dashboard +} +---- ++ +=== Balance Calculation +* TokenHolder Balance can be shown in Token currency or in Fiat currency. + ** For Token currency conversion, the fetched balance is in Wei unit, which needs to be converted to Base unit. + ** For Fiat currency conversion, the fetched balance first need to be converted to fiat equivalent using current converion rate from price points and then to its Base unit. +```java OstJsonApi.getBalanceWithPricePoints(userId, new OstJsonApiCallback() { @Override public void onOstJsonApiSuccess(@Nullable JSONObject jsonObject) { if ( null != jsonObject ) { String balance = "0"; +JSONObject pricePoint = null; +try{ JSONObject balanceData = jsonObject.getJSONObject(jsonObject.getString("result_type")); +balance = balanceData.getString("available_balance"); +pricePoint = jsonObject.optJSONObject("price_point"); +} catch(Exception e){ } //To user balance in token currency with two decimals. +convertWeiToTokenCurrency(balance); ++ +.... + //To user balance in fiat(Dollar) with two decimals. + convertBTWeiToFiat(balance, pricePoint) + } else { + //Todo:: Show fetch error + } + } + + @Override + public void onOstJsonApiError(@NonNull OstError err, @Nullable JSONObject data) { + //Todo:: Show fetch error + } +}); +.... + +public static String convertWeiToTokenCurrency(String balance) { if (null == balance) return "0"; + + OstToken token = OstSdk.getToken(AppProvider.getTokenId()); + Integer decimals = Integer.parseInt(token.getBtDecimals()); + BigDecimal btWeiMultiplier = new BigDecimal(10).pow(decimals); + BigDecimal balance = new BigDecimal(balance).divide(btWeiMultiplier); + return balance.setScale(2, RoundingMode.HALF_UP).toString(); + } + +public static String convertBTWeiToFiat(String balance, JSONObject pricePointObject) { if (null == balance || null == pricePointObject) return null; + +.... + try{ + OstToken token = OstSdk.getToken(AppProvider.getTokenId()); + double pricePointOSTtoUSD = pricePointObject.getJSONObject(token.getBaseToken()).getDouble("USD"); + int fiatDecimalExponent = pricePointObject.getJSONObject(token.getBaseToken()).getInt("decimals"); + BigDecimal fiatToEthConversionFactor = new BigDecimal("10").pow(fiatDecimalExponent); + + BigDecimal tokenToFiatMultiplier = calTokenToFiatMultiplier(pricePointOSTtoUSD, fiatDecimalExponent, token.getConversionFactor(), Integer.parseInt(token.getBtDecimals())); + + BigDecimal fiatBalance = new BigDecimal(balance).multiply(tokenToFiatMultiplier); + + return fiatBalance.divide(fiatToEthConversionFactor, 2, RoundingMode.DOWN).toString(); + + } catch (Exception e){ + return null; + } +} ``` +.... + +== Classes + +. OstError +. OstContextEntity +. OstWorkflowContext + +=== OstError + +This class is used to provide error details in <> callback function. + +You can call the following methods on this object to get more details about the error. + +==== i). Methods + +. `public OstErrors.ErrorCode getErrorCode()` +. `public String getInternalErrorCode()` +. `public boolean isApiError()` + +=== OstContextEntity + +This class provides context about the `entity` that is being changed during a <>. +Callback functions that needs to know about the `entity` will receive an object of this class as an argument. + +You can call the following methods on this object to get more details about the entity. + +==== i). Methods + +. `public OstContextEntity(String message, Object entity, String entityType)` +. `public OstContextEntity(Object entity, String entityType)` +. `public String getMessage()` +. `public Object getEntity()` +. `public String getEntityType()` + +=== OstWorkflowContext + +This class provides context about the current <>. +Callback function that needs to know about the current <> will get the object of this class as an argument. + +You can call the following methods on this object to get more details about the current <>. + +The `getWorkflow_type()` methods will return one of the strings from this enum. + +[source,java] +---- +public enum WORKFLOW_TYPE { + UNKNOWN, + SETUP_DEVICE, + ACTIVATE_USER, + ADD_SESSION, + GET_DEVICE_MNEMONICS, + PERFORM_QR_ACTION, + EXECUTE_TRANSACTION, + AUTHORIZE_DEVICE_WITH_QR_CODE, + AUTHORIZE_DEVICE_WITH_MNEMONICS, + INITIATE_DEVICE_RECOVERY, + ABORT_DEVICE_RECOVERY, + REVOKE_DEVICE_WITH_QR_CODE, + RESET_PIN, + LOGOUT_ALL_SESSIONS + } +---- + +==== i). Methods + +. `public OstWorkflowContext(WORKFLOW_TYPE workflow_type)` +. `public OstWorkflowContext()` +. `public WORKFLOW_TYPE getWorkflow_type()` + +== Steps to use Android mobile SDK through AAR lib + +* Download AAR file from S3 https://sdk.stagingost.com.s3.amazonaws.com/Android/release/ostsdk-release.aar[Download link] +* Create libs folder under app directory in your application project. +* In libs folder add your downloaded aar file. +* Add aar lib dependency to your build.gradle file ++ +---- +
implementation files('libs/ostsdk-release.aar') +---- + +* Also add dependencies of ostsdk in you build.gradle + +[source,groovy] +---- +dependencies { + + // your app dependencies + + //--- Section to Copy ---- + + // Room components + implementation "android.arch.persistence.room:runtime:1.1.1" + annotationProcessor "android.arch.persistence.room:compiler:1.1.1" + implementation 'com.madgag.spongycastle:core:1.56.0.0' + implementation 'org.web3j:core:4.1.0-android' + // Lifecycle components + implementation "android.arch.lifecycle:extensions:1.1.1" + annotationProcessor "android.arch.lifecycle:compiler:1.1.1" + // https://mvnrepository.com/artifact/com.google.guava/guava + implementation 'com.google.guava:guava:18.0' + // Zxing barcode dependency + implementation 'me.dm7.barcodescanner:zxing:1.9.8' + + //---Section to Copy ---- + +} +---- + +* Clean and then Build your Android project. + +== OST Wallet UI + +For quick and easy integration with SDK, developers can use built-in user interface components which are configurable and support content and theme customization. +All OstWalletSdkUI workflows return workflow-id. +The application can subscribe to the events of the workflow using the workflow-id. +Please refer xref:./documentation/OstWalletUI.adoc[OstWalletUI]. + +== Public Key Pinning Using TrustKit + +If your Application is using TrustKit, Please refer xref:./documentation/TrustKitPublickeyPinning.adoc[TrustKit Public Key Pinning]