Notify (older version)
Client library for a full notification UI experience. Powered by our Mempool API.
Notify is now part of web3-onboard
We've upgraded Notify with a modern look & feel and added it to web3-onboard. You can access the latest version on https://onboard.blocknative.com/ as part of the core package.
To see the notify.js library in action, checkout the code sandboxes at the end of this documentation or see the latest on the open source demo site at https://reactdemo.blocknative.com/.
Notify.js uses Notify API, which has rate limits. Please see Rate Limits for more details.
Quickstart
It should take less than 5 minutes to get going with Blocknative Notify.
Create a Blocknative Account
Setup your Blocknative account at https://explorer.blocknative.com/account?signup=true using an email address. You will receive an email to confirm your account. You can then go to your account page at https://explorer.blocknative.com/account.
Create an API Key
On your Account page, create a new API key with your choice of name using the Add new API Key button on the top right. Blocknative will create a default API key for you but it is recommended you create your own as API keys segment analytics data. Consider using different API keys for development, staging, and production releases.
Install the widget using npm
Initialize the Library
Use the minimum required config. There are more options available in our documentation.
Track transactions
Send a transaction using web3.js and get the transaction hash while its processing. Let notify know the hash and it will track its progress through the mempool and into a block.
And you are live!
Example Code
For an example of a basic React demo integration of both Notify.js and Onboard.js, checkout the GitHub repo: https://github.com/blocknative/onboard-notify-react
and the live demo:
https://reactdemo.blocknative.com/
Screencasts
See the above Quickstart guide in a screencast:
See how to add and customize advanced notifications to your Dapp:
Initialization
dappId
[required] (optional if in UI only mode)
dappId
[required] (optional if in UI only mode)Your unique api key that identifies your application. You can generate a dappId by visiting the Blocknative account page and create a free account.
system
[default = 'ethereum']
system
[default = 'ethereum']The blockchain system that you would like to track transactions on. Currently supported systems are 'bitcoin'
and 'ethereum'
.
networkId
[required] (optional if in UI only mode)
networkId
[required] (optional if in UI only mode)The network id that your application runs on. The following values are valid:
Ethereum
1
Main Network3
Ropsten Test Network4
Rinkeby Test Network5
__ Goerli Test Network42
Kovan Test Network100
xDai POA Network137
Polygon Matic Main Network
onerror
onerror
A function to catch any errors that Notify does not handle internally such as event rate limit errors.
darkMode
darkMode
Boolean value sets notification rendering to use light text on dark background. Default is false
.
mobilePosition
mobilePosition
String value sets where notifications appear on mobile devices. Value must be either top
or bottom
. Default is top
.
desktopPosition
desktopPosition
String value sets where notifications appear on desktop devices. Value must be bottomLeft
, bottomRight
, topLeft
, or topRight
. Default is bottomRight
.
txApproveReminderTimeout
txApproveReminderTimeout
Number value sets time to wait until approval reminder notification is presented. This notifications reminds user to confirm/approve a transaction for processing by the wallet. Default is 20000
milliseconds (20 seconds).
tsStallPendingTimeout
tsStallPendingTimeout
Number value sets time to wait until stall notification is presented if transaction is not detected in the txPool
. Default is 20000
milliseconds (20 seconds).
tsStallConfirmedTimeout
tsStallConfirmedTimeout
Number value sets time to wait until stall notification is presented if transaction is not confirmed in a block. Default is 90000
milliseconds (90 seconds).
transactionHandler
transactionHandler
The function defined for the transactionHandler
parameter will be called once for every status update for every transaction that is associated with a watched address or a watched transaction. This is useful as a global handler for all transactions and status updates. The callback is called with the following object:
See the Transaction Object section for more info on what is included in the transaction
parameter.
clientLocale
clientLocale
Sets the locale for internationalization within notify. Defaults to English ('en'
). See the i18n section for more details.
notifyMessages
notifyMessages
An object that defines all of the transaction messages. Can be used to customize the default messages, and can also be used to add multiple language support for transaction notifications. See the i18n section for more details.
Notifications
hash
hash
To get notifications for every status that occurs after sending a transaction ("post-flight"), use the hash
function:
Check out the Emitter Section for details on the emitter
object
account
account
You can register an address with Notify to display notifications for all incoming and outgoing transactions that occur on that account by using the account
function:
Check out the Emitter Section for details on the emitter
object
transaction
transaction
To get notifications for every status that occurs for the full transaction lifecycle ("pre-flight" and "post-flight"), use the transaction
function:
The transaction function only applies to Ethereum transactions
result
is a promise that resolves with the id
of the transaction or rejects with an error if there was an error initiating the transaction. The id
is useful for when you would like to initiate the transaction yourself and didn't pass a sendTransaction
function in to transaction
. You can then send the transaction yourself, receive the hash, and then call notify.hash(hash, id)
. By passing in the id
to hash
you enable notify to link the preflight notifications to the post send transaction notifications, ensuring a consistent UX.
The transaction
function takes an object as the argument which allows you to progressively opt in to which checks and corresponding notifications that you would like during the "pre-flight" phase of the transaction lifecycle. Below is a list of the parameters, what is expected for each of those parameters, and the corresponding notifications you will get by including those parameters:
estimateGas
- [balance check notification]
The estimateGas
function must return a Promise
that resolves with a String
that is the gas estimate in wei
. This function can vary depending on whether it is a contract transaction or just a regular send transaction call.
gasPrice
- [balance check notification]
The gasPrice
function must return a Promise
that resolves with a String
that is the gas price in wei
.
balance
- [balance check notification]
The users' balance in wei
txDetails
- [repeat transaction check notification]
The txDetails
object includes a to
parameter which is the address the transaction is being sent to and the value
parameter, which is the value of the transaction.
contractCall
- [repeat transaction check notification]
The contractCall
object includes a methodName
parameter which is the name of the method on the contract being called and the params
parameter is the parameters that the contract method was called with.
sendTransaction
- [send transaction error, approval reminder, and stall notifications]
The sendTransaction
function must return a Promise
that resolves with a String
that is the transaction hash.
notification
notification
You may want to trigger a notification for a custom event that may not be related to a transaction. You can use the notification
function to do that:
The notification
function is called with a notification object with the following parameters:
eventCode
: a string which is used to keep track of that event for your analytics dashboardtype
: a string that defines the style - ['hint' (gray), 'pending' (yellow), 'success' (green), 'error' (red)]message
: a message string that is displayed on the notificationautoDismiss
: a number in milliseconds before the notification auto dismisses or0
for no auto dismissal.success
andhint
types default to4000
onclick
: a function to call when the notification is clicked by the user
Returned from the notification function is an object that has two functions defined on it:
update
: a function that can be called with a new notification object to replace the original notification withdismiss
: a function that can be called to dismiss the notification manually
unsubscribe
unsubscribe
You may want to unsubscribe from an account address or transaction hash that you are watching and stop receiving notifications:
config
config
Some configuration options can be set or updated after the library is initialized:
If a new networkId
or system
is passed to the config
function, then the current WebSocket connection will automatically be closed and a new connection will be established.
Emitter
The emitter
object returned is used to listen for transaction events:
Linking to a Block Explorer
You may want to link to a block explorer (such as Etherscan) on every transaction notification. To do this, a link
parameter can be added to the notification object returned from the emitter callback specifying the url:
Event Codes
The following event codes are valid events to listen to on the transaction emitter:
Client Side Generated Events (when using transaction
function):
transaction
function):txRequest
: Transaction has been initiated and is waiting approval from the usertxRepeat
: Transaction has the same value and to address, so may be a repeat transactiontxAwaitingApproval
: A previous transaction is awaiting approvaltxConfirmReminder
: Transaction has not been confirmed after timeouttxStallPending
: Transaction has not been received in the mempool after timeouttxStallConfirmed
: Transaction has been in the mempool for longer than the timeouttxError
: An error has occurred initiating the transactiontxSendFail
: The user rejected the transactiontxUnderpriced
: The gas was set too low for the transaction to completetxSent
: Transaction has been sent to the network
Server Side (Notify SDK) Generated Events
txPool
: Transaction was detected in the "pending" area of the mempool and is eligible for inclusion in a blocktxStuck
: Transaction was detected in the "queued" area of the mempool and is not eligible for inclusion in a blocktxConfirmed
: Transaction has been confirmedtxFailed
: Transaction has failedtxSpeedUp
: A new transaction has been submitted with the same nonce and a higher gas price, replacing the original transactiontxCancel
: A new transaction has been submitted with the same nonce, a higher gas price, a value of zero and sent to an external address (not a contract)txDropped
: Transaction was dropped from the mempool without being added to a block. NOTE: Transaction could reappear in mempool.
Local Networks
When using a local network (such as Ganache), Notify has no way of seeing pending
and confirmed
statuses for transactions on that network and will not display any notifications. The emitter will also not emit events for those statuses. Notify will set the network to local
if a networkId
is passed in during initialization that is not one of the supported networks
Transaction Object
The callback that is registered for events on the emitter will be called with the following transaction object:
Customizing CSS
To gain the required specificity to override the default styles, use the class name .bn-notify-custom
plus the class name that you would like to override in your CSS
file. For example, if you would like to customize the font-family
of the notifications, then you would target the top level ul
element that has the class bn-notify-notifications
in your CSS
file:
Below is a list of the main classes that you would target to customize the CSS
:
class name | description |
---|---|
| container holding all of the notifications |
| top level element of each notification |
| notification content container |
| notification message |
| close notification icon container |
i18n
Notify has internationalization built in, allowing you to enable transaction notifications that match your user's locale and to give the user an option to switch locale.
clientLocale
clientLocale
Notify will automatically detect the browser's locale and set an internal clientLocale
. If that locale is defined within the notifyMessages
object, then it will use that locale for all transaction messages. If it isn't defined, then it will fallback to the default 'en'
locale. You can explicitly set the clientLocale
for the user by calling the config
function or passing it in via initializationObject
.
notifyMessages
notifyMessages
This object contains the messages for all the transaction states supported by Notify. The library has default transaction messages for the 'en'
clientLocale
and can be extended to include transaction messages for additional clientLocale
settings. To extend the default notifyMessages
object, you can pass in a notifyMessages
object to either the config
function or to the initializationObject
.
Below is an example object that implements a 'es'
(Spanish) notifyMessages
object:
The notifyMessages
object above would get merged with Notify's internal notifyMessages
object, extending Notify to support both English and Spanish transaction notification messages.
You can include as many of the above parameters as you would like in each language object. If Notify gets an undefined
value back from the language object, then it will fallback to the English default included in Notify.
Notify uses format.js
under the hood, which uses the ICU message syntax to format messages. Check out their guide to the ICU message syntax here.
For each language, you can include a transaction
object, a watched
object and a time
object.
The transaction
object will be referenced for notifications that have been triggered via the hash
or transaction
function.
The watched
object will be referenced for notifications that have been triggered by watching an address via the account
function.
The time
object will be referenced for expressing the amount of time that has passed during pending states on the notification.
Each message will be called with the following inputs that will be formatted in to a message string:
The formatted value of the transaction:
formattedValue
- (transaction
, watched
)
The asset that is being sent or received:
asset
- (transaction
, watched
)
The correct verb based on whether the transaction is being incoming or outgoing and whether it is confirmed or pending:
verb
- (watched
)
Possible values are: 'received'
, 'sent'
, 'receiving'
, 'sending'
The correct preposition based on the direction of the transaction:
preposition
- (watched
)
Possible values are: 'from'
, 'to'
A shortened address of the counter party of the transaction:
counterpartyShortened
- (watched
)
UI Only Mode
You can optionally run Notify.js as a simple notification UI library by not including a dappId
in your initialization options. In this scenario, Notify.js will not initiate a WebSocket connection to the Blocknative servers and all functionality other than the notification
function will be disabled.
Rollup Builds
You may run in to an error: Uncaught TypeError: dist is not a constructor
when building with Rollup.js. To fix this issue make sure that you are using @rollup/plugin-commonjs
version 16.0.0
and above
Get Started Today
Sign up for a free Blocknative Account at https://explorer.blocknative.com/account?signup=true with your work email address.
If you have any questions, connect with the team on our discord
React Demo
To see a Notify integration in a simple React app you can check out our react-demo
repo on GitHub: https://github.com/blocknative/react-demo
We have the reactdemo
codebase deployed so that you try Notify from an end user perspective: https://reactdemo.blocknative.com/
Last updated