SDK

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)

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.

​

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”.

​

login(in_popup)

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.

​

Points

The SDK ships with a lightweight, built-in points/XP badge and toast notification UI that you can control independently of the widget. It’s useful for headless integrations or when you want to reflect a user’s point balance directly on your page.

​

configure_points(options)

This method configures the built-in points badge and toast UI. options is an object that can include:

• enabled: true or false to show or hide the points UI.
• position: badge position — top-left, top-right, bottom-left, or bottom-right.
• toast_position: position for award toasts (defaults to position).
• template: toast message template, supporting {amount} and {reason} placeholders.
• icon: string (for example, an emoji) shown on the badge and toasts.
• duration: how long an award toast stays visible, in milliseconds.
• theme: an object with background, color, and accent CSS color values.

​

set_points_balance(balance)

This method sets the displayed points balance directly, without showing an award toast or notifying the Claimr backend. Use it to sync the widget’s badge with a balance you already have (for example, on page load).

• The balance parameter should be the numeric balance to display.

​

add_points(amount, reason, meta)

This method increases the points balance by amount, shows an award notification (or calls on_points_notification if you’ve defined one), and reports the award to the Claimr backend for the current user.

• The amount parameter is the number of points to add (can be negative).
• The reason parameter is optional and describes what the points were awarded for. It’s used in the toast template and passed to event callbacks.
• The meta parameter is optional and can hold any additional metadata to send to the backend along with the award.

​

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_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").

​

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_points_notification

Assign a function to this event to fully replace the built-in points award toast with your own UI. When set, it’s called instead of showing the default toast, and receives an object with amount, reason, and the updated balance.

​

on_points_update

This event is fired whenever the points balance changes via add_points() or set_points_balance(). It receives the new balance and a details object with amount, reason, and meta.

​

on_request

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.

​

on_sign_message

This event is fired when the widget asks your parent application to sign a message with the connected wallet.

​

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.

​

points

This parameter holds the current state of the built-in points UI, including the balance and configuration options such as position, icon, template, and theme. Update it using configure_points(), set_points_balance(), and add_points() rather than mutating it directly.