Integrate Claimr into a React app

This guide adds Claimr to a client-rendered React app (Vite, Create React App, or any React Router setup). For Next.js, follow the Next.js guide instead, since it adds server-side rendering and server routes. You will build four small pieces:

File	Purpose
`src/lib/claimr.ts`	Framework-agnostic loader, readiness helpers, and TypeScript types.
`src/claimr/ClaimrProvider.tsx`	Loads the script once, assigns SDK callbacks, and shares user and campaign state through context.
`src/claimr/ClaimrWidget.tsx`	Renders the container the widget attaches to. Place it on any page or route.
`src/claimr/useClaimr.ts`	Hook for reading Claimr state and calling SDK methods from components.

Read How the loader works first if you want to understand why the code is split this way. In short: the script loads once at the app root, and the widget attaches to whichever container is currently rendered.

Prerequisites

React 18 or later.
Your organization ID and campaign ID from Publish > Get embed code in the Claimr admin panel.

Set up the integration

Add environment variables

Create or update .env in your project root. These values are public.

.env

VITE_CLAIMR_ORGANIZATION=your-organization-id
VITE_CLAIMR_CAMPAIGN=your-campaign-id

With Create React App, use the REACT_APP_ prefix and read them from process.env instead of import.meta.env.

Add the shared loader module

Create src/lib/claimr.ts with the contents of the shared loader module. Copy it as is. It has no dependencies.

Create the provider

The provider is the only place that loads the script and assigns callbacks. It turns SDK callbacks into React state.

src/claimr/ClaimrProvider.tsx

import { createContext, ReactNode, useEffect, useMemo, useState } from 'react';
import {
  ClaimrCampaignInfo,
  ClaimrConfig,
  ClaimrUser,
  getClaimr,
  loadClaimr,
} from '../lib/claimr';

export const CLAIMR_CONTAINER_ID = 'claimr-widget';

export interface ClaimrState {
  /** The script has loaded and window.claimr exists. */
  loaded: boolean;
  /** The script failed to load, for example because an ad blocker blocked it. */
  error: Error | null;
  /** The user signed in to the widget, or null. */
  user: ClaimrUser | null;
  campaign: ClaimrCampaignInfo | null;
}

export const ClaimrContext = createContext<ClaimrState | null>(null);

interface Props {
  children: ReactNode;
  /** Optional user token generated by your server for the signed-in user. */
  userToken?: string;
  language?: string;
}

export function ClaimrProvider({ children, userToken, language }: Props) {
  const [loaded, setLoaded] = useState(false);
  const [error, setError] = useState<Error | null>(null);
  const [user, setUser] = useState<ClaimrUser | null>(null);
  const [campaign, setCampaign] = useState<ClaimrCampaignInfo | null>(null);

  useEffect(() => {
    const config: ClaimrConfig = {
      organization: import.meta.env.VITE_CLAIMR_ORGANIZATION,
      campaign: import.meta.env.VITE_CLAIMR_CAMPAIGN,
      container: CLAIMR_CONTAINER_ID,
      autoresize: true,
      language,
      userToken,
    };

    // loadClaimr is idempotent, so Strict Mode's double effect is harmless.
    loadClaimr(config, (claimr) => {
      claimr.on_user_info = (info) => setUser(info);
      claimr.on_campaign_info = (info) => setCampaign(info);
      claimr.on_logout = () => setUser(null);
    })
      .then(() => setLoaded(true))
      .catch(setError);
    // Load once. Later prop changes are applied by the effects below.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);

  // Keep the widget's user in sync with your app's user.
  useEffect(() => {
    if (!loaded) return;
    const claimr = getClaimr();
    if (userToken) claimr?.set_user_token(userToken);
  }, [loaded, userToken]);

  const value = useMemo(() => ({ loaded, error, user, campaign }), [loaded, error, user, campaign]);

  return <ClaimrContext.Provider value={value}>{children}</ClaimrContext.Provider>;
}

Create the widget component

The widget component only renders the container. The loader notices it and attaches the widget. When the component unmounts, the loader removes the widget on its own.

src/claimr/ClaimrWidget.tsx

import { useEffect } from 'react';
import { CLAIMR_CONTAINER_ID } from './ClaimrProvider';

interface Props {
  className?: string;
}

export function ClaimrWidget({ className }: Props) {
  useEffect(() => {
    return () => {
      // An open quest popup locks page scroll. Release it if the user navigates away mid-quest.
      document.body.style.overflow = '';
    };
  }, []);

  // Keep this element empty and do not bind an inline height: the loader owns both.
  return <div id={CLAIMR_CONTAINER_ID} className={className} />;
}

Render at most one ClaimrWidget at a time. The loader attaches to the first element with the container ID.

Create the hook

src/claimr/useClaimr.ts

import { useCallback, useContext } from 'react';
import { getClaimr, withWidget } from '../lib/claimr';
import { ClaimrContext } from './ClaimrProvider';

export function useClaimr() {
  const state = useContext(ClaimrContext);
  if (!state) throw new Error('useClaimr must be used inside <ClaimrProvider>');

  const openQuest = useCallback((questId: string) => getClaimr()?.open_quest(questId), []);
  const login = useCallback(() => getClaimr()?.login(), []);
  const logout = useCallback(() => getClaimr()?.logout(), []);
  const completeTask = useCallback((taskId: string) => withWidget((c) => c.complete_task(taskId)), []);
  const setLanguage = useCallback((code: string) => withWidget((c) => c.set_language(code)), []);
  const setTheme = useCallback((theme: string) => withWidget((c) => c.set_theme(theme)), []);

  return { ...state, openQuest, login, logout, completeTask, setLanguage, setTheme };
}

Wrap your app

Wrap the whole app once, above your router, so the script survives route changes.

src/main.tsx

import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
import { ClaimrProvider } from './claimr/ClaimrProvider';
import { App } from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ClaimrProvider>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </ClaimrProvider>
  </StrictMode>,
);

Render the widget

Place ClaimrWidget on the page or route where the campaign should appear.

src/pages/QuestsPage.tsx

import { ClaimrWidget } from '../claimr/ClaimrWidget';
import { useClaimr } from '../claimr/useClaimr';

export function QuestsPage() {
  const { user, error } = useClaimr();

  return (
    <section>
      <h1>Quests</h1>
      {user && <p>Signed in to Claimr</p>}
      {error && <p>The quests could not be loaded. Disable your ad blocker and reload the page.</p>}
      <ClaimrWidget className="claimr-widget" />
    </section>
  );
}

With React Router, other routes simply do not render the container, and the loader detaches the widget when you leave this route.

Use the SDK from components

Call SDK methods through the hook. Methods that need a loaded widget are wrapped in withWidget, so they are safe to call at any time.

import { useEffect } from 'react';
import { useTranslation } from 'react-i18next';
import { useClaimr } from '../claimr/useClaimr';

export function VideoLesson({ taskId }: { taskId: string }) {
  const { completeTask, setLanguage } = useClaimr();
  const { i18n } = useTranslation();

  // Follow the app's language.
  useEffect(() => {
    setLanguage(i18n.language);
  }, [i18n.language, setLanguage]);

  // Mark a front-end task as complete when the user finishes the video.
  return <video src="/lesson.mp4" controls onEnded={() => completeTask(taskId)} />;
}

complete_task only works for tasks configured as front-end tasks in the campaign. See SDK tasks. To react to other widget events, add more callbacks in the provider’s setup function, for example claimr.on_leaderboard_open or claimr.on_analytics_event, and expose them through context. Do not assign callbacks from other components: each callback has a single owner, so the last assignment wins.

Sign users in with your own accounts

If your users already sign in to your app, give them a Claimr user token so they do not have to sign in again inside the widget.

Generate the token on your server

Your API token is secret. Call the token endpoint from your backend, never from React code.

server/claimr-token.ts

export async function getClaimrUserToken(account: string, name?: string): Promise<string> {
  const url = new URL('https://prod.claimr.io/api/v1/token');
  url.searchParams.set('account', account); // your stable user ID
  url.searchParams.set('platform', process.env.CLAIMR_PLATFORM!); // a short name for your platform, not "claimr"
  if (name) url.searchParams.set('name', name);

  const response = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.CLAIMR_API_TOKEN}` },
  });
  const body = await response.json();
  if (!response.ok || !body.success) throw new Error('Claimr token request failed');
  return body.data.token as string;
}

Expose it through an authenticated endpoint of your own, for example GET /api/claimr-token, that reads the current user from the session. The token does not expire, so you can store it with the user record.

Pass the token to the provider

Wrap ClaimrProvider in a component that knows your signed-in user, and use it in main.tsx in place of the plain <ClaimrProvider>. It must render inside your auth provider.

src/claimr/ClaimrAuthProvider.tsx

import { ReactNode, useEffect, useState } from 'react';
import { ClaimrProvider } from './ClaimrProvider';
import { useAuth } from '../auth'; // your app's auth hook

export function ClaimrAuthProvider({ children }: { children: ReactNode }) {
  const { user } = useAuth();
  const [claimrToken, setClaimrToken] = useState<string>();

  useEffect(() => {
    if (!user) return setClaimrToken(undefined);
    fetch('/api/claimr-token', { credentials: 'include' })
      .then((r) => r.json())
      .then((body) => setClaimrToken(body.token));
  }, [user]);

  return <ClaimrProvider userToken={claimrToken}>{children}</ClaimrProvider>;
}

Log out of Claimr when the user logs out of your app

import { getClaimr } from './lib/claimr';

async function signOut() {
  await yourAuth.signOut();
  getClaimr()?.logout();
}

When a different user signs in without a page reload, call logout() before the new token reaches set_user_token.

Enable the matching sign-in option in the campaign under Settings > Sign-in options.

Connect the user’s wallet (dApps)

If your app already connects a wallet, let the widget use it instead of asking the user to connect again. Set platform: 'dapp' in the provider config and implement on_wallet_request. This example uses wagmi and RainbowKit, and must render inside WagmiProvider and RainbowKitProvider.

src/claimr/ClaimrWalletBridge.tsx

import { useEffect, useRef } from 'react';
import { useConnectModal } from '@rainbow-me/rainbowkit';
import { useAccount, useChainId, useDisconnect, useSignMessage, useSwitchChain, useWriteContract } from 'wagmi';
import type { Abi, Address } from 'viem';
import { getClaimr, type ClaimrWalletRequest } from '../lib/claimr';

/** Answers the widget's wallet requests with the wallet your app already manages. Render once. */
export function ClaimrWalletBridge() {
  const { address } = useAccount();
  const chainId = useChainId();
  const { openConnectModal } = useConnectModal();
  const { signMessageAsync } = useSignMessage();
  const { writeContractAsync } = useWriteContract();
  const { switchChainAsync } = useSwitchChain();
  const { disconnect } = useDisconnect();

  useEffect(() => {
    const handler = async (request: ClaimrWalletRequest) => {
      switch (request.op) {
        case 'connect':
          if (address) return { address, chain: String(chainId) };
          openConnectModal?.();
          throw new Error('The user has not connected a wallet yet');
        case 'sign_message':
          return { signature: await signMessageAsync({ message: request.message }) };
        case 'send_transaction': {
          const target = Number(request.chain_id);
          if (target !== chainId) await switchChainAsync({ chainId: target });
          const hash = await writeContractAsync({
            abi: request.abi as Abi,
            address: request.contract as Address,
            functionName: request.method,
            args: request.args,
            chainId: target,
          });
          return { hash };
        }
        case 'disconnect':
          disconnect();
          return {};
      }
    };

    // The handler closes over the latest wallet state, so reassign it when that state changes.
    const claimr = getClaimr();
    if (claimr) claimr.on_wallet_request = handler;
  }, [address, chainId, openConnectModal, signMessageAsync, writeContractAsync, switchChainAsync, disconnect]);

  // Log the widget out when the wallet disconnects or changes. Comparing with the previous address
  // skips the page load, when wagmi briefly reports no address while it reconnects.
  const previousAddress = useRef(address);
  useEffect(() => {
    if (previousAddress.current && previousAddress.current !== address) getClaimr()?.logout();
    previousAddress.current = address;
  }, [address]);

  return null;
}

Render ClaimrWalletBridge inside ClaimrProvider and only after the provider reports loaded, for example {loaded && <ClaimrWalletBridge />}. That guarantees window.claimr exists when the handler is assigned.

Each op must return a value or throw. Throwing reports a failure to the widget immediately, instead of leaving it waiting. See on_wallet_request for the full contract and Integrate Claimr widget into your dApp for the campaign settings a dApp needs.

Verify the integration

Run the app and open the page with ClaimrWidget. The campaign renders inside the container.
In the browser console, run window.claimr.is_claimr_ready. It returns true.
Navigate to another route and back. The widget disappears and comes back, and document.querySelectorAll('#claimr-script').length is still 1.
Open a quest, then press the browser back button. The page still scrolls.
If you use user tokens, sign in to your app and confirm the widget shows the same user without a second sign-in.

To see what the loader is doing, add debug: true to the provider config. The loader then logs its steps to the console.

API Guide

Webhooks Guide

SDK Guide

Framework Integration

Guides

Integrate Claimr into a React app

Prerequisites

Set up the integration

Use the SDK from components

Sign users in with your own accounts

Connect the user’s wallet (dApps)

Verify the integration

​Prerequisites

​Set up the integration

​Use the SDK from components

​Sign users in with your own accounts

​Connect the user’s wallet (dApps)

​Verify the integration

Prerequisites

Set up the integration

Use the SDK from components

Sign users in with your own accounts

Connect the user’s wallet (dApps)

Verify the integration