Integrate Claimr widget into your dApp

You can use the Claimr widget inside any TypeScript-based React application to enable blockchain-driven engagement features within your dApp. This setup is ideal for dApps using custom or anonymous wallet layers, such as embedded wallet providers or user flows that require privacy. In these cases, users connect their wallet at a higher level, and you proxy the connection down to the Claimr widget, avoiding duplicate wallet prompts and maintaining a seamless UX. This article demonstrates how to:

Inject the Claimr widget dynamically.
Pass wallet signatures to Claimr without reconnecting.
Respond to Claimr widget events for blockchain interaction.

Main files:

src/claimr_wrapper.tsx: Handles Claimr widget injection.
src/wagmi.ts: Sets up wallet connections and providers.
src/example_app.tsx & src/main_page.tsx: The main app UI.

Ensure you have the following installed:

Node.js (v18+ recommended)
npm or Yarn

Run the project

Open a terminal and follow the steps below.

Navigate to your project directory

cd path/to/claimr-dapp-example

Install dependencies

Using npm:

npm install

Using Yarn:

yarn

Start the development server

Using npm:

npm start

Using Yarn:

yarn start

Visit your app

Open http://localhost:3000 in your browser.

Build for production (optional)

To create a production-ready build:

npm run build

Or:

yarn build

This will create a production-ready build/ folder. The ClaimrWrapper component is responsible for injecting the Claimr widget script into the application. This ensures the widget is loaded dynamically and configured appropriately for your dApp environment. Script source:

https://widgets.claimr.io/claimr.min.js

The script is injected with the following attributes:

script.setAttribute('data-container', CLAIMR_CONTAINER_ID);
script.setAttribute('data-organization', 'Claimr');
script.setAttribute('data-campaign', 'dapp');
script.setAttribute('data-addons', 'sup,eap,eup,pvm,dcc');
script.setAttribute('data-autoresize', 'true');
script.setAttribute('data-platform', 'dapp');

These attributes define where the widget should render (data-container), which organization and campaign to load, what feature add-ons are enabled, and that it’s running in a dApp context. The widget script is injected only once per session to avoid duplication.

App bootstrapping (example_app.tsx)

The widget is used within a fully Web3-enabled app context, including support for wallet connections, data fetching, and blockchain interaction. The main provider hierarchy looks like this:

<WagmiProvider config={config}>
  <QueryClientProvider client={client}>
    <RainbowKitProvider>
      <ClaimrWrapper>
        <MainPage />
      </ClaimrWrapper>
    </RainbowKitProvider>
  </QueryClientProvider>
</WagmiProvider>

This setup provides:

WagmiProvider: Wallet and blockchain interaction support.
QueryClientProvider: Enables data fetching via React Query.
RainbowKitProvider: Wallet UI and modal handling.
ClaimrWrapper: Injects and initializes the Claimr widget.

All components inside MainPage now have access to both the wallet and the Claimr widget.

Wallet integration (wagmi.ts)

The app uses:

@rainbow-me/rainbowkit for wallet modal & connection management
wagmi for Ethereum interaction abstraction

Chains configured:

Ethereum Mainnet
Sepolia testnet
Arbitrum Sepolia testnet

Configuration:

export const config = getDefaultConfig({
  appName: 'Claimr dApp example',
  projectId: 'YOUR_WALLETCONNECT_PROJECT_ID',
  chains: [mainnet, sepolia, arbitrumSepolia],
  transports: {
    [mainnet.id]: http(),
    ...
  }
});

The projectId comes from WalletConnect (required by RainbowKit). The Claimr widget does not manage the wallet directly. Instead, it relies on the host app to pass signed wallet data for authentication.

Two-way integration

Wallet management (connect/disconnect, sign, etc.) is handled via wagmi + RainbowKit.
The Claimr widget uses SDK methods and browser events to communicate with the wallet context.

window.claimr.connect_wallet(address, signature, message)

This function is called after the user signs a message with their wallet:

window.claimr?.connect_wallet(address, signature, message);

address: user’s wallet address (from wagmi.useAccount())
signature: result from signMessageAsync()
message: custom nonce + timestamp message (from get_sign_message())

It authenticates the user in Claimr using a wallet signature.

`window.claimr.on_request = async (...) => { ... }`

Set during widget::ready:

window.addEventListener('message', process_message);

if (event.data.event === 'widget::ready') {
  window.claimr.on_request = on_request;
}

The on_request function handles:

Switching chains if needed (switchChainAsync)
Calling a contract method with abi, contract, method, args, and chain_id
Returning the transaction hash back to Claimr

It lets the Claimr widget trigger on-chain actions like NFT mints, token claims, etc., through your dApp’s wallet context.

Example flows

When the user opens the app:

React app loads.
ClaimrWrapper injects the widget.
If localStorage['demo-signature'] exists, it’s reused.
Otherwise, the app shows a “Connect wallet → Sign in” prompt.

When the user signs the message:

signMessageAsync() signs a claimr-auth message.
The signature is saved in localStorage.
window.claimr.connect_wallet(...) is called to complete login.

When the widget needs to interact with the blockchain:

The widget emits a widget::ready event.
Your app assigns the on_request handler.
Claimr can now ask your app to switch chains or execute contract calls.

Campaign configuration: required settings

To ensure the Claimr widget works correctly with your dApp, configure the campaign settings accordingly.

Navigate to Sign-in options

Open your Claimr dashboard, go to your specific campaign, click Settings in the left-hand menu, then select Sign-in options.

Set the sign-in parameters

Require login to start a task: Ensures that users must log in (e.g., via wallet) before they can begin any task. This is necessary for Claimr to associate actions with an authenticated wallet address.
Require token to start campaign (optional): If enabled, this requires a specific token to access the campaign.
Wallet change is disabled (optional): Prevents users from switching wallets mid-session.
Disable users merge (optional): Disables automatic merging of user identities across sign-in methods.

Configure wallet sign-in

Select Wallet to allow wallet-based login in the Select sign-in services field, select the correct blockchain in the Chains field, and in the Wallet message field, enter a custom message that will be shown to users during wallet signature to identify the purpose of signing.

Summary

Method	Triggered by	Purpose
`connect_wallet`	Your app (after sign-in)	Authenticate user to Claimr
`on_request`	Claimr widget	Let dApp execute blockchain actions

API Guide

Webhooks Guide

SDK Guide

Guides

Integrate Claimr widget into your dApp

Run the project

Build for production (optional)

Claimr widget integration

App bootstrapping (example_app.tsx)

Wallet integration (wagmi.ts)

Connecting external wallets to the Claimr widget

Two-way integration

window.claimr.connect_wallet(address, signature, message)

`window.claimr.on_request = async (...) => { ... }`

Example flows

Campaign configuration: required settings

Summary

​Run the project

​Build for production (optional)

​Claimr widget integration

​App bootstrapping (example_app.tsx)

​Wallet integration (wagmi.ts)

​Connecting external wallets to the Claimr widget

​Two-way integration

​window.claimr.connect_wallet(address, signature, message)

​window.claimr.on_request = async (...) => { ... }

​Example flows

​Campaign configuration: required settings

​Summary

Run the project

Build for production (optional)

Claimr widget integration

App bootstrapping (example_app.tsx)

Wallet integration (wagmi.ts)

Connecting external wallets to the Claimr widget

Two-way integration

window.claimr.connect_wallet(address, signature, message)

`window.claimr.on_request = async (...) => { ... }`

Example flows

Campaign configuration: required settings

Summary