Tag: QR Code

Send Sign Request As Push Notification: XUMM SDK

You have sent your first Payload request and also signed and/or rejected the sign request, by scanning the QR code. Now lets see how we can get user specific user token and start sending sign request as push notification to the end user.

Payload using create() method

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const payload = await Sdk.payload.create(request, true)
  console.log(payload)
}
main()

Above code is from our previous video tutorial where we sent our first payload using create method.

Video Tutorial: Send Sign Request As Push Notification: XUMM SDK


[youtube https://www.youtube.com/watch?v=4Wxcz0jvA9A]

YouTube Link: https://www.youtube.com/watch?v=4Wxcz0jvA9A [Watch the Video In Full Screen.]

Payload using createAndSubscribe() method

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const subscription = await Sdk.payload.createAndSubscribe(request, event => {
      console.log('New payload event',event.data)
  })
  console.log('sign request URL',subscription.created.next.always)
  console.log('Pushed ',subscription.created.pushed)
}

main()

Here we use createAndSubscribe() method instead of create() method. createAndSubscribe() also takes 2 arguments. The first argument is the payload information and the second argument is method/function that gets invoked every time the XUMM platform asynchronously sends an update about the created payload.

Running The Application

We issue the command node index.js to run our application and we get the following output:

sign request URL https://xumm.app/sign/e917182a-b64f-474d-ab24-8792d6b0ca6c
Pushed  false
New payload event { message: 'Welcome e917182a-b64f-474d-ab24-8792d6b0ca6c' }
New payload event { expires_in_seconds: 86399 }
New payload event { expires_in_seconds: 86384 }

Since main() is a asynchronous method and a child thread keeps waiting for Sdk.payload.createAndSubscribe() method to be resolved(it gets resolved once end user either signs or rejects the sign request, or when the payload expires). If we want to exit the waiting and kill the child process – get on the output terminal and press CTRL + C buttons(on windows PC).

The constant subscription(from above code) has information regarding the payload, payload status, signing URL, QR code information etc. Sdk.payload.createAndSubscribe() second argument keeps updating the payload status like expiration time until the user performs some action on the sign request. If user doesn’t perform any action until the payload gets expired, then the payload information gets expired and will be removed from the XUMM platform.

Once Payload is Resolved

Once user opens the QR code present on sign request URL(check above code output), scans it and signs or rejects the sign request, the method in seconds argument of Sdk.payload.createAndSubscribe() gets triggered and sends the updated status of the sign request.

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          console.log('New payload event',event.data)
          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
  })
  console.log('sign request URL',subscription.created.next.always)
  console.log('Pushed ',subscription.created.pushed)
}

main()

The Object.keys you see in above code is standard Javascript code. When we pass an object to it, and chain indexOf() method and pass the key name to indexOf() method, it returns the index position of that key in the object. Index starts from 0. So it returns the event.data if and when the user interacts with the payload QR code and either signs or rejects the payload. Until user performs some action with the generated payload, event.data will not have the key signed in its output.

Lets execute above code
We issue the command node index.js to run our application and we get the following output:

sign request URL https://xumm.app/sign/e917182a-b64f-474d-ab24-8792d6b0ca6c
Pushed  false
New payload event { message: 'Welcome e917182a-b64f-474d-ab24-8792d6b0ca6c' }
New payload event { expires_in_seconds: 86399 }
New payload event { expires_in_seconds: 86384 }

Copy the sign request URL from above output and past it in a browser and open your XUMM app in your phone, scan the QR code and sign or reject the sign request and look out for the status change.

Output when the sign request gets rejected

sign request URL https://xumm.app/sign/972d25fe-413a-48a3-8935-dd95c6cdf8ef
Pushed  false
New payload event { message: 'Welcome 972d25fe-413a-48a3-8935-dd95c6cdf8ef' }
New payload event { expires_in_seconds: 86399 }
New payload event { expires_in_seconds: 86384 }
New payload event { opened: true }
New payload event {
  payload_uuidv4: '972d25fe-413a-48a3-8935-dd95c6cdf8ef',
  reference_call_uuidv4: 'd81ae124-527d-40b6-ad38-c272f9b71134',  
  signed: false,
  user_token: true,
  return_url: { app: null, web: null },
  opened_by_deeplink: false,
  custom_meta: { identifier: null, blob: null, instruction: null }
}

As you can see in the output above, the payload event status shows when the user opened his/her XUMM app and scanned the QR code { opened: true }. In above case the end user has rejected the sign request, so the signed key has a value of false. The key opened_by_deeplink is new and is implemented in XUMM SDK 0.2.2 to further improve user flows – its value is null if unopened, true if opened using a mobile deeplink/push, false if QR scan opened. Technically it is present to let the developer know whether the sign request was opened from a deeplink URL or not.

Output when the sign request is signed

sign request URL https://xumm.app/sign/848ff099-4161-4911-a024-d27c15e87f62
Pushed  false
New payload event { message: 'Welcome 848ff099-4161-4911-a024-d27c15e87f62' }
New payload event { expires_in_seconds: 86399 }
New payload event { opened: true }
New payload event { expires_in_seconds: 86384 }
New payload event {
  payload_uuidv4: '848ff099-4161-4911-a024-d27c15e87f62',
  reference_call_uuidv4: 'bc98f5b6-d960-41a3-884a-3c9dced5b0e2',  
  signed: true,
  user_token: true,
  return_url: { app: null, web: null },
  opened_by_deeplink: false,
  custom_meta: { identifier: null, blob: null, instruction: null }
}

As you can see from above output, the value of signed is true. That means end user has successfully signed the sign request. Now we take the payload_uuidv4 value and fetch the user token from it.

Fetching user_token from payload_uuidv4

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000"
  }

  const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          // console.log('New payload event',event.data)
          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
  })
      console.log('sign request URL',subscription.created.next.always)
      console.log('Pushed ',subscription.created.pushed ? 'Yes' : 'No')

      const resolveData = await subscription.resolved
      if(resolveData.signed == false)
      {
          console.log('The sign request was rejected!')
      }
      else
      {
        console.log('The sign request was Signed!!')
        const result = await Sdk.payload.get(resolveData.payload_uuidv4)
        console.log('User_token: ',result.application)
      }
}

main()

We take another constant and await for subscription to be resolved. Once the end user signs the sign request we pass the resolveData.payload_uuidv4 information to Sdk.payload.get() which outputs a lot of json results. In that we pick up the user_token present under result.application as value for key issued_user_token.

Output of above code:

sign request URL https://xumm.app/sign/da54ac54-549f-42d2-a239-8ae6086eafbd
Pushed  No
New payload event { message: 'Welcome da54ac54-549f-42d2-a239-8ae6086eafbd' }
New payload event { expires_in_seconds: 86397 }
New payload event { opened: true }
New payload event { expires_in_seconds: 86382 }
The sign request was Signed!!
User_token: {
    name: 'My Super Duper App!',
    description: 'Demo App To Show New SDK Features',
    disabled: 0,
    uuidv4: '401015ee-7edc-4469-bdfd-3af11f229885',
    icon_url: 'https://xumm-cdn.imgix.net/app-logo/2a14d2f7-d0a8-432a-a40f-b45eddb70fc4.png',
    issued_user_token: '343a2f1e-8160-4984-a0f0-208086509617'
  }

In this we are interested in issued_user_token, which will be used to send push notifications to end user. To pick it up we write result.application.issued_user_token and store it inside the database.

Sending sign request as Push Notification

The user_token is a unique token for your XUMM app in combination with the specific XUMM user. To use the token to deliver a sign requst per Push notification, let’s adjust our first (minimal) sample payload or the ‘transaction template’ to include the user token:
This payload is XRPL specific

const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "10000",
  }

Now lets add user_token information to it.

{
  "txjson": {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "10000"
  },
  "user_token": "343a2f1e-8160-4984-a0f0-208086509617"
}

As you can see from above code, all the XRP Ledger specific payload information has been moved into a separate block under key txjson. All the other information outside of object txjson is specific to XUMM platform. Other XUMM platform specific information are: options, custom_meta and the user_token etc.

Stage is set to send sign request as Push Notification

Now lets use the user_token we received from our previously signed payload and use that in our final source code. Once you execute this final source code, the end user(user identified by user_token) will receive the sign request as push notification. Exciting!!

Source Code: To Send Sign Request As Push Notification: XUMM SDK

const {XummSdk} = require('xumm-sdk')
const {Txdata, TxData}  = require('xrpl-txdata')

const Sdk       = new XummSdk('401015ee-7edc-4469-bdfd-3af11f229885', '267b909b-0374-450b-a05b-5df60bc1f57a')
const Verify    = new TxData()

const main      = async() => {
    
      const request = {
        "txjson": {
            "TransactionType": "Payment",
            "Destination": "rwietsevLFg8XSmG3bEZzFein1g8RBqWDZ",
            "Amount": "1000000"
        },
        "user_token": "343a2f1e-8160-4984-a0f0-208086509617"
      }

      const subscription = await Sdk.payload.createAndSubscribe(request, event => {
          if(Object.keys(event.data).indexOf('signed') > -1)
          {
              return event.data
          }
      }) 
      console.log('sign request URL',subscription.created.next.always)
      console.log('Pushed ',subscription.created.pushed ? 'Yes' : 'No')

      const resolveData = await subscription.resolved
      if(resolveData.signed == false)
      {
          console.log('The sign request was rejected!')
      }
      else
      {
        console.log('The sign request was Signed!!')
        const result = await Sdk.payload.get(resolveData.payload_uuidv4)
        console.log('User_token: ',result.application.issued_user_token)
      }
}
main()

Here is the push notification on my phone
xumm sign request as push notification

We can click on the push notification bubble or open the XUMM App directly on our phone and navigate to “Events” tab and open the new sign request there and choose to sign or reject the request.

Output
The output of above source code will be same as we’ve posted previously for signing and rejecting the sign request. Now the only difference is, value of key pushed will be true as sign request was sent as push notification directly to the end users phone.

Important Note

Its best practice to check the value of key pushed in the output. If its false(maybe user revoked the permission), then its always good to show the user with the QR code to manually scan and make the payment. If value of pushed is false, that means the end user has not received the push notification.

For full “XUMM SDK/API” free video tutorial list visit: Working With XUMM SDK/API: XRPL

Your First Payload: XUMM SDK

Once we establish connection to the XUMM platform using XUMM SDK, its time to actually learn about sending payload. Payload is nothing buy “transaction template”.

What is a Payload or “Transaction Template”?

Think of Payload or “Transaction Template” as invoice. The minimum things which an invoice should include are:
1. What kind of an invoice it is.
2. The destination address for payment.

We could even leave the amounts section empty assuming that the client will fill it.

Simple Transaction Template

{
  "TransactionType": "Payment",
  "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT"
}

This is the bare minimal Payload or Transaction template we can write. It has transaction type and destination address(XRP address). The keywords “TransactionType”: “Payment” and “Destination” should be formatted as per XRP ledger transaction specifications.

If we don’t mention amount in our payload, end user can edit and enter the amount himself or herself after opening the payload request using their XUMM App. If we mention the amount in payload or transaction template, then he or she will not be able to edit it while signing.

Signing simply means authorizing the payment request. Or authorizing the sign request.

Sample Transaction Template With More Information

{
  "TransactionType": "Payment",
  "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
  "Amount": "1000000",
  "Memos": [
    {
      "Memo": {
        "MemoData": "F09F94A520546563686E6F7469702E636F6D"
      }
    }
  ]
}

Here we’ve explicitly mentioned the “Amount” which is 1 Million, which means 1 XRP. i.e., one XRP is one million Drops. And a Memo (HEX encoded string). TransactionType and Destination are mandatory fields, all other fields are optional.

Generating Memo(HEX encoded string)

const hex = Buffer.from('🔥 Technotip.com').toString('hex').toUpperCase()
console.log(hex)

Buffer is a nodejs packages built-in property, so you need not install any other packages once again.

Video Tutorial: Your First Payload: XUMM SDK


[youtube https://www.youtube.com/watch?v=RYAHzvUqM64]

YouTube Link: https://www.youtube.com/watch?v=RYAHzvUqM64 [Watch the Video In Full Screen.]

Things To Keep In Mind While Sending Payload

1. A payload (sign request) sent to the XUMM platform should be formatted as per XRP ledger transaction specifications, but some fields may be omitted as XUMM will automatically fill them in if able to do so.

2. Usually, a payload sent to the XUMM platform will be signed by the end user (e.g., for a sign in, subscription, payment, escrow creation etc). For this tutorial, you will be the initiator and the end user, either signing or rejecting your own payload.

3. The first sign request from a specific XUMM app will always have to be scanned using a QR code on the desktop. Once an end user trusts your application, by signing your sign request, your application can obtain a user specific user token to deliver future sign requests using push notification.

Source Code: Complete Code To Send Payload

const {XummSdk} = require('xumm-sdk')
const Sdk = new XummSdk('xumm-app-id', 'xumm-app-secret')

const main = async () => {
  const request = {
    "TransactionType": "Payment",
    "Destination": "rHdkzpxr3VfabJh9tUEDv7N4DJEsA4UioT",
    "Amount": "1000000",
    "Memos": [
      {
        "Memo": {
          "MemoData": "F09F94A520546563686E6F7469702E636F6D"
        }
      }
    ]
  }

  const payload = await Sdk.payload.create(request, true)
  console.log(payload)
}
main()

Here we are making use of Sdk.payload.create() method to generate sign request URL and QR code and other outputs. We pass 2 arguments to Sdk.payload.create(). First argument is the payload or the transaction template(in above code the constant by name request), and the second argument will be a flag (boolean, true) telling the code to return an error, if one occurs.

Running The Application

We issue the command node index.js to run our application and we get the following output:
payload

{
  uuid: '127287c3-bf55-40ee-b0ab-345f9edc8840',
  next: {
    always: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840'
  },
  refs: {
    qr_png: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840_q.png',    
    qr_matrix: 
'https://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840_q.json',
    qr_uri_quality_opts: [ 'm', 'q', 'h' ],
    websocket_status: 
'wss://xumm.app/sign/127287c3-bf55-40ee-b0ab-345f9edc8840'   
  },
  pushed: false
}

Your output will be different, and most part of this output will be unique. The output at payload.next.always is the sign request URL. payload.refs.qr_png is the QR code which has sign request information encoded. payload.pushed is false as this is the first time we are sending payload to the end user and we do not yet have the user token. We get the user token if the user successfully signs the sign request. We store this user token, which is specific to XUMM platform and from next time we can send sign request as push notification to the end users mobile device.

Action Steps

Now you can open YOUR payload output and navigate to payload.next.always or payload.refs.qr_png, open the XUMM app present on your mobile phone, scan the QR code and sign or reject the sign request and check for the status changes at payload.next.always URL.

Benefits of using XUMM Platform for our Application

1. DEX or any site can make use of XUMM “sign” transaction type for authorization – for example, for signing up for a DEX account or for creating an account on an app etc.

2. We can use XUMM platform to create and accept payments and/or subscription services.

3. Once the user signs/authorizes our first sign request, we can start sending payments/sign requests as push notification directly to their XUMM app in their mobile devices. That’s so convenient and seamless payments experience.

For full “XUMM SDK/API” free video tutorial list visit: Working With XUMM SDK/API: XRPL