Dapplets × NEAR example

Dapplets × NEAR example is a Dapplet (an Augmentation App) that can parse Twitter posts and store them in the NEAR contract. It can also display your saved tweets on the overlay page.

1. Introduction

Dapplets – applications that interact with web-pages, augment them by inserting different widgets, parse the pages’ data and add some new functionalities. They can improve the user experience when using social media, video services and other sources.

Dapplets use the extension we are creating. This extension gives a simple API for dapplets developers and big abilities for the dapplets community. Our platform is decentralized. We use NEAR and Ethereum networks for our registries and contracts. We also use decentralized storages, like Swarm, IPFS and SIA for hosting dapplets code and multimedia.

To use our platform at first you need to install the Dapplets Extension . Currently it’s in the alpha-stage and is not published to Google Chrome or any other store. To install it follow this steps:

1. Open one of the following browsers: Google Chrome, Firefox, Brave, Tor.

The following steps are described for Google Chrome. The steps may differ in other browsers.

2. Download the Dapplets Browser Extension.
3. Open chrome://extensions in a new tab.
4. Switch the Developer mode on and press F5 to refresh the page.
5. Drag and drop the downloaded file into the extensions page. The extension will install automatically. If you are using Ubuntu or possibly another Linux OS the Dapplets extension can disappear from the Chrome Extensions after restarting the PC. To avoid this unzip the archive and use the Load unpacked button to add the extension.
6. Click to the Dapplets extension icon in extension bar. Try Dapplets × NEAR example dapplet.

2. Tutorial

Let’s study how this dapplet works and why Dapplets is a NEAR frendly platform.

The goal of this example is to show the interaction between NEAR and Dapplets. If this is your first encounter with Dapplets we recommend trying our documentation first. It contains several exercises that explain how to create dapplets and adapters, from simple to complex ones. We highly recommend going through the ex01 and ex04 examples that describe how to create the most basic dapplets and dapplets with an overlay. The knowledge you will get will make it easier to understand the current example.

The initial code for this example is in a separate branch: exercise

You can clone this repo. It won’t work directly. Try following steps to start it.

Let’s look at the structure. There are three components: dapplet, overlay and contract.

Dapplet is the entry point of the application. It uses adapters for interaction with web-pages, defining contexts to augment and widgets to insert. You can find the core functions of the extension inside a dapplet. We use TypeScript in our project.

We define Overlay as a place where a user can do something with parsed data, connect to core dapplet’s functions through the dapplet bridge and manage augmentation parameters. It is an impotrant part of the application, but it runs in another environment and is published as a separate bundle. In most cases we use React as one of the most popular frameworks. But you can use a framework that you prefer or pure JavaScript or TypeScript.

Contract does not connect directly with other modules and may be located outside of the dapplet. However, this simple NEAR contract is created specifically for this dapplet. This is why it’s convenient to place it in the application structure.

Let’a look at the each module.

2.1. Dapplet

Look at the /dapplet/src/index.ts.

At first we create injectable class with decorator @Injectable and use @Inject to add the Twitter Adapter as the adapter class variable. Also create activate method. It runs when the selected adapter finds specific context and is loading. It will contain all the main logic.

Add the button to every tweet. Put this code to the activate:

Look at the code. We get widget button from the adapter. Then run adapter’s method attachConfig. It receives an object with the names of contexts, that will be used, as keys. Values are functions that receive parsed context as the only argument and return a widget or an array of widgets. You may also return null, false or undefined.

Widget is a function that receives an object consisting of widget states. State parameters are described in the adapters documentation. You can find Twitter Adapter documentation here. In our case we add an image to the button and tooltip. exec is a function that runs when clicked. Now we just show the parsed context in the console.

Run the dapplet:

⚠️ Since the browser is blocking pages with problematic security certificates, go to https://localhost:3001/dapplet.json when the application is running and agree to run in insecure mode

Open the extension. Go to Developer tab and turn on the development server: https://localhost:3001/dapplet.json.

Turn on the Dapplets tab. You will see the dev badge near our dapplet. Turn it on.

Now you can see additional buttons on our tweets. Click on the button and open the console. You will see the parsed context of the tweet.

You’ve done it! Congratulations!!! Go back to the code.

We want to show parsed data not in the console but to the users. We will use an overlay for this. But before implementing the overlay, add the interaction logic between the dapplet and the overlay to the dapplet.

Let’s change our code. Add private class variable _overlay of type any. In the activate add the following code:

Core function Core.overlay (typing problems will be fixed soon) receives an object with a name of the overlay and an overlay title and returns the Overlay object which we save in the _overlay variable.

Let’s add openOverlay method to the class:

In this example we call the method send the overlay. It takes two arguments: the name of this data and the data to send to the overlay.

Add openOverlay to exec function and pass the parsed context to the overlay. This is the current code of the dapplet:

Open the manifest ./dapplet/dapplet.json.

⚠️ Since the browser is blocking pages with problematic security certificates, go to https://localhost:3000 when the application is running and agree to run in insecure mode.

Here we see the URL of the overlay named 'overlay' that will be used in developers mode. During the publication of the dapplet to the registry the overlay will be published to the decentralized storage.

We also see the Twitter Adapter in the dependencies. We are using the 0.9.0 version in the example.

Let’s go to the overlay.

2.2. Overlay

As we previously mentioned, the overlay can be created in any way you want. We use React in most of our projects. We will not be analyzing the entire overlay code, but only the important points for our architectural aspects.

For interaction with the dapplet install the npm package @dapplets/dapplet-overlay-bridge:

To get the data from the dapplet we need the class Bridge in the overlay part. Look at the module ./overlay/src/dappletBridge.ts. Here is the onData method where we subscribe on the 'data' event, which we’ve described in the dapplet.

Then we use it in the App.tsx module.

Now save the changes and reload the Twitter page. When you click on the button you will see the overlay with the selected tweet data.

That’s cool! But our goal is to save this data to NEAR chain and get it back. So let’s see the contract.

2.3. NEAR smart contract

Look at the th module ./contract. There is a simple NEAR smart contract written in AssemblyScript with create-near-app.

In ./contract/assembly/index.ts we see one PersistentUnorderedMap named tweetsByNearId. It stores an array of serialized tweets data with the current user ID. It has methods for saving, removing and retrieving saved tweets.

You can find all the nessesary data about how to write, test and deploy NEAR smart contracts in the official documentation and Learn NEAR courses and guides.

Let’s see how to connect to the smart contract and use its methods in the dapplet.

Add the following code to the activate method of the ./dapplet/src/index.ts module:

There is a Core.contract method that receives 3 parameters: name of the network (‘near’ or ‘etherium’), contract name and object with view and change methods.

Now we will make the contract methods available in the overlay. In order to pass the methods through the dapplets bridge, add a listen function to the overlay call. Don’t be afraid, just copy and paste this code 🙂

The last three asynchronius functions pass our contract methods to the overlay. The first four functions need to pair the wallet to the dapplet. To get the Wallet object we use the Core.wallet method, with named parameters name (near or ethereum) and network. The wallet has methods isConnected, connect, disconnect and parameter accountId.

The next step is to change ./overlay/src/dappletBridge.ts. We have to make functions that were described in the dapplet, available in the overlay. Copy the following code to the Bridge class:

Now we can use contract methods in the overlay modules. We can authorize the dapplet with the NEAR testnet wallet and save the data of the selected tweets to the smart contract. We can also see our saved data in the overlay.

Uncommit all the commited code in the ./overlay/src/App.tsx. Save changes and reload the Twitter page.

A cherry on top will be the addition of the ability to view saved tweets without parsing new ones. To do this, it is enough to add the Core.onAction method to the activate in ./dapplet/src/index.ts and pass the function of opening the overlay to it.

Now you will see the home icon near the dapplets name.

A click on the button opens an overlay with saved tweets.

Congratulations to everyone who made it to the end of the tutorial! We hope it was successful.

Here is the result: dapplets-near-example

If something didn’t work out for you, or you still have some questions, you are welcome to our chats in Discord and Telegram.

Thank you for your time. We hope this new knowledge will be useful, and you will go on to develop impressive and successful applications on the Dapplets platform using the capabilities of NEAR protocol 🚀✨

Contacts:

Web: dapplets.org
Docs: docs.dapplets.org
GitHub: github.com/dapplets
Discord: discord.gg/YcxbkcyjMV
Telegram: t.me/dapplets
Twitter: @dappletsproject