NAV
Im token logo imToken API Documentation Tokenlon-SDK DApp-SDK
typescript
  • Introduction
  • Provider
  • callAPI
  • API
  • 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.

    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

    import Web3 from 'web3.js'
    
    if(window.ethereum) {
      window.ethereum.enable().then(accounts => {
    
        console.log(accounts) // got user accounts
    
        window.web3 = new Web3(window.ethereum) // init web3 object
    
        web3.eth.sendTransaction({...}, (txId) => { // send transaction
    
          console.log(txId)
    
        })
      })
    }
    

    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)
        }
      })
    

    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