Introduction

This documentation aims to help developers of decentralized application (DApp) to leverage the imToken DApp SDK.

In general, DApps need a host environment and the user's wallet to interact with. Just like for example Metamask, imToken is providing this environment within the imToken wallet app.

The imToken DApp browser lets your DApp interact in even more complex ways, than for would be possible with other tools like Metamask.

To keep it simple, this documentation uses DApp browser to represent the imToken DApp browser and DApp to represent DApp webpage.

Provider

imToken currently support Ethereum and EOS DApps.

DApp browser has the compatibility of Metamask, your DApp should naturally work with imToken if it is compatible with Metamask as well.

DApp browser also support Scatter, you can develop your EOS DApp with ScatterJS，and run inside imToken DApp browser.

⚠️ note: for ScatterJS, right now, we noly support `scatter-core` version < 2.3.8, you should use the apis in scatter 2.3.8, like `getIdentity`、`forgetIdentity`, you can't use the new api like `login`、`logout`.

The interaction between DApp browser and DApp is base on EIP1102 ，DApp must implement EIP1102 to get user account and send transaction.

⚠️ DApp browser do not inject web3 into dapp page any more， we just inject a simple `provider`， DApp should enable it first to get full provider features：

callAPI

We provide a serie of methods that enhance the capacity of your DApp. Each method has an apiName. Please use as follows:

imToken.callAPI(apiName, options, callback)

Params

Type

Description

apiName

string

name of the method which you want to invoke, you will see the available apiNames below

options

object

options depend on the specific method

callback

function

callback of method

The callback function follows the style of NodeJS. The first param passed to the callback function is always an error object (if no error occurred, it is null), the error object always has a message property. The second param is the successful result returned by API call.

Note: To use callPromisifyAPI, your DApp must include a Promise polyfill ( such as es6-promise) already.

API

transaction

web3.eth.sendTransaction

The most common operation of a DApp is to send a transaction, which has the method web3.eth.sendTransaction in web3.js. The DApp browser listens to this method being invoked by the DApp and displays relevant information to the user. Users then type in their password for approval, send the transaction and get the txHash if the transaction succeeded or an error if failed.

error handle

The DApp browser only handles a part of errors (such as a password error). Most transaction errors will be returned to the DApp itself. Therefore, DApps should always handle the error and display the message to users directly.
imToken handles the i18n of the error message, which is why the DApp can simply use the alert message in most cases.

There is a special case though: The DApp browser will return an error in case of the user canceling the operation, for which you don't need to show an alert message. If you are getting an error, please check the error codes to decide how to proceed.

gas

We recommend that DApps should always set gas and gasPrice when sending transactions, because the DApp developer usually knows the accurate value. If you don't set a gas param, imToken uses web3.eth.estimateGas to estimate a value of gas.

transaction.signTransaction

signTransaction only signs the transaction, but doesn't send. It directly returns the signature.

transaction.signTransaction

varparams={to:'0x0fa38abec02bd4dbb87f189df50b674b9db0b468',from:web3.eth.defaultAccount,value:'1250000000000000',memo:'buy a cup of coffee',feeCustomizable:true,}imToken.callAPI('transaction.tokenPay',params,function(err,signature){if(err){alert(err.message)}else{alert(signature)}})

navigator

navigator.getOrientation

get the current orientation state of APP，return 'LANDSCAPE' or 'PORTRAIT'

it will display a wallets selector on the user's device, after the user selected, it returns the selected wallet address, if the user canceled the selector, it returns the current wallet address of wallet, it might be one of ETHEREUM/EOS/BITCOIN wallet address.

if you only want to display bitcoin wallet addresses in the wallet selector, you can change the chainType value from null to 'BITCOIN'.

device

device.getCurrentLanguage

Gets the user's current language setting. If your DApp should support multiple languages, this information may be useful, but we have added the locale parameter to the DApp's url. In most cases you do not need to call this API.

error code

error code

Description

1001

user canceled the operation

debug

You can add an param url ___debug to your DApp url (like: https://ens.token.im/?___debug=1), it will inject an console panel into your page，you can find a vConsole button in the bottom right corner of page, it will open a panel after click (like chrome developer panel).

multi-language support

When user open a DApp, we set the accept-language http request header of the url request, the value is depend on imToken APP language, such as:

Accept-Language: zh-CN,zh;q=0.9,en-US;q=0.8,en;q=0.7,*;q=0.6

We recommend you detect this value first, otherwise you can detect language form url, we will and a locale params to it (like : https://ens.token.im/?locale=en-US)

example

You can find the API example here. Feel free to test the examples within your imToken App.