EOSCommunity.org Forums

Call to Action: Upgrade your Anchor integrations for an improved user experience

It’s time to upgrade! This is a call to action to encourage all developers who have integrated Anchor, either directly through our SDKs or through UAL, to upgrade the Anchor related parts of their apps.

For the Anchor users out there reading this page, who love using these apps, we would encourage you to reach out to your favorite apps you use Anchor with and direct them to this post with encouragement to upgrade.


A recommended upgrade is ready!

After many months worth of work towards our goal of improving the user experience of EOSIO blockchains, we have hit a new milestone in our SDKs that include a number of new features to simplify the user experience. This call to action is to explain the why you should upgrade the software within your application, to explain the improvements we have made, and show you how to upgrade. Questions? Feel free to ask in this thread!

The 3 components you may be using in your app that are now upgraded are:

If you are using any of these components in your application, except with older versions, we highly recommend you upgrade at this point.


What’s new?

These new versions contain a significant number of improvements, including user experience improvements, bug fixes, new features, and tooling to improve your experience as a developer.

Fuel v2

The new Fuel API endpoints, which follow the initial Resource Provider specification described in this forum post, are now used in these new versions.

Free Transactions

Our Resource Provider, Fuel, provides a limited amount of free CPU and NET resources for the users of your app. This is all done directly within the application and doesn’t require your users to leave your application to go manage their resources. This keeps users focused on using your app and not distracted with the complexities of resource management.

The above animation shows what a free transaction would look like today using your application with Anchor.

Fee-based Transactions

Fuel now also provides fee-based transactions for users who have exceeded their free quota and don’t have resources of their own, which also happens directly within your app. How many times do you think a user has given up using your application because they don’t have resources and don’t understand how to manage them? This is the UX problem our fee-based transactions set to help solve.

The above animation shows a fee-based transaction and what the experience would look like within your application. The user can choose to try and proceed without the fee, or accept the fee, which is also broken down further by costs within Anchor itself. Accepting the fee will cover the costs of their transaction and allow the user to get back to what they were originally trying to do.

In-app RAM purchases

One of the other features that fee-based transactions allows us to offer is in-app RAM purchases. If the user requires RAM to complete a transaction, Fuel is able to use this fee-based purchase flow to purchase RAM directly for the account.

This is a much better user experience than the user having to go off into their wallet, buy it, and then come back to your app.

Referral Rewards

To incentivize the adoption of Fuel (and Resource Providers) within your application, we have also setup a smart contract to share the revenue generated by transactions fees with you, the application developer. All you need to do is pass an account name as one of the configuration parameters (based on your setup) and you will earn a portion of every transaction fee paid through your application. The more users using your app, the more potential revenue sharing you can be a part of.

This is all done through a smart contract on the fuel.gm account, which then allows you to call claim on to claim those tokens. We know it’s hard to monetize decentralized applications so this is one way we are trying to help. We hope this sets a precident moving forward and ends up being a common practice for all Resource Providers as this new economy starts coming to life.

Making the User Interface more clear

A number of improvements have been made to the user interface that Anchor users have faced when using apps. The original design led to some common points of confusion, which should be addressed with a better layout, more clear wording, and interactive elements.

Improvements to the Mobile Experience

The mobile-to-mobile experience has also been improved, with much better browser detection, the integration of deep links, and new handlers that better route users back to the mobile browser they originated from.

This update also adds support for the upcoming release of Anchor on Android! This update will be required for the Android version of Anchor to work properly. We would like to see as many apps upgraded as possible before the launch of Anchor on Android to make that rollout as smooth as possible.

Additional Features

The above is not all these new versions have to offer, these updates also include:

  • Multi-chain requests, one login button or one transaction type for any compatible chain.
  • Improved mobile-to-mobile experience for Anchor on iOS.
  • Changes in preparation for the release of Anchor on Android.
  • More responsive Anchor to App communication, such as closing a signing request in the wallet cancelling the transaction in the app.
  • Migrating from eosjs to @greymass/eosio as the core EOSIO library.
    • Strongly typed responses from internal APIs.
    • Exposes library functionality to integrating apps.
    • Smaller bundle sizes.
    • Better error handling.
  • Support for R1 keys to enable technologies like Secure Enclave and other HSMs.

Upgrading? Here’s what you need to know.

There are a few internal API-breaking changes you’ll need to know about during this upgrade.

anchor-link / anchor-link-browser-transport

If you are directly integrated with these two libraries, a few of the initialization parameters have changed. You’ll need to update how you define these parameters once you have upgraded. To update, use the package manager of your choosing and ensure you’re on the 3.x version.

Typed responses and required changes

All responses returned from the methods of these libraries are now typed using the @greymass/eosio library. This means if you were using generic Javascript comparisons to any of the anchor-link responses, you may need to alter that logic, since comparing a string to one of these typed objects won’t work.

You may need to specifically cast these objects to strings or numbers in order to do whatever comparisons you were previously doing. If you are expecting a string, cast it to a String() first.

If you’d like to un-type an entire response object, this can be done by converting it to and from JSON, like so:

const untypedResponse = JSON.parse(JSON.stringify(typedResponse))

Just note that all of the helper methods included will be stripped in this process. You’ll probably still want to keep the typedResponse in order to use those.

Required change: chainId is now chains

Previously the initialization of the AnchorLink class would require a chainId parameter for you to specify which blockchain you intended on using and an rpc parameter to specify the API node to use. This initialization looked something like:

new AnchorLink({
    chainId: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
    rpc: 'https://eos.greymass.com',
    transport: new AnchorLinkBrowserTransport()
})

This has now changed to be a chains parameter, which is an array that defines both of these parameters in a new format, and is what allows us to enable multi-chain logins and signing requests.

new AnchorLink({
    chains: [
        {
            chainId: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
            nodeUrl: 'https://eos.greymass.com'
        }
    ],
    transport: new AnchorLinkBrowserTransport()
})

It accepts an array of chains your application supports, and by default, will use the first chain defined in requests.

Required change for multi-chain apps: specifying a chainId

Some of the methods in anchor-link you might be using (like removeSession or restoreSession) now also accept an optional chainId parameter that allows you to specify which blockchain this method is for.

Take restoreSession for example:

link.restoreSession('myappname')

This will still function, but will now use the first blockchain defined in the chains array. If you want to specify a specific blockchain to restore an account from, you would pass the chainId as the 2nd parameter to the function like so:

link.restoreSession('myappname', 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906')

The same is true for removeSession, listSessions, and also transact.

Working with Fuel inside the anchor-link-browser-transport

As we mentioned above, Fuel now has a referral system you can use to share in the transaction fees generated by your application. To do so, just specify a valid account name as the fuelReferrer value when setting up the transport.

const transport = new AnchorLinkBrowserTransport({
    fuelReferrer: 'teamgreymass',
})
new AnchorLink({
    chains: [
        {
            chainId: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
            nodeUrl: 'https://eos.greymass.com'
        }
    ],
    transport
})

If your application provides resources already and you’d like to disable Fuel completely, that’s also possible using the disableGreymassFuel parameter on the transport:

const transport = new AnchorLinkBrowserTransport({
    disableGreymassFuel: true
})
new AnchorLink({
    chains: [
        {
            chainId: 'aca376f206b8fc25a6ed44dbdc66547c36c6c33e3a119ffbeaef943642f0e906',
            nodeUrl: 'https://eos.greymass.com'
        }
    ],
    transport
})
Other Settings

A number of new settings are also available for both anchor-link and anchor-link-browser-transport. You can find a full list of these options on Github:

ual-anchor

For users of our UAL plugin, not many changes are required, but you can optionally use the same new options as defined above. A full example of the configuration options can be found here. The @greymass/ual-reactjs-renderer-demo-multipass example we developed shows a complete implementation and is well documented in the code itself.

Reference Material:

Github - Libraries/SDKs

Github - Examples

npmjs

A thank you

A big thank you for everyone who has contributed to these efforts, whether it is directly in code or by providing feedback. We are on a mission to make these blockchains easier to understand and use for the average user. This release marks a significant step forward in that effort and shows that it is possible. We hope that every app integrating Anchor will upgrade in the near future to these new SDKs, and those apps not integrating Anchor will take notice and consider the integration in their next release.

11 Likes