Web3 Tip Widget
Self-host and controll the entire tip flow within your app.
Example
Installation
Package
You can install DePay Widgets via yarn
or npm
and build it as part of your application:
yarn add @depay/widgets
or if you use npm
npm install @depay/widgets --save
CDN
If you don't want to install the package or don't want to build DePay Widgets as part of your application, you can also load DePay Widgets via our CDN:
<script defer async src="https://integrate.depay.com/widgets/v10.js"></script>
Usage
After installation, import DePayWidgets
from @depay/widgets
wherever you need it:
import DePayWidgets from '@depay/widgets';
Configuration
You need to pass a configuration object to DePayWidgets.Donation
which needs to at least contain the accept
field.
DePayWidgets.Donation({
title: "Tip",
accept: [{
blockchain: 'ethereum',
token: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
}]
});
This declares to receive DEPAY tokens (0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb
) as tip on ethereum
to 0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02
.
You can also accept multiple tokens on multiple blockchains:
DePayWidgets.Donation({
title: "Tip",
accept: [
{
blockchain: 'ethereum',
token: '0xdac17f958d2ee523a2206206994597c13d831ec7',
receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
},{
blockchain: 'bsc',
token: '0xe9e7cea3dedca5984780bafc599bd69add087d56',
receiver: '0x552C2a5a774CcaEeC036d41c983808E3c76477e6'
}
]
});
The DePay App helps you to create a basic valid configuration: DePay App > Integrations > New Integration > Donation Widget
accept
The accept
attribute describes what is accepted as a tip. It needs to be an array and needs to contain at least one entry.
Required Attributes
blockchain
- The name of the blockchain (e.g. ethereum
, bsc
, polygon
etc.)
token
- The address of the token you want to receive
receiver
- The address receiving the tip. Always double check that you've set the right address.
amount
When you want to control how the amount selection behaves, pass the amount
configuration object,
alongside values for start
, min
and step
.
start
: The amount that is initially selected.
min
: The minimum amount selectable.
step
: The number by wich to increment/decremten changes to the amount.
{
amount: {
'start': 10,
'min': 1,
'step': 1
}
}
connected
A callback that will be executed once the user connects a wallet.
This function will be called with the connected wallet address as the main argument:
connected: (address)=> {
// do something with the address
}
closed
closed
A function that will be called once the user closes the widget (no matter if before or after the tip).
closed: ()=> {
// do something if user closed the widget
}
before
before
A function that will be called before the tip is handed over to the wallet.
Allows you to stop the tip if this methods returns false.
before: (tip)=> {
alert('Something went wrong')
return false // stop
}
sent
sent
A function that will be called once the tip has been sent to the network (but still needs to be mined/confirmed).
The widget will call this function with a transaction as single argument (see: depay-web3-wallets for more details about the structure)
sent: (transaction)=> {
// called when tip transaction has been sent to the network
}
succeeded
succeeded
A function that will be called once the tip has succeeded on the network (checked client-side).
The widget will call this function passing a transaction as single argument (see: depay-web3-wallets for more details)
succeeded: (transaction)=> {
// called when tip transaction has been confirmed once by the network
}
failed
failed
A function that will be called if the tip execution failed on the blockchain (after it has been sent/submitted).
The widget will call this function passing a transaction as single argument (see: depay-web3-wallets for more details)
failed: (transaction)=> {
// called when tip transaction failed on the blockchain
// handled by the widget, no need to display anything
}
critical
critical
A function that will be called if the widget throws an critical internal error that it can't handle and display on it's own:
critical: (error)=> {
// render and display the error with error.toString()
}
error
error
A function that will be called if the widget throws an non-critical internal error that it can and will handle and display on it's own:
error: (error)=> {
// maybe do some internal tracking with error.toString()
// no need to display anything as widget takes care of displaying the error
}
currency
Allows you to enforce displayed local currency (instead of automatically detecting it):
{
currency: 'USD'
}
whitelist
Allows only the configured tokens to be eligible as means of tip (from the sender):
whitelist: {
ethereum: [
'0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // ETH
'0xdac17f958d2ee523a2206206994597c13d831ec7', // USDT
'0x6b175474e89094c44da98b954eedeac495271d0f' // DAI
],
bsc: [
'0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // BNB
'0xe9e7cea3dedca5984780bafc599bd69add087d56', // BUSD
'0x55d398326f99059ff775485246999027b3197955' // BSC-USD
],
polygon: [
'0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE', // MATIC
'0x2791bca1f2de4661ed88a30c99a7a9449aa84174', // USDC
]
}
blacklist
Allows to blacklist tokens so that they will not be suggested as means of tip (from the sender):
blacklist: {
ethereum: [
'0x82dfDB2ec1aa6003Ed4aCBa663403D7c2127Ff67', // akSwap
'0x1368452Bfb5Cd127971C8DE22C58fBE89D35A6BF', // JNTR/e
'0xC12D1c73eE7DC3615BA4e37E4ABFdbDDFA38907E', // KICK
],
bsc: [
'0x119e2ad8f0c85c6f61afdf0df69693028cdc10be', // Zepe
'0xb0557906c617f0048a700758606f64b33d0c41a6', // Zepe
'0x5190b01965b6e3d786706fd4a999978626c19880', // TheEver
'0x68d1569d1a6968f194b4d93f8d0b416c123a599f', // AABek
'0xa2295477a3433f1d06ba349cde9f89a8b24e7f8d', // AAX
'0xbc6675de91e3da8eac51293ecb87c359019621cf', // AIR
'0x5558447b06867ffebd87dd63426d61c868c45904', // BNBW
'0x569b2cf0b745ef7fad04e8ae226251814b3395f9', // BSCTOKEN
'0x373233a38ae21cf0c4f9de11570e7d5aa6824a1e', // ALPACA
'0x7269163f2b060fb90101f58cf724737a2759f0bb', // PUPDOGE
'0xb16600c510b0f323dee2cb212924d90e58864421', // FLUX
'0x2df0b14ee90671021b016dab59f2300fb08681fa', // SAFEMOON.is
'0xd22202d23fe7de9e3dbe11a2a88f42f4cb9507cf', // MNEB
'0xfc646d0b564bf191b3d3adf2b620a792e485e6da', // PIZA
'0xa58950f05fea2277d2608748412bf9f802ea4901', // WSG
'0x12e34cdf6a031a10fe241864c32fb03a4fdad739' // FREE
]
}
event
If set to ifSwapped
, emits an event if payments are routed through router smart contract.
Payments are routed through the DePayPaymentRouter if swapping tokens is required in order to perform the payment. If payments are not routed through the router, e.g. direct transfer, no event is emited if event
is set to ifSwapped
.
{
event: 'ifSwapped'
}
container
Allows you to pass a container element that is supposed to contain the widget:
{
container: document.getElementById('my-container')
}
Make sure to set the css value position: relative;
for the container element. Otherwise it can not contain the widget.
React example:
let CustomComponentWithWidget = (props)=>{
let container = useRef()
useEffect(()=>{
if(container.current) {
DePayWidgets.Donation({ ...defaultArguments, document,
container: container.current
})
}
}, [container])
return(
<div ref={container} style={{ position: 'relative', border: '1px solid black', width: "600px", height: "600px" }}></div>
)
}
style
Allows you to change the style of the widget.
{
style: {
colors: {
primary: '#ffd265',
text: '#e1b64a',
buttonText: '#000000',
icons: '#ffd265'
},
fontFamily: '"Cardo", serif !important',
css: `
@import url("https://fonts.googleapis.com/css2?family=Cardo:wght@400;700&display=swap");
.ReactDialogBackground {
background: rgba(0,0,0,0.8);
}
`
}
}
fee
You can configure a fee which will be applied to every tip with it's own dedicated fee receiver address.
The fee will be taken from the target token and target amount (after swap, depending on your accept
configuration).
amount
: Either percentage (e.g. 5%
, or absolute amount as BigNumber string ('100000000000000000') or pure number (2.5)
receiver
: The address that is supposed to receive the fee.
{
fee: {
amount: '3%',
receiver: '0x4e260bB2b25EC6F3A59B478fCDe5eD5B8D783B02'
}
}
Unmount
Allows you to unmount (the React safe way) the entire widget from the outside:
let { unmount } = await DePayWidgets.Donation({})
unmount()