@wert-io/widget-initializer

WertWidget initializer

@wert-io/widget-initializer is a helper that assists you with integrating the Wert widget into your web app.

• WertWidget initializer
  • Installation
  • Usage
  • Options
    • General options
    • Smart contract options
    • Pre-filling user data
    • Appearance and restrictions
    • Extra object structure
      • Adding NFT information
      • Adding default wallets
    • Listeners
      • Initial event listeners
      • Events
  • Widget class methods
    • Showing the module
    • Closing the module
    • Switching themes without reload
    • Adding event listeners
    • Removing event listeners
  • Additional notes
    • Boolean usage

Installation

npm install @wert-io/widget-initializer

Usage

import WertWidget from '@wert-io/widget-initializer';

First of all, you need to create a widget class:

const wertWidget = new WertWidget(options);

Options

General options

Property	Required	Type	Default value	Possible value(s)	Description
partner_id	required	String	-	-	partner_id will be given to you upon your registration as our partner. It's required to track your commission and statistics. If you don't have one, contact us.
click_id	optional	String	-	uuid_v4()	Unique identifier for the order that lets you track it and helps us with troubleshooting.
listeners	optional	Object	-	See the listeners object structure	Use this if you want to listen to some module events and react to them.
origin	optional	String	https://widget.wert.io	https://sandbox.wert.io	Required to initialize the module in the specific environment.
redirect_url	optional	String	-	https://origin.us/item_id	Full url string (with protocol). This link will be used for user redirection.

Smart contract options

Property	Required	Type	Default value	Possible value(s)	Description
sc_address	required for smart contracts	String	-	-	Address of the smart contract where the transaction should be sent to.
sc_input_data	required for smart contracts	String	-	-	Input data to be executed by the smart contract, in hex format. For Tezos, it must be Michelson code passed as JSON transformed into hex format.
signature	required for smart contracts	String	-	-	Signature to sign the data for the smart contract execution. You can use our signature helper.

Pre-filling user data

Property	Required	Type	Default value	Possible value(s)	Description
address	optional	String	-	-	User's wallet address. The address is checked for validity based on the chosen commodity. BTC address format is used by default. If the address is invalid, this option is ignored.
commodity	optional	String	BTC	List of supported currencies	Default commodity that will be selected in the module.
network	optional	String	bitcoin	List of supported currencies	Network that will be selected for default commodity.
commodity_amount	optional	Number	-	-	Default commodity amount that will be pre-filled in the module. This option is ignored if the currency_amount has been set.
commodities	optional	String	-	List of supported currencies	Commodities that will be available in the module. By default, all commodities are present. Should contain a stringified JSON of an array of objects with commodity and network fields. Fields are filled with the same values as a default commodity and network, e.g. JSON.stringify([{ commodity: 'USDC', network: 'ethereum' }]).
currency_amount	optional	Number	-	-	Default currency amount that can be pre-filled in the module.
country_of_residence	optional	String	-	code of the country	User's country of residence.
state_of_residence	optional	String	-	code of USA state	User's state of residence (for the USA).
date_of_birth	optional	String	-	DD/MM/YYYY / MM/DD/YYYY (USA)	User's date of birth.
email	optional	String	-	[e-mail]	User's email address.
full_name	optional	String	-	min 3, max 69 letters; RegExp(/(\w+\s)\w+/)	User's first and last name.
phone	optional	String	-	[phone] / 11014321111	User's phone number in the international format (E. 164 standard). Can be with or without +.

Appearance and restrictions

Property	Required	Type	Default value	Possible value(s)	Description
lang	optional	String	en	List of supported languages	Defines the language in the module. Falls back to English.
is_crypto_hidden	optional	Boolean	undefined	true	Allows to hide crypto mentions and exchange rate for NFT purchases if it is enabled for your partner_id. - Please check the boolean usage note
is_warranty_disabled	optional	Boolean	undefined	true	Allows to disable NFT warranty option for a specific widget mount, even if it is enabled for your partner_id and smart contract. - Please check the boolean usage note
skip_init_navigation	optional	Boolean	undefined	true	By default, module will try to provide the closest to purchase starting route depending on provided parameters. If true, this navigation logic will be skipped. - Please check the boolean usage note
theme	optional	String	undefined	dark	The theme used in the module (uses the light theme by default).
buttons_border_radius secondary_buttons_border_radius	optional	Number	4	-	Custom radius of elements (in pixels).
color_background color_buttons color_buttons_text color_secondary_buttons color_secondary_buttons_text color_main_text color_secondary_text color_icons color_links color_success color_warning color_error	optional	String	-	red / #FF0000 / rgb(255,255,0)	Custom colors of elements. Can be in any suitable format (string, HEX, rgb etc.).

Extra object structure

The extra object is an optional object that can contain some additional data.

extra: {
  item_info: Object,
  wallets: Array,
}

Adding NFT information

You can add the following parameters to the item_info to display your NFT's name, image, the author’s avatar, the author’s name and the seller’s name in the widget.

Property	Type	Description
author_image_url	String	The URL of the author's avatar. Example: https://something.com/images/image.jpg
author	String	The name of the author
image_url	String	The URL of the NFT's image
name	String	The name of the NFT
category	String	The category of the NFT
seller	String	The name of the NFT's seller
header	String	The header to be shown instead of 'Buy token'

Adding default wallets

You can define the array of default wallets that will be prefilled when the user changes cryptocurrency. Non-valid addresses will be ignored.

The wallet object structure:

Property	Type	Description
name	String	Example: ETH. See the list of supported currencies.
network	String	Example: ethereum. See the list of supported currencies.
address	String	The wallet address. Non-valid addresses will be ignored.

Listeners

Initial event listeners

Simply include the listeners object in the following format, where the key is the event type and the value is your callback.

const widget = new WertWidget({
  ...options,
  listeners: {
    position: data => console.log('step:', data.step),
  },
});

Events

Event type	Data	Description
close	undefined	An event raised by module when the user closes a widget.
error	{ name: String message: String }	Information about an error that occurred in the module.
loaded	undefined	The module has the necessary data and is ready to work. In case extra data was used, it's ready to receive it. This event can be duplicated if there was a 3D Secure redirection.
payment-status	{ status: String payment_id: String order_id: String tx_id: String // if available }	Possible statuses: pending, canceled, failed, success, failover. Event for each status can be not unique.
position	{ step: String }	Informs about the changes in user's position in the flow.
rate-update	{ ticker: String, fee_percent: String, currency_amount: String, fee_amount: String, commodity_amount: String, purchase_amount: String, miner_fee: String, currency_miner_fee: String }	Information on when does the widget updates the rate.

Widget class methods

Method	Description
open	Mounts module in DOM and makes it visible
updateTheme	Switches the theme without reload
addEventListeners	Adds event listeners
removeEventListeners	Removes event listeners
close	Closes the widget

Showing the module

After creating an instance of the widget class, you can call the open method to show the module to the user:

wertWidget.open();

Closing the module

You can call the close method to close and remove the widget modal at any time:

wertWidget.close();

Switching themes without reload

To switch to another theme without reloading the whole widget you can use the updateTheme method:

wertWidget.updateTheme({
  theme: 'dark', // undefined — for the default light theme 
  colors: {
    // supported colors listed in options table above 
    color_buttons: 'red',
  },
});

Please note that this method should be called only after the widget is fully loaded.

Adding event listeners

If you want to listen to the widget events, you can use the addEventListeners method. Pass an object of listeners to add listeners, potentially rewriting the existing listeners of the same type:

wertWidget.addEventListeners({
  position: data => console.log('step:', data.step),
});

Removing event listeners

If you want to stop listening to the widget events, you can use the removeEventListeners method. Pass an event type, array of the event types or nothing to remove a listener, multiple listeners or all listeners:

wertWidget.removeEventListeners('rate-update');

or

wertWidget.removeEventListeners([ 'rate-update', 'payment-status' ]);

or

wertWidget.removeEventListeners();

Additional notes

Additional information about the library usage

Boolean usage

Please note that any value passed to the property with the boolean type will be considered true.
Example: is_crypto_hidden: "test" will be equal to is_crypto_hidden: true.