Integrate Claimr into a Vue or Nuxt app

This guide covers two setups:

Vue 3 with Vite: a client-rendered app, usually with Vue Router.
Nuxt 3 or 4: server-rendered, with a client-only plugin and a Nitro server route for user tokens.

Both use the same pattern: a plugin loads the script once and turns SDK callbacks into reactive state, a ClaimrWidget component renders the container, and a useClaimr() composable gives components access to state and methods.

Read How the loader works for the reasoning behind this layout. In short: the script loads once for the whole app, and the widget attaches to whichever ClaimrWidget is currently mounted.

Vue 3 with Vite

File	Purpose
`src/lib/claimr.ts`	Framework-agnostic loader, readiness helpers, and TypeScript types.
`src/plugins/claimr.ts`	Vue plugin: loads the script and provides reactive state.
`src/composables/useClaimr.ts`	Composable for Claimr state and SDK methods.
`src/components/ClaimrWidget.vue`	Renders the container the widget attaches to.

Add environment variables

.env

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

Add the shared loader module

Create src/lib/claimr.ts with the contents of the shared loader module.

Create the plugin

src/plugins/claimr.ts

import { App, InjectionKey, reactive, watch } from 'vue';
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;
  error: string | null;
  /** The user signed in to the widget, or null. */
  user: ClaimrUser | null;
  campaign: ClaimrCampaignInfo | null;
  /** User token from your server. Set it through useClaimr().setUserToken(). */
  userToken: string | null;
}

export const claimrKey: InjectionKey<ClaimrState> = Symbol('claimr');

export function createClaimr(options: Partial<ClaimrConfig> = {}) {
  const state = reactive<ClaimrState>({
    loaded: false,
    error: null,
    user: null,
    campaign: null,
    userToken: null,
  });

  return {
    install(app: App) {
      app.provide(claimrKey, state);

      loadClaimr(
        {
          organization: import.meta.env.VITE_CLAIMR_ORGANIZATION,
          campaign: import.meta.env.VITE_CLAIMR_CAMPAIGN,
          container: CLAIMR_CONTAINER_ID,
          autoresize: true,
          ...options,
        },
        // Runs on every fresh SDK instance. This is the only place callbacks are assigned.
        (claimr) => {
          claimr.on_user_info = (info) => (state.user = info);
          claimr.on_campaign_info = (info) => (state.campaign = info);
          claimr.on_logout = () => (state.user = null);
        },
      )
        .then(() => (state.loaded = true))
        .catch((err: Error) => (state.error = err.message));

      // Hand the user token to the widget once the script is loaded, and whenever it changes.
      watch(
        () => [state.loaded, state.userToken] as const,
        ([loaded, token]) => {
          if (loaded && token) getClaimr()?.set_user_token(token);
        },
      );
    },
  };
}

Create the composable

src/composables/useClaimr.ts

import { inject, toRefs } from 'vue';
import { getClaimr, withWidget } from '../lib/claimr';
import { claimrKey } from '../plugins/claimr';

export function useClaimr() {
  const state = inject(claimrKey);
  if (!state) throw new Error('useClaimr() needs app.use(createClaimr())');

  return {
    ...toRefs(state), // loaded, error, user, campaign, userToken as refs
    openQuest: (questId: string) => getClaimr()?.open_quest(questId),
    login: () => getClaimr()?.login(),
    completeTask: (taskId: string) => withWidget((c) => c.complete_task(taskId)),
    setLanguage: (code: string) => withWidget((c) => c.set_language(code)),
    setTheme: (theme: string) => withWidget((c) => c.set_theme(theme)),
    /** Pass the token for the signed-in user, or null when they sign out. */
    setUserToken: (token: string | null) => {
      state.userToken = token;
      if (!token) getClaimr()?.logout();
    },
  };
}

Create the widget component

src/components/ClaimrWidget.vue

<script setup lang="ts">
import { onUnmounted } from 'vue';
import { CLAIMR_CONTAINER_ID } from '../plugins/claimr';

onUnmounted(() => {
  // An open quest popup locks page scroll. Release it if the user navigates away mid-quest.
  document.body.style.overflow = '';
});
</script>

<template>
  <!-- Keep this element empty and do not bind an inline height: the loader owns both. -->
  <div :id="CLAIMR_CONTAINER_ID" class="claimr-widget" />
</template>

Render at most one ClaimrWidget at a time, and do not wrap it in <KeepAlive>. A kept-alive component is moved out of the document when it is deactivated, so the loader detaches the widget and reloads it on every reactivation.

Install the plugin

src/main.ts

import { createApp } from 'vue';
import App from './App.vue';
import router from './router';
import { createClaimr } from './plugins/claimr';

createApp(App).use(router).use(createClaimr()).mount('#app');

Pass options to override the defaults, for example createClaimr({ language: 'fr', platform: 'dapp' }).

Render the widget

src/views/QuestsView.vue

<script setup lang="ts">
import ClaimrWidget from '../components/ClaimrWidget.vue';
import { useClaimr } from '../composables/useClaimr';

const { user, error } = useClaimr();
</script>

<template>
  <section>
    <h1>Quests</h1>
    <p v-if="user">Signed in to Claimr</p>
    <p v-if="error">The quests could not be loaded. Disable your ad blocker and reload the page.</p>
    <ClaimrWidget />
  </section>
</template>

With Vue Router, other views do not render the container, so the loader detaches the widget when you leave this route and attaches it when you come back.

Use the SDK from components

src/components/LessonVideo.vue

<script setup lang="ts">
import { watch } from 'vue';
import { useI18n } from 'vue-i18n';
import { useClaimr } from '../composables/useClaimr';

const props = defineProps<{ taskId: string }>();
const { completeTask, setLanguage } = useClaimr();
const { locale } = useI18n();

// Follow the app's language.
watch(locale, (code) => setLanguage(code), { immediate: true });
</script>

<template>
  <!-- Mark a front-end task as complete when the user finishes the video. -->
  <video src="/lesson.mp4" controls @ended="completeTask(props.taskId)" />
</template>

complete_task only works for tasks configured as front-end tasks in the campaign. See SDK tasks.

Sign users in with your own accounts

Generate the token on your backend with your secret API token. Never call the token endpoint from Vue 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, then pass the token to the composable whenever your app’s user changes:

src/App.vue

// Inside <script setup lang="ts">
import { watch } from 'vue';
import { useClaimr } from './composables/useClaimr';
import { useAuthStore } from './stores/auth'; // your app's auth store

const auth = useAuthStore();
const { setUserToken } = useClaimr();

watch(
  () => auth.user?.id,
  async (id) => {
    if (!id) return setUserToken(null);
    const { token } = await fetch('/api/claimr-token', { credentials: 'include' }).then((r) => r.json());
    setUserToken(token);
  },
  { immediate: true },
);

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

Using Pinia? You can keep ClaimrState in a Pinia store instead of provide/inject. Keep the rule the same: the plugin that loads the script is the only code that assigns SDK callbacks, and it writes into the store.

Nuxt

This setup works with Nuxt 3 and Nuxt 4. Paths are relative to your source directory: the project root in Nuxt 3, or app/ in Nuxt 4. Server files always live in server/ at the project root.

File	Runs on	Purpose
`lib/claimr.ts`	Browser	Framework-agnostic loader, readiness helpers, and TypeScript types.
`composables/useClaimr.ts`	Both	Shared state through `useState`, plus SDK methods. Auto-imported.
`plugins/claimr.client.ts`	Browser	Loads the script after hydration and assigns callbacks.
`components/ClaimrWidget.vue`	Both	Renders the container. Auto-imported.
`server/api/claimr/token.get.ts`	Server	Returns a user token to the signed-in user. Optional.

Add runtime config

nuxt.config.ts

export default defineNuxtConfig({
  runtimeConfig: {
    // Server only. Set with NUXT_CLAIMR_API_TOKEN and NUXT_CLAIMR_PLATFORM.
    claimrApiToken: '',
    claimrPlatform: '',
    public: {
      // Browser. Set with NUXT_PUBLIC_CLAIMR_ORGANIZATION and NUXT_PUBLIC_CLAIMR_CAMPAIGN.
      claimrOrganization: '',
      claimrCampaign: '',
    },
  },
});

.env

NUXT_PUBLIC_CLAIMR_ORGANIZATION=your-organization-id
NUXT_PUBLIC_CLAIMR_CAMPAIGN=your-campaign-id
NUXT_CLAIMR_API_TOKEN=your-secret-api-token
NUXT_CLAIMR_PLATFORM=your-platform-name

Add the shared loader module

Create lib/claimr.ts with the contents of the shared loader module. It guards every window access, so importing it during server rendering is safe.

Create the composable

useState gives you state that is shared across components and safe to use during server rendering.

composables/useClaimr.ts

import { getClaimr, withWidget, type ClaimrCampaignInfo, type ClaimrUser } from '~/lib/claimr';

export const CLAIMR_CONTAINER_ID = 'claimr-widget';

export interface ClaimrState {
  loaded: boolean;
  error: string | null;
  user: ClaimrUser | null;
  campaign: ClaimrCampaignInfo | null;
  userToken: string | null;
}

export const useClaimrState = () =>
  useState<ClaimrState>('claimr', () => ({
    loaded: false,
    error: null,
    user: null,
    campaign: null,
    userToken: null,
  }));

export function useClaimr() {
  const state = useClaimrState();

  return {
    state, // Ref<ClaimrState>: use state.value.user, state.value.loaded, and so on
    openQuest: (questId: string) => getClaimr()?.open_quest(questId),
    login: () => getClaimr()?.login(),
    completeTask: (taskId: string) => withWidget((c) => c.complete_task(taskId)),
    setLanguage: (code: string) => withWidget((c) => c.set_language(code)),
    setTheme: (theme: string) => withWidget((c) => c.set_theme(theme)),
    setUserToken: (token: string | null) => {
      state.value.userToken = token;
      if (!token) getClaimr()?.logout();
    },
  };
}

Create the client plugin

The .client suffix keeps the plugin out of server rendering. onNuxtReady delays loading until hydration is finished, so the loader never adds its iframe to server-rendered markup that Vue is still hydrating.

plugins/claimr.client.ts

import { getClaimr, loadClaimr } from '~/lib/claimr';

export default defineNuxtPlugin(() => {
  const config = useRuntimeConfig();
  const state = useClaimrState();

  onNuxtReady(() => {
    loadClaimr(
      {
        organization: config.public.claimrOrganization,
        campaign: config.public.claimrCampaign,
        container: CLAIMR_CONTAINER_ID,
        autoresize: true,
      },
      (claimr) => {
        claimr.on_user_info = (info) => (state.value.user = info);
        claimr.on_campaign_info = (info) => (state.value.campaign = info);
        claimr.on_logout = () => (state.value.user = null);
      },
    )
      .then(() => (state.value.loaded = true))
      .catch((err: Error) => (state.value.error = err.message));
  });

  watch(
    () => [state.value.loaded, state.value.userToken] as const,
    ([loaded, token]) => {
      if (loaded && token) getClaimr()?.set_user_token(token);
    },
  );
});

Create the widget component

components/ClaimrWidget.vue

<script setup lang="ts">
import { CLAIMR_CONTAINER_ID } from '~/composables/useClaimr';

onUnmounted(() => {
  // An open quest popup locks page scroll. Release it if the user navigates away mid-quest.
  document.body.style.overflow = '';
});
</script>

<template>
  <!-- Keep this element empty and do not bind an inline height: the loader owns both. -->
  <div :id="CLAIMR_CONTAINER_ID" class="claimr-widget" />
</template>

There is no need for <ClientOnly>. The empty <div> renders on the server, and the widget attaches to it in the browser.

Render the widget on a page

pages/quests.vue

<script setup lang="ts">
const { state } = useClaimr();
</script>

<template>
  <main>
    <h1>Quests</h1>
    <p v-if="state.user">Signed in to Claimr</p>
    <ClaimrWidget />
  </main>
</template>

Navigating with <NuxtLink> to a page without ClaimrWidget detaches the widget. Coming back attaches it again.

Sign users in with your own accounts (Nuxt)

Create the server route

The route reads your secret API token from server-only runtime config. This example uses nuxt-auth-utils; replace requireUserSession with your auth library’s equivalent.

server/api/claimr/token.get.ts

export default defineEventHandler(async (event) => {
  const { user } = await requireUserSession(event);
  const config = useRuntimeConfig(event);

  const response = await $fetch<{ success: boolean; data: { token: string } }>(
    'https://prod.claimr.io/api/v1/token',
    {
      query: { account: user.id, platform: config.claimrPlatform, name: user.name },
      headers: { Authorization: `Bearer ${config.claimrApiToken}` },
    },
  );

  return { token: response.data.token };
});

The token never expires. Store it with your user record to avoid calling Claimr on every request.

Pass the token to the widget

plugins/claimr-auth.client.ts

export default defineNuxtPlugin(() => {
  const { loggedIn } = useUserSession(); // from nuxt-auth-utils, or your auth library
  const { setUserToken } = useClaimr();

  watch(
    loggedIn,
    async (isLoggedIn) => {
      if (!isLoggedIn) return setUserToken(null);
      const { token } = await $fetch('/api/claimr/token');
      setUserToken(token);
    },
    { immediate: true },
  );
});

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

Wallets and Telegram

dApp with its own wallet: pass platform: 'dapp' in the loader config and assign window.claimr.on_wallet_request once your wallet library is ready. The handler receives { op, ...params } for connect, sign_message, send_transaction, and disconnect, and must return a result or throw. See on_wallet_request and the React wallet bridge, which translates directly to a Vue component using @wagmi/vue.
Telegram Mini App: pass platform: 'telegram'. See Telegram Mini App.

Verify the integration

Open the page with ClaimrWidget. The campaign renders inside the container.
In the browser console, window.claimr.is_claimr_ready returns true.
Navigate to another route and back. The widget comes back, and document.querySelectorAll('#claimr-script').length is still 1.
In Nuxt, the server log and browser console show no hydration mismatch warnings for the widget container.
If you use user tokens, sign in to your app and confirm the widget shows the same user without a second sign-in.

API Guide

Webhooks Guide

SDK Guide

Framework Integration

Guides

Integrate Claimr into a Vue or Nuxt app

Vue 3 with Vite

Use the SDK from components

Sign users in with your own accounts

Nuxt

Sign users in with your own accounts (Nuxt)

Wallets and Telegram

Verify the integration

​Vue 3 with Vite

​Use the SDK from components

​Sign users in with your own accounts

​Nuxt

​Sign users in with your own accounts (Nuxt)

​Wallets and Telegram

​Verify the integration

Vue 3 with Vite

Use the SDK from components

Sign users in with your own accounts

Nuxt

Sign users in with your own accounts (Nuxt)

Wallets and Telegram

Verify the integration