diff --git a/docs/modules/ROOT/pages/OstJsonApi.md.adoc b/docs/modules/ROOT/pages/OstJsonApi.md.adoc index cb4a2d9..1857aaa 100644 --- a/docs/modules/ROOT/pages/OstJsonApi.md.adoc +++ b/docs/modules/ROOT/pages/OstJsonApi.md.adoc @@ -24,6 +24,9 @@ OST JSON APIs are a set of _asynchronous_ methods that make API calls to OST Pla *** <> *** <> *** <> + ** <> + *** <> + *** <> * <> ** <> *** <> @@ -31,6 +34,9 @@ OST JSON APIs are a set of _asynchronous_ methods that make API calls to OST Pla ** <> *** <> *** <> + ** <> + *** <> + *** <> ++++++++++++ @@ -393,6 +399,147 @@ The `getPendingRecoveryForUserId` API will respond with `UNPROCESSABLE_ENTITY` A } ---- +++++++++++++ + +=== Get Redeemable Sku Details + +API to get redeemable sku details. + +++++++++++++ + +.Usage +[source,javascript] +---- +/* + 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. +*/ +let userId = "71c59448-ff77-484c-99d8-abea8a419836"; +let skuDetailId = "2"; +let extraParams = {}; + +/** + * Api to get redeemable skus + * @param {String} userId - Ost User id + * @param {String} skuDetailId - Sku detail id got from list of Redeemable skus + * @param {Object} extraParams (@nullable). + * @param {function} Success callback with success data + * @param {function} Failure callback with error and failure response + * @public + */ + + +OstJsonApi.getRedeemableSkuDetails(userId, skuDetailId ,extraParams, (response) => { + console.log(response); + }, (error)=> { + console.log("An error has occurred while fetching redeemable sku details."); + console.log( error ); + }); +---- + +++++++++++++ + +.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 @@ -613,3 +760,94 @@ OstJsonApi.getDeviceListForUserId(userId, nextPagePayload, "result_type": "devices" } ---- + +++++++++++++ + +=== Get Redeemable Skus + +API to get redeemable skus. + +++++++++++++ + +.Usage +[source,javascript] +---- +/* + 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. +*/ +let userId = "71c59448-ff77-484c-99d8-abea8a419836"; +let nextPagePayload = null; + +/** + * Api to get redeemable skus + * @param {String} userId - Ost User id + * @param {Object} nextPagePayload (@nullable). Pass null to get first page. + * @param {function} Success callback with success data + * @param {function} Failure callback with error and failure response + * @public + */ + + +OstJsonApi.getRedeemableSkus(userId, nextPagePayload , (respones) => { + console.log(response); + // Let's check if more pages of data is available. + if ( response.meta ) { + let nextPagePayloadFromResponse = response.meta.next_page_payload || {}; + if ( Object.keys(nextPagePayloadFromResponse).length > 0 ) { + // Next page is available. + // Update nextPagePayload + nextPagePayload = nextPagePayloadFromResponse; + // To fetch the next page, pass the updated nextPagePayload. + } + } + }, (error)=> { + console.log("An error has occurred while fetching redeemable skus."); + console.log( error ); + }); +---- + +++++++++++++ + +.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/OstRedemptionConfig.md.adoc b/docs/modules/ROOT/pages/OstRedemptionConfig.md.adoc new file mode 100644 index 0000000..71785fa --- /dev/null +++ b/docs/modules/ROOT/pages/OstRedemptionConfig.md.adoc @@ -0,0 +1,68 @@ += OstWallet Redemption Config + +== Introduction + +App developers can configure the text shown on redemption page. + +To configure the content, the sdk needs to be provided with https://developer.mozilla.org/en-US/docs/Learn/JavaScript/Objects/JSON[JSON object]. + +== Dictionary Data Structure + +Here is the small sample json representation of the configuration. + +[source,json] +---- +{ + "common": { + "walletIcon": null, + "storeIcon": null + }, + "skuListScreen": { + "navHeader": null, + "header": null, + "description": null + }, + "skuDetailsScreen": { + "navHeader": null + } +} +---- + +In the above example: + +* The key `common` includes options to configure the wallet icon in header and the store icon. +* The key `skuListScreen` allows to configure the navigation header and the header and description shown on the redemption store list page. +* The key `skuDetailsScreen` allows to configure the navigation header shown on the redemption store details page. + +== Redemption Config + +The following are the customizable options provided. +These can be set in the above config. + +|=== +| customizable component | Config Keys | Config Type + +| Wallet icon +| - walletIcon +| Custom icon Image to be rendered. + +| Store icon +| - storeIcon +| Custom icon Image to be rendered. + +| Skulist Header +| - skuListScreen.header +| String + +| Skulist Description +| - skuListScreen.description +| String + +| SkuDetails Screen Navigation header +| - skuDetailsScreen.navHeader +| String + +| Skulist Screen Navigation header +| - skuListScreen.navHeader +| String +|=== diff --git a/docs/modules/ROOT/pages/OstRedemptionFlow.md.adoc b/docs/modules/ROOT/pages/OstRedemptionFlow.md.adoc new file mode 100644 index 0000000..a1158d2 --- /dev/null +++ b/docs/modules/ROOT/pages/OstRedemptionFlow.md.adoc @@ -0,0 +1,65 @@ += OstRedemption Flow + +== Introduction + +OstRedemption component is a pre-built UI component available exclusively in `ost-wallet-sdk-react-native` SDK. +It consist two pages - one displaying redeemable product list and another displaying product details and redemption options. +It can be used by end-users to integrate redemption flow into their app. + +____ +*IMPORTANT:* This feature requires application to use https://reactnavigation.org/docs/en/getting-started.html[React Navigation] package. +____ + +== Usage + +=== Create Redemption Flow stack navigation + +[source,js] +---- +import {OstRedeemableSkus, OstRedeemableSkuDetails } from '@ostdotcom/ost-wallet-sdk-react-native'; + +let redemptionStack = createStackNavigator( + { + RedeemableSkusScreen: OstRedeemableSkus, + RedeemableSkuDetails: OstRedeemableSkuDetails + } +); +---- + +=== Navigate to settings page + +`ostUserId` and `ostWalletUIWorkflowCallback` are mandetory parameters that need to be passed as params to the `RedeemableSkusScreen` screen. + +[source,js] +---- +const ostUserId = +const delegate = new OstWalletUIWorkflowCallback(ostUserId, {}) +this.props.navigation.push("RedeemableSkusScreen", {'ostUserId': ostUserId , + 'ostWalletUIWorkflowCallback': delegate, + 'navTitle': 'My Store'}); +---- + +____ +*Note* + Developer needs to create a class extends from `OstWalletUIWorkflowCallback` and write logic to get passphrase prefix from their application server. +Please refer link:OstWalletUI.md#setup-your-passphrase-prefix-delegate[this] section for documentation. +____ + +== UI Customization + +Developer can customize Redemption flow by updating respective properties mentioned in image. +OstTheme config shown link:./configs/ost-sdk-theme-config.js[here] + +image::images/redemptionFlow.png[copy-framework-file] + +== Redemption Content + +Developer can make various modifications in redemption flow component. +To modify contet, xref:./OstRedemptionConfig.adoc[refer here]. + +[source,js] +---- +import ost_sdk_redemption_config from "../../theme/ostsdk/ost-sdk-redemption-config"; +import { OstRedemableCustomConfig } from '@ostdotcom/ost-wallet-sdk-react-native'; + + OstRedemableCustomConfig.setConfig(ost_sdk_redemption_config); +---- diff --git a/docs/modules/ROOT/pages/OstWalletUI.md.adoc b/docs/modules/ROOT/pages/OstWalletUI.md.adoc index 19fd2db..3cf08bd 100644 --- a/docs/modules/ROOT/pages/OstWalletUI.md.adoc +++ b/docs/modules/ROOT/pages/OstWalletUI.md.adoc @@ -264,6 +264,8 @@ OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowInterrupt, (ostWo A session is a period of time during which a sessionKey is authorized to sign transactions under a pre-set limit per transaction on behalf of the user. The device manager, which controls the tokens, authorizes sessions. +* *By Calling function* + + [source,js] ---- @@ -300,6 +302,82 @@ OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowInterrupt, (ostWo }); ---- +* ++++++By scanning QR-Code ++++++ + + +QR Code Sample + +---- +as|2.0.0|2a421359d02132e8161cda9518aeaa62647b648e|5369b4d7e0e53e1159d6379b989a8429a7b2dd59|1|1583308559|4d40c46a7302974134a67ce77bdfae0e1f78ee518e87b6cda861ffc5847dfaca11a653651c6cdfadf0224574f6f07e1a78aabacdfed66d8c78e1fb2c9bc750161c +---- + +[source,js] +---- + +let uiCallback = new UserPassphrasePrefixDelegate() + +/** + * Add user session + * @param {String} userId - Ost User id + * @param {OstWalletUIWorkflowCallback} uiCallback - callback implementation instances for application communication + * @public + */ +let workflowId = OstWalletSdkUI.scanQRCodeToAuthorizeSession( + userId, + uiCallback +) + +// Subscribe to events +OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.requestAcknowledged, () => { + // Session is being added. +}); + +OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowComplete, (ostWorkflowContext , ostContextEntity) => { + // Show success message to user. + // Session has been added. +}); + +OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowInterrupt, (ostWorkflowContext , ostError) => { + // Show error to user. + // An error occoured during the workflow. The Session has NOT been added. +}); +---- + +* ++++++With QR Code Payload ++++++ + + +[source,js] +---- + +let uiCallback = new UserPassphrasePrefixDelegate() +let payload = "as|2.0.0|2a421359d02132e8161cda9518aeaa62647b648e|5369b4d7e0e53e1159d6379b989a8429a7b2dd59|1|1583308559|4d40c46a7302974134a67ce77bdfae0e1f78ee518e87b6cda861ffc5847dfaca11a653651c6cdfadf0224574f6f07e1a78aabacdfed66d8c78e1fb2c9bc750161c" +/** + * Authorize browser session with QR code payload + * @param {String} userId - Ost User id + * @param {String} qrPayload - QR-Code payload + * @param {OstWalletUIWorkflowCallback} uiCallback - callback implementation instances for application communication + * @return {*|number} + */ +let workflowId = OstWalletSdkUI.authorizeSessionWithQRPayload( + userId, + payload, + uiCallback +) + +// Subscribe to events +OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.requestAcknowledged, () => { + // Session is being added. +}); + +OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowComplete, (ostWorkflowContext , ostContextEntity) => { + // Show success message to user. + // Session has been added. +}); + +OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowInterrupt, (ostWorkflowContext , ostError) => { + // Show error to user. + // An error occoured during the workflow. The Session has NOT been added. +}); +---- + ==== Get Mnemonic Phrase The mnemonic phrase represents a human-readable way to authorize a new device. @@ -611,6 +689,8 @@ QR-Code Sample: } ---- +* ++++++By scanning QR-Code ++++++ + + [source,js] ---- let uiCallback = new UserPassphrasePrefixDelegate(); @@ -639,6 +719,38 @@ QR-Code Sample: }); ---- +* ++++++with QR Code payload ++++++ + Developer can pass QR code payload to authorize device. +QR code scanner view won't open if developer pass payload. + +[source,js] +---- + let uiCallback = new UserPassphrasePrefixDelegate(); + let payload = "{\"dd\":\"AD\",\"ddv\":\"1.1.0\",\"d\":{\"da\":\"0x7701af46018fc57c443b63e839eb24872755a2f8\"}}" + /** + * Authorize device with QR code payload + * @param {String} userId - Ost User id + * @param {String} qrPayload - QR-Code payload + * @param {OstWalletUIWorkflowCallback} uiCallback - callback implementation instances for application communication + * @return {*|number} + */ + let workflowId = OstWalletSdkUI.authorizeDeviceWithQRPayload(userId, payload, uiCallback); + + // Subscribe to events + OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.requestAcknowledged, () => { + // Device is being authorized. + }); + + OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowComplete, (ostWorkflowContext , ostContextEntity) => { + // Show success message to user. + // Device has been authorized. + }); + + OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowInterrupt, (ostWorkflowContext , ostError) => { + // Show error to user. + // An error occoured during the workflow. + }); +---- + === Execute Transaction * ++++++By Scanning QR-Code ++++++ + To execute transaction via device by scanning device QR-Code. @@ -704,6 +816,38 @@ QR-Code Sample: }); ---- +* ++++++with QR Code payload ++++++ + Developer can pass QR code payload to execute transaction. +QR code scanner view won't appear if developer pass payload. + +[source,js] +---- + let uiCallback = new UserPassphrasePrefixDelegate(); + let payload = + /** + * Execute transaction with QR code payload + * @param {String} userId - Ost User id + * @param {String} qrPayload - QR-Code payload + * @param {OstWalletUIWorkflowCallback} uiCallback - callback implementation instances for application communication + * @return {*|number} + */ + let workflowId = OstWalletSdkUI.executeTransactionWithQRPayload(userId, payload, uiCallback); + + // Subscribe to events + OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.requestAcknowledged, () => { + // Device is being authorized. + }); + + OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowComplete, (ostWorkflowContext , ostContextEntity) => { + // Show success message to user. + // Device has been authorized. + }); + + OstWalletSdkUI.subscribe(workflowId, OstWalletSdkUI.EVENTS.flowInterrupt, (ostWorkflowContext , ostError) => { + // Show error to user. + // An error occoured during the workflow. + }); +---- + * *By Calling function* + Helper method creates session if active sessoin for transction amount is not available. To execute transaction via helper method, xref:./OstTransactionHelper.adoc[ref here] diff --git a/docs/modules/ROOT/pages/README.md.adoc b/docs/modules/ROOT/pages/README.md.adoc index 1e70145..5d1a06b 100644 --- a/docs/modules/ROOT/pages/README.md.adoc +++ b/docs/modules/ROOT/pages/README.md.adoc @@ -32,6 +32,8 @@ Ost React Native Wallet SDK... *** <> ** <> *** <> + ** <> + *** <> ** <> *** <> * <> @@ -281,6 +283,8 @@ ____ Please refer to link:./documentation/OstWalletUI.md#activate-user[Activate User UI Workflow Documentation] for implementation details. +++++++++++++ + === 3. Wallet Settings UI Component ''' @@ -296,7 +300,25 @@ ____ Please refer to xref:./documentation/OstWalletSettings.adoc[OstWallet Settings Documentation] for implementation details. -=== 4. OstvTransaction Helper - Transaction and Add Session Integrated Workflow +++++++++++++ + +=== 4. Redemption Flow UI Component + +''' + +OstRedemption component is a pre-built UI component available exclusively in `ost-wallet-sdk-react-native` SDK. +It consist two pages - one displaying redeemable product list and another displaying product details and redemption options. +It can be used by end-users to integrate redemption flow into their app. + +____ +*IMPORTANT:* This feature requires application to use https://reactnavigation.org/docs/en/getting-started.html[React Navigation] package. +____ + +==== Implementation + +Please reder to xref:./documentation/OstRedemptionFlow.adoc[OstRedemption flow Documentation] for implementation details. + +=== 5. OstTransaction Helper - Transaction and Add Session Integrated Workflow ''' diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc deleted file mode 100644 index 1e70145..0000000 --- a/docs/modules/ROOT/pages/index.adoc +++ /dev/null @@ -1,336 +0,0 @@ -= Ost Wallet SDK React Native - -== Introduction - -Ost React Native Wallet SDK is the official Ost Wallet SDK for react-native platform. -The SDK is a mobile application development SDK that enables developers to integrate the functionality of a non-custodial crypto-wallet into consumer applications. - -Ost React Native Wallet SDK... - -* Safely generates and stores keys on the user's mobile device -* Signs ethereum transactions and data as defined by contracts using EIP-1077 -* Enables users to recover access to their Brand Tokens in case the user loses their authorized device - -== Table of Contents - -* <> -* <> -* <> - ** <> - ** <> - ** <> -* <> -* <> -* <> - ** <> - *** <> - *** <> - *** <> - ** <> - *** <> - *** <> - *** <> - ** <> - *** <> - ** <> - *** <> -* <> -* <> -* <> - ** <> - ** <> - -== Installing React-native SDK - -. Install React Native and create a react-native project - -Follow this https://facebook.github.io/react-native/docs/0.59/getting-started[official react-native getting started guide] to install react native and create a react-native project - -. Install Ost React Native SDK in your project The sdk needs following peer dependencies: - ** https://www.npmjs.com/package/eventemitter3[eventemitter3] - ** https://www.npmjs.com/package/lodash.merge[lodash.merge] - ** https://www.npmjs.com/package/bignumber.js[bignumber.js] - -[source,bash] ----- - npm install --save lodash.merge - npm install --save eventemitter3 - npm install --save bignumber.js ----- - -Run following command in your react-native project root - -[source,bash] ----- - npm install --save @ostdotcom/ost-wallet-sdk-react-native ----- - -. Linking the Ost React Native SDK with your project - -[source,bash] ----- - react-native link @ostdotcom/ost-wallet-sdk-react-native ----- - -. xref:./documentation/android_setup.adoc[Android set-up for Ost React Native SDK] -. xref:./documentation/ios_setup.adoc[iOS Set-up for Ost React Native SDK] - -== Migrating to another version - -If you decide to change the SDK version, please make sure to update the downsteam native SDKs. - -For Android, please run: - -[source,shell] ----- -react-native link -react-native run-android ----- - -For iOS, please update the `ios/Cartfile` with desired version and run: - -[source,shell] ----- -carthage update --cache-builds --platform ios ----- - -After updating the SDK, please delete `ostwalletrnsdk` using the *Remove References* option and add it back by following link:./documentation/ios_setup.md#5-add-additional-sdk-files[this step]. - -== SDK Usage - -* Initialize the SDK -* Subscribe to events -* Implement `OstWalletWorkFlowCallback` for a workflow -* Execute workflow - -=== Initializing the SDK - -You must initialize the SDK before using it. - -____ -Initialize the SDK in using BASE_URL (Ost Platform endpoint) inside App.js `constructor()` method. -____ - -[source,javascript] ----- -/** - * Initialize wallet sdk - * @param {String} endpoint - Ost Platform endpoint - * @param {function} Callback function with error and success status. - * @public - */ - OstWalletSdk.initialize( endpoint, - (error, success) => {}) ----- - -=== Initializing SDK With Config - -Starting version `2.3.1` application can also pass SDK config in the initialize method - -____ -If config is passed in `initialize` method, the configs specified in `OstWalletSdk.plist` and `ost-mobilesdk.json` are ignored. -It is no longer mandatory to define `ost-mobilesdk.json` and `OstWalletSdk.plist` files. -____ - -[source,javascript] ----- - let sdkConfig = { - "BLOCK_GENERATION_TIME": 3, - "PIN_MAX_RETRY_COUNT": 3, - "REQUEST_TIMEOUT_DURATION": 60, - "SESSION_BUFFER_TIME": 3600, - "PRICE_POINT_CURRENCY_SYMBOL": "USD", - "USE_SEED_PASSWORD": false, - "NO_OF_SESSIONS_ON_ACTIVATE_USER": 1, - "ENABLE_IOS_DEVICE_RESTORE": false - }; - - /** - * Initialize wallet sdk - * @param {String} endpoint - Ost Platform endpoint - * @param {Object} config (optional) - SDK Config. Supported from version 2.3.1 - * @param {function} callback - A typical node-style, error-first callback. - * @callback params {Object}error , {Boolean} success - * @public - */ - OstWalletSdk.initialize( endpoint, sdkConfig, (error, success) => { - - }); ----- - -=== Subscribe to `OstWalletSdkEvents` in your top most level component - -In the most top level component (mostly `App.js`) import like this: - -[source,javascript] ----- -import { OstWalletSdkEvents, OstWalletSdk, OstWalletSdkUI, OstJsonApi } from '@ostdotcom/ost-wallet-sdk-react-native'; ----- - -In `componentDidMount()` subscribe to OstWalletSdkEvents and in `componentWillUnmount()` unsubscribe to OstWalletSdkEvents. -Also initialize the SDK in using BASE_URL (Ost Platform endpoint) `constructor()` method: - -[source,javascript] ----- -class App extends Component { - - constructor() { - super(); - OstWalletSdk.initialize(BASE_URL, (error, success) => { - if(error) { - console.warn(error); - } - else { - console.warn(success); - } - - }); - } - - componentDidMount() { - OstWalletSdkEvents.subscribeEvent(); - } - - componentWillUnmount() { - OstWalletSdkEvents.unsubscribeEvent(); - } - -} ----- - -== Getter Methods - -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. -Please refer to xref:./documentation/OstWalletSdkGetMethods.adoc[Ost Wallet SDK Getter Methods] for documentation. - -== Ost JSON APIs - -While the getter methods provide application with data stored in device's database, the JSON API methods make API calls to Ost Platform servers. -Please refer to xref:./documentation/OstJsonApi.adoc[Ost JSON API] for documentation. - -== Quick Start Guide - Ost Macro Workflows - -Starting version 2.3.12-beta.1, developers can enable all the Ost wallet features implementing the Ost Macro Workflows. - -=== 1. Setup Device Core Workflow - -''' - -The setup device workflow establishes trust between the device and Ost Platform. -As application is responsible for user authentication, application servers must facilitate this workflow using the server side sdk. - -==== Workflow Details - -* When this workflow is initiated by the application, the Sdk creates the following keys: - ** API key - the key used to sign API requests sent to Ost Platform from the sdk. - ** Device key - the user's wallet device key. -All device manager operations shall be performed using this key. -* The Sdk asks the application to register the device entity with Ost Platform. -* The application must send the device entity to the application server. -* The application server must then use the server side sdk to register the device with Ost Plaform by using device service's create device Api. -* Once the device is registered by the Ost Platform, the application server must send the response to the mobile application. -* The mobile application must then use the `deviceRegistered` callbacks to provide the response to the Sdk. -* The sdk validates the registration by making Api calls to the Ost Plaform. - -image::./documentation/images/setup_device_workflow.svg[] - -==== Notes - -* Setup device workflow must be initiated *on every app launch*. -* Setup device workflow must be initiated only *after the user has been autheniticated* by the application, including cookie based authentication for already logged-in users. -* Each of user's device creates its own API key and device key. -* User's Device and API keys are not shared across devices. -* User's API key & device key are stored in persistent storage on the device and created only if needed. -* The Sdk shall request for device registration only when needed. -`registerDevice` shall not be invoked if device is already authorized and sdk is able to make Api calls to Ost Platform. - -==== Implementation - -Please refer to link:./documentation/OstCoreWorkflows.md#setupdevice[`setupDevice` core workflow documentation] for implementation details. - -=== 2. Activate User UI Workflow - -''' - -Activate User workflow deploys user's wallet on the blockchain and whitelists the user's wallet and enables it to take part in application's brand token economy. - -==== Blockchain Transactions Performed During Activate User Workflow - -* Deploys user's contracts - ** Device-manager and token-holder contracts - ** Set user's recovery key address, device key address in device-manager contract - ** Authorizes session key(s) in token-holder contract -* Whitelists user's contract in UBT (Utility Brand Token Contract). - -==== Recovery Key Generation Using 6 Digit Pin - -* User's recovery key is generated using https://en.bitcoinwiki.org/wiki/Scrypt[SCrypt], a password-based key derivation function. -* The '`password`' provided to this function is a string created by concatenating: -* A prefix provided by application server. -+ -____ -Application server must generate and store prefix for each user, treat it as sensitive and immutable information. -____ - -* User's PIN -* User's Ost-id -* The salt required for SCrypt is provided by Ost Platform - -==== Implementation - -Please refer to link:./documentation/OstWalletUI.md#activate-user[Activate User UI Workflow Documentation] for implementation details. - -=== 3. Wallet Settings UI Component - -''' - -OstWallet Settings is a pre-built UI component available exclusively available in `ost-wallet-sdk-react-native` SDK. -It is a wallet settings page that can be used by end-users to perfrom 12 different wallet operations and view their wallet details. - -____ -*IMPORTANT:* This feature requires application to use https://reactnavigation.org/docs/en/getting-started.html[React Navigation] package. -____ - -==== Implementation - -Please refer to xref:./documentation/OstWalletSettings.adoc[OstWallet Settings Documentation] for implementation details. - -=== 4. OstvTransaction Helper - Transaction and Add Session Integrated Workflow - -''' - -`OstTransactionHelper` is a transaction helper provided by the SDK that creates session keys before performing a transaction if needed. -App developers can configure the session creation parameters (session buckets) as per application's need. - -==== Implementation - -Please refer to xref:./documentation/OstTransactionHelper.adoc[Ost Transaction Helper Documentation] for implementation details. - -== Intermediate Usage - Ost Wallet SDK 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. - -Please refer to xref:./documentation/OstWalletUI.adoc[Ost Wallet SDK UI] for documentation. - -== Advance Usage - Ost Wallet Core Workflow APIs - -Ost core workflows API do not use any UI components, thereby giving complete ux control to the developers. -The xref:./documentation/OstWalletUI.adoc[`OstWalletSdkUI`] also uses Ost core workflows. - -Please refer to xref:./documentation/OstCoreWorkflows.adoc[Ost Core Workflow APIs] for documentation. - -== Known Issues - -=== Sdk Initialization Fails on Android 9 (API level 28) - -Starting with Android 9 (API level 28), https://developer.android.com/training/articles/security-config#CleartextTrafficPermitted[cleartext support] is disabled by default. -On the other hand, Ost Wallet Android Sdk leverages on *Public Key Pinning* to ensure the authenticity of a Ost Platform server's public key used in TLS sessions using https://github.com/datatheorem/TrustKit-Android[TrustKit]. -As TrustKit can only be inititialized with application's https://developer.android.com/training/articles/security-config[network security configuration], sdk initialization fails. -To work-around this issues, application needs to have TrustKit as a dependency and initialize it. - -=== Setup Device Workflow Fails on iOS-13 Simulator - -Ost Wallet Sdk uses iOS's https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/storing_keys_in_the_keychain[Keychain] to store user's cryptographic keys. -Unfortunately, Keychain doesn't work as expected on iOS-13 Simulators. -We request you to kindly test your application on actual iOS-13 device while we continue to look for a workaround. diff --git a/docs/modules/ROOT/pages/ios_setup.md.adoc b/docs/modules/ROOT/pages/ios_setup.md.adoc index 60ecb74..e131a7b 100644 --- a/docs/modules/ROOT/pages/ios_setup.md.adoc +++ b/docs/modules/ROOT/pages/ios_setup.md.adoc @@ -21,7 +21,7 @@ Add following entry in your `Cartfile` [source,bash] ---- - github "ostdotcom/ost-wallet-sdk-ios" == 2.3.6 + github "ostdotcom/ost-wallet-sdk-ios" == 2.4.1 ---- Now to actually install everything run the following in your terminal: