Installing the widget

📘

Objective and contents

At the end of this guide, you should be able to embed the hashmail widget into your dApp front-end.

Estimated time to complete this guide: ~10 min

Step 1 - Create a free account on hashmail dapp console

👋🏼If you have already setup your dapp on the hashmail console, please skip to step 2

• Get your access to the hashmail dapp console for free here
• Read this setup guide for step-by-step instructions to setting up your dapp console

Step 2 - Configure your widget theme 📚

The hashmail widget is fully configurable to your preferences. You can customize the color of the widget, and padding accoridng to your preferences

To get the widget to appear on your application, copy and paste the generated widget code (step 2 in the console; refer image above)

Include the hashmail script in your HTML head element i.e. just before the tag of your front-end

• A code snippet is given in your console (similar to the generic version below)
• Double-check that your dapp_id is correct, then paste the code just before the element in the root of your website
• When your page loads, this script will fetch the details of your widget configuration and load on your dapp website (on the bottom-right corner)

<script type="text/javascript">
    let dapp_id="<your-dapp-id>"; // replace with dapp_id provided by hashmail
!function(){window.hashmail||(window.hashmail=[]),window.hashmail.queue=[];let i=["load","identify","track"],t=function(i){return function(){a=Array.prototype.slice.call(arguments),a.unshift(i),window.hashmail.queue.push(a)}};for(var e=0;i.length>e;e++)window.hashmail[i[e]]=t(i[e]);hashmail.methods=i,window.hashmail.load=function(i){window.hashmail.dapp_id=i;var e=document,s=e.getElementsByTagName("script")[0],h=e.createElement("script");h.type="text/javascript",h.async=!0,h.src="https://widget.hashmail.dev/notifier_tracking_script.js",s.parentNode.insertBefore(h,s)},window.hashmail.identify=i=>{window.hashmail.wallet_address=i,localStorage.setItem("hashmail-wallet_address",i)},window.hashmail.load(dapp_id)}();
</script>

If you are using any SSR frameworks (e.g. NextJS, or Remix), you can paste this script tag at the root of your application

<script
    type="text/javascript"
    dangerouslySetInnerHTML={{
         __html: `let dapp_id="<your-dapp-id>"; // replace with dapp_id provided by hashmail
                            !function(){window.hashmail||(window.hashmail=[]),window.hashmail.queue=[];let i=["load","identify","track"],t=function(i){return function(){a=Array.prototype.slice.call(arguments),a.unshift(i),window.hashmail.queue.push(a)}};for(var e=0;i.length>e;e++)window.hashmail[i[e]]=t(i[e]);hashmail.methods=i,window.hashmail.load=function(i){window.hashmail.dapp_id=i;var e=document,s=e.getElementsByTagName("script")[0],h=e.createElement("script");h.type="text/javascript",h.async=!0,h.src="https://widget.hashmail.dev/notifier_tracking_script.js",s.parentNode.insertBefore(h,s)},window.hashmail.identify=i=>{window.hashmail.wallet_address=i,localStorage.setItem("hashmail-wallet_address",i)},window.hashmail.load(dapp_id)}();`,
                }}
></script>

👍

Checkpoint

At this point, you should see the widget on your front-end (see example below on the bottom right)

Step 3 - Call identify method a wallet address when connected 🤖

• The widget is currently in an anon state, i.e. no wallet is connected.
• To start displaying messages to the user, we need to identify the connected wallet.
• To identify a wallet, call the window.hashmail.identify method whenever a user connects their wallet. Typically this is done inside the function hook that handles state changes to the wallet connect / disconnect

window.hashmail.identify("<user-wallet-address>")

❔

Brief note on widget states

Till the identify method is called, the widget is in a 'anon' state, and any website visitors will not see any messages in the widget.

Whenever a wallet is connected, you need to call the identify method, by passing in the wallet address of the user. Once this method is called, the widget is 'authenticated'

Note: The first time a user connects, the user will be asked for consent to display messages. This is required for security and compliance (GDPR) requirements

Step 4 - Add a function call to disconnect ↪️

Once everything is set up, users will be able to see the messages / notifications in the widget. But it is necessary to disconnect the widget in case a user logout or disconnects the wallet.

This method needs to be called if a user goes to logged out states anytime on the application or disconnects the wallet.

Note: calling identify method again with a different wallet automatically overwrites the current wallet address

window.hashmail.disconnect();

Step 5 - All done ✅

Once you’ve completed the above steps, open your website and connect a wallet. Your widget should appear in the bottom right corner similar to the below image.

👀

More details

For further details on configuration and widget methods, check out our complete widget SDK documentation here.