Hooking up HandCash Connect
If you read the title and thought this writing might have something to do with extracurricular dating activities, I have to say, I am sorry to disappoint you — your dirty mind must look elsewhere. The only intimate connection shared here is about my recent rendezvous with a pretty little thing named HandCash. (Hmm, perhaps I should reword that…)
Using a little less lingo, this writing is about my experience integrating ‘HandCash Connect’ into a Social Media web application, with HandCash being an NPM package + API that developers can use for user authentication and payment enablement. Basically, it’s a Bitcoin wallet on steroids.
My plan with HandCash is to build an application where people can post content and earn money (Bitcoin) from other users who appreciate their efforts. Direct, peer-to-peer, no middlemen attached. That’s the payment part of the scheme that HandCash enables, which I haven’t “hooked up” quite yet.
However, I did hook up the user authentication feature, and I’ll share those incredibly vivid details now. And let me tell you, you’re in for one mind-blowing experience — assuming you’re into this sort of thing.
HandCash Connect step-by-step tutorial
To start, you need to create a developer account and add your application to their app store. This can be done here: https://dashboard.handcash.dev/#/. After doing this, you’ll receive an App ID which will be used to communicate with their API. I saved the App ID in my .env file.
The next step is to review their installation docs, found here: https://docs.handcash.dev/installation/. Following the docs, add the NPM package to your project.
Then, to create a HandCashConnect instance, you’ll need to require the package, and your App ID will come into play thereafter. With this instance, you’ll be able to setup your user authentication.
But before diving further, you will want to create a button on the frontend that redirects the user to the HandCash page with your App ID. Upon redirection, the user is prompted to confirm whether they want to authenticate into your app or not. If they do, HandCash redirects them to a predefined URL, with the authToken included in the link. Put in bullet point format:
1. User clicks “HandCash login” button
2. Their browser redirects to HandCash’s verification page with the App ID
3. User Accepts or Declines authenticating into your App
4. If they Accept, HandCash redirects their browser and sends them to your predefined URL, with the authToken included in the link. In my case, I chose http://localhost:3000/authenticate as my predefined URL, since I’m in a testing environment.
Since most people are visual learners, I’ll continue this tutorial with images of code.
When this button is clicked, my “signIntoHandCash” function is called. This function triggers an Axios-to-Express, frontend-to-backend communication.
Note: The Promise.all() isn’t necessary since there’s only one asynchronous function to return, but it works just fine so cut me some slack. And perhaps this functionality doesn’t need the frontend-to-backend communication, but that’s where process.env works, so that’s why I went through with it.
Moving forward, once ‘redirectionLoginUrl’ is sent back to the frontend, I send that URL to the user’s browser via the window.location.assign() function. Then, they’re on HandCash’s page to accept or reject the app. Here’s what the page looks like:
Once Authorized, HandCash redirects the browser to my ‘http://localhost:3000/authenticate’ route, and this is where we can find our beloved authToken.
Since I’m using React, I render my <AuthenticatePage> component at the /authenticate route, and when the component mounts, I run an authenticateUser() function that verifies the validity of the token, then if valid, logs the user into the application. Otherwise, they’re redirected to the home page.
Once again, the frontend and backend are communicating, and the corresponding backend function is found below. For reasons of brevity, I don’t include the code that interacts with the database. Just know that I ‘res.json’ the ‘publicProfile’ that HandCash provides, after the user’s profile is retrieved with the authToken.
Once the user is authorized, I save the authToken to localStorage for future use, and redirect them to their profile page, as the ‘authenticateUser’ function outlines above.
With this, you have your authentication configured, and from there, you can integrate it as you like. If you need any further supplements, take a look at the docs, or HandCash’s Brandon Cryderman’s tutorial videos, found here. That should be all you need.
Reflecting on the rendezvous
Mind-blowing, yes? (Hopefully.) To me, the most mind-blowing part was how easy it was. The hooking up phase came and went very quickly once the connection was made. Granted, before I started playing around with it I was a bit nervous and intimidated (it was my first time after all), but once we became intertwined, I found my groove and finished the job.
All innuendo aside, it really was easy to integrate. To get the user authentication going, you only need a few lines of code. It wasn’t tricky at all. The tricky thing for me was deciding how to store the token. Do I use the very easy Local Storage, or do I learn how to use Cookies? After hours of research into the subject and XSS + CSRF attacks, it seems Cookies are probably the safest bet, but with React and the domPurifying protection I have, I might be fine with good ol’ Local Storage. Session Storage was dead on arrival as I don’t want to force users to re-login every time they come to the website. That’s annoying and makes for a poor user experience. (If you’re a developer, I would be interested in your thoughts on the subject.)
As user experience is something I care about deeply, the decision to integrate HandCash did not come lightly. I chose them for good reason. Their Bitcoin wallet UI/UX is the best there is. Aside from their sleek interface, with their $handle system, they made the typical copy/pasting of super long Bitcoin addresses a thing of the past (send to $Brandon rather than 23j4l2k3i4h23io4g2o3iugo23ig423f2f), and they’ve removed the annoying requirement that users must write down “seed words” in case they forget their password. It’s no longer necessary with HandCash. Simply put, the user experience with Bitcoin is one your average everyday person would expect, and since that is who my apps are geared towards, the HandCash NPM Package and API is exactly what I need. Thank you HandCash team for delivering such an excellent product.
And now, it’s time for the payment enablement phase with that pretty little thing named HandCash. Writing hat off, coding cap on. Talk later.
- Sam
