xApp Xumm UI interaction

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>
<script>
  const xapp = new xAppSdk()
</script>

🚧
Warning!
Please note the new xAppSdk() constructor needs to be called before interacting with the SDK. Constructing on demand upon first interaction will not work reliably.
It's best to initialize the SDK as soon as your webapp/page is being loaded, straight after the xApp SDK for Javascript has been loaded.

Initialize the xApp SDk

// 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:

Resolve the xApp loading screen (opt in) `ready` (2.5.0+)

When using the native Xumm loader screen for your xApp (until your xApp is ready, fully hydrated, booted, etc.) you call this method to remove the Xumm loading screen.

To prevent showing a double loader (first the Xumm xApp loader, then your xApp's loader while hydrating / booting) you can enable the "Xumm Loader Screen" option in the Xumm Developer Console (xApp tab). The xApp will then show the Xumm native loader, until your application calls the ready() method on the Xumm SDK.

Syntax

First your app loads, fetches, etc. Then you have all the information you need to render & show your app, and you call:

xumm.xapp.ready()

The xApp doesn't load, to be able to debug the app needs to be displayed (e.g. reverse proxy 502 error or some other app error, preventing the SDK's ready() call being made).

With Xumm in Developer Mode, the Xumm loading screen shows a 'Proceed to xApp' button at the Xumm loader screen, below the spinner. This way you can dismiss the Xumm loader and view the underlying problem.
The xApp takes very long to load or doesn't load at all: users are confronted with a long wait.

If the ready() method in the Xumm SDK isn't called within ~6 seconds a label + button is made visible: "xApp is slow to respond..." [Contact Developer]. This button then opens the Support URL for the xApp as entered in the Developer Console.

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.

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.

If you want to request the destination address only, skipping the "Destination Tag" required check & input, you can provide the ignoreDestinationTag param. If not provided (or false) Xumm will chech if the destination account requires a Destination Tag and ask the user to input one.

xapp.selectDestination({ ignoreDestinationTag: false })
  .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:

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 code`scanQr`

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.

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:

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

Open the native OS 'Share' dialog

Available starting Xumm version 2.4.0

xapp.share({
    title: 'Some Title',
  text: 'Some Text',
  url: 'https://xumm.app/?q=I+shared+this'
})

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

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.

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

xapp.on('payload', function (data) {
  console.log('Payload resolved', data)
})

{
  "reason": "DECLINED"
}

{
  "reason": "SIGNED"
}

QR Code scanner opened & scanned / closed

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

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

xApp SDK for Javascript

🚧Warning!

Initialize the xApp SDk

Trigger actions

Resolve the xApp loading screen (opt in) ready (2.5.0+)

Syntax

Open a Sign Request (payload) openSignRequest

Pick an XRPL Destination Account selectDestination

Open an URL with the OS Browser openBrowser

Scan a QR codescanQr

Open the Transaction Details panel tx

Open the native OS 'Share' dialog

Close the xApp close

Navigate to another xApp navigate

Receive events / data

Payload resolved

QR Code scanner opened & scanned / closed

Destination picker: closed / destination picked

🚧
Warning!

Resolve the xApp loading screen (opt in) `ready` (2.5.0+)

Open a Sign Request (payload) `openSignRequest`

Pick an XRPL Destination Account `selectDestination`

Open an URL with the OS Browser `openBrowser`

Scan a QR code`scanQr`

Open the Transaction Details panel `tx`

Close the xApp `close`

Navigate to another xApp `navigate`