Integrate claimr widget into dApp

Use this tutorial to integrate the claimr widget with a custom wallet connection in your dApp, including instructions for anonymous or privacy-preserving setups.

Introduction

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.

1. Navigate to your project directory:

cd path/to/claimr-dapp-example

1. Install dependencies:

Using npm:

npm install

Using Yarn:

yarn

1. Start the development server:

Using npm:

npm start

Using Yarn:

yarn start

1. Visit your app at:

http://localhost:3000

Build for production (optional)

To create a production-ready build:

npm run build

Or

yarn build

This will create a production-ready build/ folder.

claimr widget integration

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 is 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 the following:

• 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 is from WalletConnect (required by RainbowKit)

Connecting external wallets to claimr widget

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;
}

on_request function handles:

1. Switching chains if needed (switchChainAsync)

2. Calling a contract method with:

• abi, contract, method, args, and chain_id

1. 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 user opens the app:

• React app loads

• ClaimrWrapper injects the widget

• If localStorage['demo-signature'] exists, it’s reused

• Otherwise: shows “Connect wallet → Sign in” prompt

When user signs the message:

• signMessageAsync() signs a claimr-auth message

• Signature is saved inlocalStorage

• window.claimr.connect_wallet(...) is called to complete login

When the widget needs to interact with blockchain:

• Widget emits widget::ready event

• Your app assigns the on_request handler

• claimr can now ask your app to:

  • Switch chains

  • Execute contract calls

Campaign configuration: required settings

To ensure the claimr widget works correctly with your dApp, make sure to configure the campaign settings accordingly.

1. Navigate to Sign-in options:

• Open your Claimr dashboard.

• Go to your specific campaign.

• Click on Settings in the left-hand menu.

• Select Sign-in options.

1. Set the following 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 would require 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.

1. Select Wallet to allow wallet-based login in the Select sign-in services field.

2. Select the correct blockchain in the Chains field.

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