NAV
Im token logo imToken API Documentation Tokenlon-SDK DApp-SDK
typescript
  • Introduction
  • Provider
  • callAPI
  • API
  • debug
  • multi-language support
  • example
  • English

    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.

    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:

    👉 You can also check the related documentation of metamask

    window.addEventListener('load', async () => {
      // Modern dapp browsers...
      if (window.ethereum) {
        window.web3 = new Web3(ethereum);
        try {
          // Request account access if needed
          await ethereum.enable();
          // Acccounts now exposed
          web3.eth.sendTransaction({/* ... */});
        } catch (error) {
          // User denied account access...
        }
      }
      // Legacy dapp browsers...
      else if (window.web3) {
        window.web3 = new Web3(web3.currentProvider);
        // Acccounts always exposed
        web3.eth.sendTransaction({/* ... */});
      }
    });
    

    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.

    callAPI

    imToken.callAPI(apiName, params, (error, result) => {
      if(error) {
        alert(error.message)
      } else {
        alert(result)
      }
    })
    

    Another way to call a method is by using callPromisifyAPI. This will do the same things as callAPI, and may be useful if you want to call the API with Promise style:

    callPromisifyAPI

    imToken.callPromisifyAPI(apiName, params).then(result =>
      alert(result)
    ).catch(error => {
      alert(error.message)
    })
    

    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.

    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

    var params = {
      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)
      }
    })
    

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

    navigator.getOrientation

    imToken.callAPI('navigator.getOrientation', function(err, result) {
      console.log(result)
    })
    

    set the orientation of APP,

    navigator.setOrientation, param is 'landscape' or 'portrait'

    imToken.callAPI('navigator.setOrientation', 'landscape')
    

    Close the current DApp window.

    navigator.closeDapp

    imToken.callAPI('navigator.closeDapp')
    

    Navigate to the previous history of the current webpage, like history.go(-1). If there is no previous record, the method closes the current DApp window.

    navigator.goBack

    imToken.callAPI('navigator.goBack')
    

    native

    native.alert

    Displays a native alert dialog to show a message, like window.alert.

    Params Type Required Default Description
    message string true null message to show

    native.alert

    imToken.callAPI('native.alert', 'winner winner, chicken dinner!')
    

    native.confirm

    Displays a native confirm dialog, like window.confirm. If the user clicked the cancel button, an error will be returned to the callback function.

    Params Type Required Default Description
    title string true null dialog title
    message string true null dialog content
    cancelText string true null cancel button text
    confirmText string true null confirm button text

    native.confirm

    imToken.callAPI('native.confirm', {
      title: 'quick question',
      message: 'is Javascript the worst language?',
      cancelText: 'no',
      confirmText: 'yes',
    }, function(err, result) {
      if(err) {
        console.log('no')
      } else {
        console.log('yes')
      }
    })
    

    native.selectPicture

    Select a picture from library or take a photo. It will return image data in base64 (jpeg default).

    Params Type Required Default Description
    maxWidth number false null response will be corpped
    maxHeight number false null response will be corpped
    allowsEditing boolean false false enables built-in iOS functionality to resize the image after selection
    quality number false 1 quality of image, range of value is 0 to 1

    response:

    property Type Description
    data string base64 data, default prefix 'data:image/jpeg;base64,'
    width number image width
    height number image height
    fileSize number file size (b)

    native.selectPicture

    imToken.callAPI('native.selectPicture',{
      maxWidth: 400,
      maxHeight: 200
    }, function (err, ret) {
      if(err) {
        alert(err.message)
      } else {
        document.getElementById('imgContainer').src = ret.data
      }
    })
    

    native.setClipboard

    Sets a text to the user's clipboard.

    Params Type Required Default Description
    text string true null text to set

    native.setClipboard

    imToken.callAPI('native.setClipboard', 'are you ok?')
    

    native.share

    Opens the native share component.

    Params Type Required Default Description
    title string true null title
    message string true null content
    url string true null link. If you want to share an image, set url to base64 data

    native.share

    imToken.callAPI('native.share', {
        title: 'dapp example',
        message: 'this is example of dapp sdk',
        url: location.href,
      }, function (err, ret) {
        if(err) {
          alert(err.message)
        } else {
          alert('share success!')
        }
      })
    

    native.scanQRCode

    Opens a scanner to scan a QRCode. Returns string content of the QRCode.

    native.scanQRCode

    imToken.callAPI('native.scanQRCode', function (err, text) {
        if(err) {
          alert(err.message)
        } else {
          alert(text)
        }
      })
    

    user

    user.showAccountSwitch

    Open a wallet selector modal. Returns a wallet address.

    user.showAccountSwitch

    imToken.callAPI('user.showAccountSwitch', { chainType: null }, function(err, address){
      if(err) {
        alert(err.message)
      } else {
        alert(address)
      }
    })
    

    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.

    Available locale:

    device.getCurrentLanguage

    imToken.callAPI('device.getCurrentLanguage', function(err, language) {
      if(err) {
        alert(err)
      } else {
        alert(language)
      }
    })
    

    device.getCurrentCurrency

    Gets the user's current currency setting.

    Available currencies:

    device.getCurrentCurrency

    imToken.callAPI('device.getCurrentCurrency', function(err, currency) {
      if(err) {
        alert(err)
      } else {
        alert(currency)
      }
    })
    

    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.