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 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/Key | Type | Description |
|---|---|---|
id | string | The Identifer of the Campaign acquired during Campaign creation |
chain | string | The blockchain identifer acquired during Campaign creation |
eventId | integer | The 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. |
nativeId | string | An 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. |
commit | integer | An 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. |
metadata | object | An arbitrary record of key/values that the Brand can use. |
metadata.amount | integer | The 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. |
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/Key | Type | Description |
|---|---|---|
campaignReference | { id: string, chain: string } | A reference to the Campaign |
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/Key | Type | Description |
|---|---|---|
anchorSelector | string | CSS 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.