SDK - Claimr

SDK (Software Development Kit) is a powerful tool that integrates Claimr’s functionalities into your web application. It provides a set of methods and events that enable you to interact with the Claimr widget, customize its behavior, and enhance the user experience.

Methods

`complete_task(task_id, data)`

This method allows you to mark a task as complete directly from your web application’s front-end. This is useful for tasks that are completed outside of the Claimr widget, such as watching a video or visiting a specific page on your website.

The task_id parameter should be the unique identifier of the task you want to complete, which can be found in your Claimr admin panel.
The data parameter is optional. Pass an object to send extra information along with the completion, for example { video_id: 'intro' }.

This method only works for tasks of the SDK FrontEnd type. See SDK tasks.

The widget must be on the page and loaded when you call this method. If the widget container is not rendered, or the widget has not finished loading, the call is ignored. Wait for is_claimr_ready to be true before calling it. See Method readiness.

`connect_wallet(address, signature, message, chain, no_reset)`

This method enables users to sign in to your Claimr campaign using their web3 wallet credentials.

The address parameter should be the user’s wallet address.
The signature parameter should be the cryptographic signature generated by the user’s wallet.
The message parameter should be the message that was signed by the user’s wallet.
The chain parameter is optional and should identify the chain the wallet address/signature belongs to.
The no_reset parameter is optional. Pass true to prevent the widget from resetting the current session state when the wallet is reconnected.

`destroy()`

This method removes the Claimr widget instance from your web page.

`get_user_info(campaign_id, public_key, account, platform)`

This method retrieves information about a specific user from your Claimr campaign using the public API.

The campaign_id parameter should be the unique identifier of your campaign.
The public_key parameter should be the public key generated in your campaign’s general settings.
The account parameter should be the user’s account identifier. For web3 wallet addresses, use the address in lowercase.
The platform parameter should be the platform identifier. For web3 wallets, use “web3”.

This method triggers the login dialog within the Claimr widget, allowing users to sign in to their Claimr account.

The in_popup parameter is optional. Pass true to open the login dialog inside the contest/leaderboard popup view instead of the main widget (only applies when that popup is available).

`logout()`

This method logs the user out of their Claimr account within the widget.

`open_profile_popup()`

This method opens the user’s profile popup within the Claimr widget.

`open_quest(quest_id)`

This method opens a specific quest within the Claimr widget.

The quest_id parameter should be the unique identifier of the quest you want to open, which can be found in your Claimr admin panel.

`platform_login(platform)`

This method opens the widget’s popup and triggers the login flow for a specific platform directly, skipping the general login menu.

The platform parameter should be the identifier of the platform to log in with (for example, a social provider configured in your campaign).

`select_wallet(address)`

This method tells the widget which of the user’s already-connected wallet addresses should be treated as the active/selected one.

The address parameter should be the wallet address to select.

`set_language(language)`

This method changes the display language of the Claimr widget.

The language parameter should be a supported language code, such as en or fr.

`set_theme(theme)`

This method allows you to set the theme of the Claimr widget if supported by your CSS.

The theme parameter should be a string representing the desired theme.

`set_user_token(token)`

This method sets the user token generated by the Claimr API. This token is used to associate a user’s actions within the Claimr widget with their account on your platform.

The token parameter should be the user token generated by the API. Refer to the Claimr API documentation for details on generating user tokens.

Pre-quests

Pre-quests let visitors earn XP and points on your site before they sign in to Claimr, for example for reading a page, watching a video, or finishing a tutorial. You create pre-quests in your campaign (or with the claimr_create_pre_quest MCP tool), then claim them from your page with claim_pre_quest(). Claimr banks the rewards in a guest pre-session stored in the visitor’s browser. When the visitor later signs in to the widget, the banked rewards move to their Claimr account. The SDK includes a built-in UI for this:

A badge in a corner of the page that shows the banked XP and points. It stays hidden until the visitor has banked something.
A toast for each award.
An optional claim button on the badge that sends the visitor to the page where they sign in and collect their rewards.

Load the script on every page where you claim pre-quests. Claims and the badge work without a widget container, so the page does not need to render the widget itself.

Pre-quest progress is stored in the visitor’s localStorage, scoped to your organization and campaign. If your site asks for consent before storing data, load the script only after the visitor consents. logout() clears this data.

`claim_pre_quest(quest_id)`

This method claims a pre-quest for the current visitor and returns a promise.

The quest_id parameter should be the ID of the pre-quest.

Claims run one at a time, in the order you call them. The promise resolves to:

{ success: true, data } when the claim is accepted. data.xp and data.pts hold the awarded XP and points.
{ success: false } when the claim is rejected or the request fails.
{ success: false, skipped: true } when the pre-quest can only be claimed once and this visitor already claimed it.

On success, the badge updates, a toast appears (or on_pre_quest_notification is called), and on_pre_quest_update fires.

video.addEventListener('ended', async () => {
  const result = await window.claimr?.claim_pre_quest('PRE_QUEST_ID');
  if (result?.success) console.log(`Banked ${result.data.xp ?? 0} XP`);
});

`configure_pre_quest(options)`

This method changes the badge, toast, and claim button settings at runtime. It merges options into the current settings, so you only pass what you want to change. options can include:

position: badge corner. One of top-left, top-right, bottom-left, or bottom-right (default).
toast_position: corner for award toasts. Defaults to bottom-right.
template: toast text. Supports the {amount}, {type}, and {reason} placeholders. Defaults to +{amount} {type} {reason}.
default_icon: URL of the image shown on the badge and toasts. Absolute, relative, and data: URLs all work.
types: display settings per points type, as { [type_id]: { icon, label } }. The xp type is labeled XP by default; other types default to their ID.
event_labels: toast reasons per pre-quest, as { [quest_id]: label }. Used when the pre-quest has no short description.
duration: how long an award toast stays visible, in milliseconds. Defaults to 4000.
claim_url: URL of the page where visitors sign in and collect their rewards. That page must render the widget. The claim button links there and adds the pre-session ID as a query parameter.
claim_label: claim button text. Defaults to Claim rewards.
claim_target: link target for the claim button. Defaults to _blank.
claim_psid_param: name of the query parameter that carries the pre-session ID. Defaults to psid.
claim_threshold: minimum banked XP before the claim button appears, as a number. To use other points types, pass an object such as { xp: 100, pts: 500 }; the button appears when any one of the rules is met. Defaults to 0.
theme: badge and toast colors, as an object with background, color, accent, muted, and border CSS color values.

The claim button appears when the visitor has banked XP or points, has not yet signed in, meets claim_threshold, and either claim_url or on_pre_quest_claim is set.

window.claimr?.configure_pre_quest({
  position: 'bottom-left',
  toast_position: 'bottom-left',
  claim_url: '/quests',
  claim_threshold: 50,
  types: { gems: { label: 'Gems', icon: '/images/gem.svg' } },
});

To turn the badge and toasts off, add data-pre-quest="false" to the script tag. See Pre-quest badge attributes.

`set_pre_quest_pts(balance)`

This method sets the displayed balance directly, without showing a toast or contacting the Claimr backend.

The balance parameter should be an object of amounts per points type, for example { xp: 120, gems: 3 }.

`get_pre_quest_xp()`

This method returns the visitor’s banked XP as a number.

`get_pre_quest_psid()`

This method returns the visitor’s pre-session ID, or an empty string if they have not claimed anything yet.

`get_pre_quest_history()`

This method returns the visitor’s most recent awards (up to 200) as an array of { ts, quest_id, pts, xp, balance } objects, oldest first.

Events

`on_analytics_event`

This event is fired when the widget emits an internal analytics event (for example, a page view or task completion). Use it to forward Claimr activity to your own analytics tools.

`on_campaign_info`

This event is fired when campaign information is loaded or updated within the widget. It receives the campaign info object.

`on_campaign_error`

This event is fired when the widget cannot show the campaign. It receives the error code, for example:

not_published: the campaign is not published yet.
access_denied: the current user does not have access to the campaign.
blocked: the user is visiting from a restricted region.

The widget also shows its own message for these errors. Use this event to hide the widget area or show your own fallback.

`on_campaign_loading`

This event is fired when the widget starts loading the campaign.

`on_campaign_revealed`

This event is fired when the campaign content is rendered and visible in the widget, after its height has been applied. Use it to hide your own loading placeholder.

`on_connect_wallet`

This event is fired when the widget asks your parent application to handle a wallet connection, such as for custom wallet integration flows (for example, when data-platform="dapp"). Answer it by calling claimr.connect_wallet(address, signature, message, chain) once your wallet is connected - or implement on_wallet_request instead, where connect simply returns the address. Assigning this callback is what tells the widget your application can connect a wallet at all. Leave it unset and a connect request is refused straight away, rather than the widget waiting on an answer that isn’t coming.

`on_contest_open`

This event is fired when a user opens any quest within the Claimr widget.

`on_custom_login`

This event is fired when a user logs in using the “custom” sign-in option.

`on_disconnect_wallet`

This event is fired when the widget asks your parent application to disconnect the currently connected wallet.

`on_leaderboard_open`

This event is fired when a user opens the leaderboard within the Claimr widget.

`on_leaderboards_info`

This event is fired when leaderboard data is loaded or updated. It receives the array of leaderboard entries.

`on_logout`

This event is fired when a user logs out of their Claimr account within the widget.

`on_market_open`

This event is fired when a user opens the market/store section within the Claimr widget.

`on_pre_quest_claim`

Assign a function to this event to handle clicks on the pre-quest claim button yourself. It receives an object with url, psid, xp, and balance. If claim_url is not set, assigning this callback is what makes the claim button appear, as a button instead of a link. If claim_url is set, the button stays a link and your callback runs as the visitor follows it.

`on_pre_quest_notification`

Assign a function to this event to replace the built-in pre-quest award toast with your own UI. When set, it’s called instead of showing the default toast, and receives an object with quest_id, pts, xp, balance, name, image, and short_desc.

`on_pre_quest_update`

This event is fired after a successful claim_pre_quest() call that awarded XP or points. It receives the new balance and a details object with quest_id, pts, and xp.

`on_wallet_request`

The single callback for every wallet operation the widget needs your application to perform when data-platform="dapp". It receives one object with an op field and returns (or resolves to) a result; throwing reports a failure, and the widget shows it rather than waiting.

`op`	Receives	Return
`connect`	`namespaces` - the chains the widget can act on, in preference order	`{ address, chain }`
`sign_message`	`address`, `message`	`{ signature }`
`send_transaction`	`chain_id`, `address`, `request`, `contract`, `method`, `args`, `abi`, `fee`	`{ hash }`
`disconnect`	None	`{}`

claimr.on_wallet_request = async ({ op, ...params }) => {
    if (op === 'connect') return { address: await connect(), chain: '1' };
    if (op === 'sign_message') return { signature: await sign(params.message) };
    if (op === 'send_transaction') return { hash: await send(params) };
    if (op === 'disconnect') return disconnect(), {};
    throw new Error(`unsupported: ${op}`);
};

send_transaction carries the transaction twice: request is the pre-encoded EIP-1193 call, and contract / method / args / abi describe the same call at the ABI level for hosts that rebuild it with their own library. Use whichever suits your integration.

`on_request`

Superseded by on_wallet_request, and still fully supported - it runs whenever on_wallet_request is not set, so existing integrations need no change.

This event is fired when data-platform="dapp" and the widget needs your application to submit an on-chain request (transaction or signing request) using your own wallet integration.

Receives chain_id, request, contract, method, args, abi, and fee.
Should return (or resolve to) the resulting transaction hash as a string. Returning nothing is reported to the widget as a failure.

`on_sign_message`

This event is fired when the widget asks your parent application to sign a message with the connected wallet. Answer it by calling claimr.connect_wallet(address, signature, message, chain) - or implement on_wallet_request instead, where sign_message simply returns the signature. As with on_connect_wallet, assigning this callback is what advertises the capability: unset, a signature request is refused immediately instead of waiting.

`on_user_info`

This event is fired when the widget sends updated information about the currently logged-in user (for example, after login or a profile update). It receives the user object.

Parameters

`user`

This parameter contains information about the currently logged-in user, such as their user ID, name, and email address.

`campaign_info`

This parameter contains information about the currently loaded campaign, populated after the on_campaign_info event fires.

`is_claimr_ready`

This read-only parameter is true while the widget is attached and loaded, and ready to receive method calls such as set_language() or complete_task(). It turns true at the same moment the loader posts a widget::ready message to your page, and back to false when the widget container is removed from the page or destroy() is called. See Method readiness.

`pq`

This parameter holds the current pre-quest state and settings: the banked pts, the pre-session psid, whether the progress is already attached to a Claimr account, and the options described under configure_pre_quest() above. Change it with configure_pre_quest() and set_pre_quest_pts() rather than mutating it directly.

​Methods

​complete_task(task_id, data)

​connect_wallet(address, signature, message, chain, no_reset)

​destroy()

​get_user_info(campaign_id, public_key, account, platform)

​login(in_popup)

​logout()

​open_profile_popup()

​open_quest(quest_id)

​platform_login(platform)

​select_wallet(address)

​set_language(language)

​set_theme(theme)

​set_user_token(token)

​Pre-quests

​claim_pre_quest(quest_id)

​configure_pre_quest(options)

​set_pre_quest_pts(balance)

​get_pre_quest_xp()

​get_pre_quest_psid()

​get_pre_quest_history()

​Events

​on_analytics_event

​on_campaign_info

​on_campaign_error

​on_campaign_loading

​on_campaign_revealed

​on_connect_wallet

​on_contest_open

​on_custom_login

​on_disconnect_wallet

​on_leaderboard_open

​on_leaderboards_info

​on_logout

​on_market_open

​on_pre_quest_claim

​on_pre_quest_notification

​on_pre_quest_update

​on_wallet_request

​on_request

​on_sign_message

​on_user_info

​Parameters

​user

​campaign_info

​is_claimr_ready

​pq

Methods

`complete_task(task_id, data)`

`connect_wallet(address, signature, message, chain, no_reset)`

`destroy()`

`get_user_info(campaign_id, public_key, account, platform)`

`login(in_popup)`

`logout()`

`open_profile_popup()`

`open_quest(quest_id)`

`platform_login(platform)`

`select_wallet(address)`

`set_language(language)`

`set_theme(theme)`

`set_user_token(token)`

Pre-quests

`claim_pre_quest(quest_id)`

`configure_pre_quest(options)`

`set_pre_quest_pts(balance)`

`get_pre_quest_xp()`

`get_pre_quest_psid()`

`get_pre_quest_history()`

Events

`on_analytics_event`

`on_campaign_info`

`on_campaign_error`

`on_campaign_loading`

`on_campaign_revealed`

`on_connect_wallet`

`on_contest_open`

`on_custom_login`

`on_disconnect_wallet`

`on_leaderboard_open`

`on_leaderboards_info`

`on_logout`

`on_market_open`

`on_pre_quest_claim`

`on_pre_quest_notification`

`on_pre_quest_update`

`on_wallet_request`

`on_request`

`on_sign_message`

`on_user_info`

Parameters

`user`

`campaign_info`

`is_claimr_ready`

`pq`