xApp Xumm UI interaction

Using the xApp Typescript/Javascript SDK, you can trigger native Xumm interaction & receive events from Xumm in your xApp.

xApps are WebApps, embedded in XUMM for a great user experience. They add value (tooling, wizards) for end users, using Sign Requests and their Web UI to help users perform tasks on the XRPL and beyond.

To add value for end users, your xApp will most likely implement some of the features Xumm offers natively in your xApp. E.g. open the QR scanner, Account Destination Picker, or start a Sign Request flow. Then to receive the response from these native Xumm flows in your xApp (WebApp).

Your xApp can trigger specific actions in Xumm:

These actions can be sent form your xApp (frontend Javascript) context, and will trigger functionality native to the Xumm app:

  • Open a Sign Request
  • Open the QR scanner to retrieve a scanned value
  • Open the Account Destination Picker
  • etc.

Your xApp can also receive events (data) from Xumm:

Certain actions in Xumm will trigger an event so your xApp can retrieve data or act based on the event (details below):

  • Payload resolved
  • QR Code scanner opened/closed
  • Destination picker: closed / destination picked

xApp SDK for Javascript

To interact with the Xumm platform, you can use the Javascript Xumm SDK from your frontend. To trigger actions in Xumm and receive events from Xumm, you need the xApp SDK.

<script src="https://xumm.app/assets/cdn/xumm-xapp-sdk.min.js"></script>

npm versionnpm version

Initialize the xApp SDk

const xapp = new xAppSdk()

// Now you can trigger events on the xApp object and subscribe:

// Trigger xApp Navigation
xapp.scanQr()
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('scanQr response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))
  
// Listen for events
xapp.on('qr', function (data) {
  console.log('QR data:', data)
})

With the xApp SDK included in your frontend projects, you can create a new instance of the xumm-xapp-sdk and start sending actions to Xumm & listening for events.

Trigger actions

To trigger a UI flow / features on the native side of the Xumm app, you can call these methods:

Open a Sign Request (payload) openSignRequest

Open a Sign Request (payload) using the Payload UUID. Either obtained from your own backend calling the Xumm API / SDK, or obtained by using the Javascript Xumm SDK from your frontend

Requires using the Receive events/data flow to capture the asynchronous response data.

const xapp = new xAppSdk()

xapp.openSignRequest({ uuid: '...' })
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('openSignRequest response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Pick an XRPL Destination Account selectDestination

To select a destination XRP Ledger account, either from the user's contact list, own accounts or by having the user manually entering/pasting/scanning one.

Requires using the Receive events/data flow to capture the asynchronous response data.

const xapp = new xAppSdk()

xapp.selectDestination()
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('selectDestination response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Open an URL with the OS Browser openBrowser

You should not send/redirect users to public browser URL's (you can but shouldn't, this will be disabled in a future Xumm release). Instead, trigger a confirmation dialog using the openBrowser method:

const xapp = new xAppSdk()

xapp.openBrowser({ url: '...' })
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('openBrowser response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Scan a QR codescanQr

To open the native Xumm QR reader. The native Xumm QR reader will automatically parse destination accounts to account, destination tag, etc.

Requires using the Receive events/data flow to capture the asynchronous response data.

const xapp = new xAppSdk()

xapp.scanQr()
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('scanQr response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Open the Transaction Details panel tx

After a transaction has been executed (sent, submitted to the ledger) you can open the Xumm Transaction Details panel:

const xapp = new xAppSdk()

xapp.tx({ account: '...', tx: 'HASH...' })
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('tx response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Close the xApp close

Programmatically close the xApp, e.g. after informing the user a UI flow is done and and there's nothing left to do in your xApp for end users. If you want to trigger a "Event List" refresh after closing the xApp (e.g. to catch up with transactions made with your xApp), add the refreshEvents param (optional).

const xapp = new xAppSdk()

xapp.close({ refreshEvents: true })
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('close response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Navigate to another xApp navigate

You can programmatically send users to another xApp by xApp identifier. This is only available for whitelisted xApps.

const xapp = new xAppSdk()

xapp.navigate({ xApp: '...' })
  .then(d => {
    // d (returned value) can be Error or return data:
    console.log('navigate response:', d instanceof Error ? d.message : d)
  })
  .catch(e => console.log('Error:', e.message))

Receive events / data

When a payload has been resolved, a QR code has been scanned or a Destination has been picked, Xumm will send an event containing the event response data:

Payload resolved

const xapp = new xAppSdk()

xapp.on('payload', function (data) {
  console.log('Payload resolved', data)
})
{
  "reason": "DECLINED"
}
{
  "reason": "SIGNED"
}

QR Code scanner opened & scanned / closed

const xapp = new xAppSdk()

xapp.on('qr', function (data) {
  console.log('QR scanned / cancelled', data)
})
{
  "qrContents": "the://scanned-qr/contents?...",
  "reason": "SCANNED"
}
{
  "qrContents": null,
  "reason": "USER_CLOSE"
}
{
  "qrContents": null,
  "reason": "INVALID_QR"
}

Destination picker: closed / destination picked

const xapp = new xAppSdk()

xapp.on('destination', function (data) {
  console.log('Destination picked/cancelled', data)
})
{
  "reason": "USER_CLOSE"
}
{
  "method": "selectDestination",
  "destination": {
    "address": "r...",
    "tag": 123456,
    "name": "Wietse's Savings"
  },
  "info":{
   "blackHole":false,
   "disallowIncomingXRP":false,
   "exist":true,
   "possibleExchange":false,
   "requireDestinationTag":false,
   "risk":"UNKNOWN"
  },
  "reason": "SELECTED"
}