@ibct/ledgis-wallet-plugin v1.0.1
LEDGIS Wallet Plugin for JS based Applications
This library is meant to be used together with applications that are planning to integrate LEDGIS Mobile wallet into their respective applications. Target release platforms are JS based Web Apps and Hybrid mobile frameworks such as React Native to seamlessly integrate wallet functions.
This library utilizes the Authentication Protocol Specified by EOSIO. According this specification, three major components are involved when authenticating, or signing transactions.
A simple Websocket Relay that serves the purpose of the Callback server can be found here
Integration Guide for Web Apps and dApps
This section shows how to authenticate and sign transactions using LEDGIS Wallet throughw dApp or Web App.
Use
npm
oryarn
to install the package.yarn add @ibct/ledgis-wallet-plugin
Import the package.
import ecrx from '@ibct/ledgis-wallet-plugin';
Initialize the instance
const options = { webSocketURL: 'ws://192.168.1.78:1337', callback: this.callback, fallbackURL: 'https://dapp.io/fallback', appName: 'myapp' } const ledgisObj = new ecrx(options); window.ledgis = ledgisObj;
- webSocketURL: URL of the webSocket that acts as the relay from LEDGIS wallet to your dApp/Web App. Secured wss ports are recommended.
- callback: A callback function that is essential on your dApp/Web App that will listen to incoming messages via the websocket. You need to implement this.
fallbackURL: A fallback URL to return from LEDGIS Wallet from once the request has been fulfilled or rejected.
Depending on the application and the platform, the fallbackURL may differ.
Client - Platform fallbackURL Safari - iOS http://dapp.io/fallback
Chrome - iOS googlechrome://dapp.io/fallback
googlechromes://dapp.io/fallback
Firefox - iOS, Android firefox://open-url?url=http://dapp.io
Native App - iOS, Android myapp://fallback
Calling applications should provide correct URI schemes depending on the client platform.
It's strongly recommend that you keep the created plugin object in a global scope to avoid making a new websocket connection with each request.
For subsequent requests, simply use
window.ledgis
object.Invoking wallet on a certain action.
Authenticating and getting user account info
// generate URL to invoke depending on the required action const location = ecrxObj.getAccount(); // on Web window.location = location; // on React Native Linking.openURL(location);
Once the request has been fulfilled by LEDGIS wallet, the response will be passed on to the callback function.
const callback = (res) => { console.log(res.data); // Do stuff }
Note on dApps on iOS using Ledgis Wallet Plugin
On iOS, native applications are unable to keep a WebSocket connection open for more than 30 seconds due to resoure limitations. To tackle this issue, native dApps can utilize application state to reconnect to websocket.
For React Native, a guide on App States can be found here
Sample code on how to utilize this function,
ledgis.reconnectWebSocket()
.then(() => alert('connected'))
.catch(e => alert(e));
Initializing a new ledgis object will discard old responses, and the cache will be invalidated. Therefore, reconnecting to the existing websocket should suffice.
Integration Guide for LEDGIS Wallet
This section is for LEDGIS Wallet developers to integrate communication protocols to authenticate transactions, allowing full-duplex communication between dApps/Web Apps and LEDGIS Wallet.
Use
npm
oryarn
to install the package.yarn add git+https://github.com/nuwanwre/ecrx-wallet-js-sdk.git
Import the package.
import ecrx from '@ibct/ecrx-wallet-sdk';
Initialize the instance
// Get the URL obtained via deep-linking // Linking.getInitialURL() <-- React Native const request = ecrx.parseRequest(url); const options = { webSocketURL: request.payload.callbackURL, } // Initialize ecrx object const ecrxObj = new ecrx(options);
- webSocketURL: URL of the webSocket that acts as the relay from LEDGIS wallet to relevant dApp/Web App.
Completing a request
// Sample get account eosRpc.get_account('testaccount123').then(res => { const accData = `account: ${res.account_name}\nbalance: ${ res.core_liquid_balance }`; const response = { requestId: request.requestId, success: true, data: accData, } ecrxObj.sendResponse(JSON.stringify(response)); });
- sendResponse: Returns a JSON Object to callbackURL
- requestId: requestId originally specified by incoming deep link
Complete API reference
Assume ledgis
is previously instantiated object.
getAccount()
- Invokes Ledgis wallet to get Account informationGet account action requires that the requesting app provide Chain ID of the blockchain.
Login Request
const loginURL = window.ledgis.getAccount('<chainID>'); window.location = loginURL; // Web only Linking.openURL(loginURL).catch(err => // React-Native only // Handle errors );
sendAction()
- Invokes Ledgis wallet on a certain action that can operate on the chainAction requests follows the eosjs format
Transfer Request
const txReq = { currentAccount: 'test112.ibct', action: { actions: [{ account: 'led.token', name: 'transfer', authorization: [{ actor: 'test111.ibct', permission: 'owner', }], data: { from: 'test111.ibct', to: 'test112.ibct', quantity: '1.0000 LED', memo: 'Signed with Ledgis Mobile', }, }] } } const txURL = window.ledgis.sendAction(txRequest); window.location = txURL; // Web only Linking.openURL(txURL).catch(err => // React-Native only // Handle errors );
Stake Request
const txRequest = { currentAccount: 'test111.ibct', action: { actions: [{ account: 'led', name: 'delegatebw', authorization: [{ actor: 'test111.ibct', permission: 'owner', }], data: { from: 'test111.ibct', receiver: 'test111.ibct', stake_net_quantity: "1.0000 LED", stake_cpu_quantity: "1.0000 LED", transfer:false }, }] } const txURL = window.ledgis.sendAction(txRequest); window.location = txURL; // Web only Linking.openURL(txURL).catch(err => // React-Native only // Handle errors );