Skip to main content

UsherJS API & Properties

Instantiating the UsherJS library provides a JavaScript object that responds to a few methods. These allow you to manage referral tokens and execute on conversions.


To get more details on object and method types, you can refer to the documentation we have generated for our API and properties.


To submit a conversion, you must provide parameters that identify the Campaign you are creating a conversion for, as well as provide additional data that affects the way conversions are processed.

Usher("convert", {
id: "ida4Pebl2uULdI_rN8waEw65mVH9uIFTY1JyeZt1PBM",
chain: "arweave",
eventId: 0,
commit: 10,
nativeId: "ksFTLgrwQGtNrhRz6MWyd3a4lvK1Oh-QF1HYcEeeFVk",
metadata: {
amount: 1000,
convertType: "defi",
action: "stake"

Method parameters

Object Property Name/KeyTypeDescriptionRequired
idstringThe Identifer of the Campaign acquired during Campaign creationtrue
chainstringThe blockchain identifer acquired during Campaign creationtrue
eventIdintegerThe identifier of the Campaign Event defined during Campaign creation.
This is usually 0 for single event Campaigns.
Where different rewards can be distributed at different points throughout the Referred User journey, this can 0 to X.
nativeIdstringAn identifier of the User native to the Web3 Brand's Web App.
This can be a Web3 Wallet Address used to authorise into the Web3 Brand's Web App.

By default, assigning submitting a Native ID is a way to ensure that the Referred User can only ever be converted once.
Combining this with a Campaign Event Native Limit can deliver an experience where a Referred User can continue to convert until their conversions have committed enough to have reached the Native Limit.
commitintegerAn arbitrary value that indicates how much of the Event this Conversion consumes for the Referred (Native) User and/or whether to Event Reward Rate should be calculated.
This parameter is only necessary where the Event has a corresponding Native Limit or where rewards are issued Per Commit.
metadataobjectAn arbitrary record of key/values that the Brand can use.false
metadata.amountintegerThe only special key in the metadata property is the amount key.
This is the amount of value to be used when calculating a percentage-based reward.
ie. For DeFi or Commerce applications that reward commissions as percentage-based calculations.

usher.parse(url?, keepQueryParams?)

This method is used to parse the current URL query parameters to extract and save the Usher Referral Token. The Query Parameter _ushrt is appended to the Campaign Destination URL automatically when an Usher Invite Link is visited.


This method is immediately called when UsherJS is loaded on a Browser-based Web App.

If a URL is provided, it will be parsed instead of the current web page URL.

By default, the current web page URL has the _ushrt query parameter cleared after it is saved.


A method to fetch the currently saved Referral Token that will be used in the next executed conversion - convert(conversion)

This can be useful if your conversion tracking process involves more long-formed and controlled referral token storage.

Method parameters

Object Property Name/KeyTypeDescription
campaignReference{ id: string, chain: string }A reference to the Campaign

usher.anchor(anchorSelector, campaignReference)

Modify the href attribute on an <a> Anchor HTML Element to include the currently saved Referral Token.

This can be used to pass the _ushrt Referral Token between websites/origins/domains.

Method parameters

Object Property Name/KeyTypeDescription
anchorSelectorstringCSS Selector that points to the Anchor Element to be modified
campaignReference{ id: string, chain: string }A reference to the Campaign


A method to update the configuration of the UsherJS object.


A method to flush/remove all cached referral tokens stored in Browser Storage.