# API methods
Source: https://docs.claimr.io/api-guide/api-methods
A conceptual guide to Claimr's API methods, organized by category. For exact parameters, request bodies, and live testing, use the API Playground.
This page groups Claimr's API methods by what they're used for. For the full request/response schema of any method and to try it live, open its page in the **API Playground** tab, or follow the links below.
## Webhooks
Manage real-time event updates by subscribing to specific user activities through webhooks.
* [Set Webhook](/api-reference/webhooks/set-webhook) - register a webhook URL to receive notifications when specific user events occur on the platform.
* [Remove Webhook](/api-reference/webhooks/remove-webhook) - unregister an existing webhook to stop receiving notifications for a given scope and hook ID.
## User token
Generate a permanent token to authenticate users in the Claimr widget.
* [Get User Token](/api-reference/user-token/get-user-token) - create or retrieve a user token. If the user doesn't exist, they'll be registered automatically.
Usage:
* **Production**: Add the token to the `data-user-token` attribute in the embed script.
* **Development**: Append it as a `user_token` query parameter in the widget preview URL.
## User
Manage referral data, activity, and rewards.
* [Get Referral ID](/api-reference/user/get-referral-id) - fetch a user's referral ID and create a referral link if it doesn't already exist.
* [Set Referrer ID](/api-reference/user/set-referrer-id) - set a user's referral ID to track who referred them.
* [Set Referrer](/api-reference/user/set-referrer) - manually set the referrer of a user using the referrer's account information.
* [Get User Activity](/api-reference/user/get-user-activity) - fetch a full list of completed items by a user, including tasks, quests, rewards, and XP earned.
* [Get User Progress](/api-reference/user/get-user-progress) - get a full overview of a user's progress, including both completed and pending tasks and quests.
* [Get Referral Data](/api-reference/user/get-referral-data) - return a list of users referred by a specific user and their referral impact.
* [Get XP Balance](/api-reference/user/get-xp-balance) - check a user's current XP balance, including XP from tasks, referrals, and UGC.
* [Award XP Reward](/api-reference/user/award-xp-reward) - reward a user for an off-platform action (e.g. within your app) by adding XP to their balance.
* [Withdraw User Points](/api-reference/user/withdraw-user-points) - deduct XP points from a user's balance (e.g. to revoke a reward).
All information about the points for each user can be checked in Analytics. To find out more, read our article [User information](/data-analytics/user-information).
## Tasks
Trigger specific actions and reward users by defining task types and their completion criteria within a campaign.
* [Set Task Value](/api-reference/tasks/set-task-value) - set or update a numeric attribute of a user's action (e.g., likes, followers). Used with [API Number Value tasks](/tasks/api-tasks).
* [Push Stream Value](/api-reference/tasks/push-stream-value) - accumulate numeric attributes associated with user actions (e.g., total transactions) across all matching stream tasks in a campaign. Used with [API Stream Value tasks](/tasks/api-tasks).
## Events
Track custom user actions by pushing event data to Claimr. Events can be used to trigger task completions based on user behavior.
* [Push Custom Event](/api-reference/events/push-custom-event) - create a custom event record associated with a user for tracking and triggering downstream processes, with optional categorization and a custom data payload.
* [Get Custom Events](/api-reference/events/get-custom-events) - retrieve all custom events associated with a user, filterable by category and name.
### Connecting events to tasks
When you create a task in Claimr with the type Events, Claimr listens for `POST /event` calls matching the criteria you define.
* **Events count task**: For an "Events count" task, Claimr tracks how many times an event with a specific category and name occurs. For example, if you set up a task to reward users after they achieve 10 likes, Claimr counts each incoming like event via `POST /event`. Once the count reaches 10, the reward is automatically triggered.
* **User identification**: Claimr identifies the user associated with the event using the `account` and `platform` fields in the payload. For example, if a user logs in with Web3 (using their wallet), Claimr uses the wallet address to link the event to the correct user. This ensures that points and completions are attributed accurately.
For more information about configuration, read our article on Events tasks.
## Campaign
Access campaign-level data, including task structure, season progress, and participation statistics. Useful for both live and development environments.
* [Get Campaign Info](/api-reference/campaign/get-campaign-info) - returns detailed campaign information including all tasks and quests, for both published and development environments.
* [Get Campaign Points](/api-reference/campaign/get-campaign-points) - returns campaign points and season information, calculating season progression based on configured thresholds.
* [Get Campaign Stats](/api-reference/campaign/get-campaign-stats) - returns comprehensive campaign statistics including points awarded and participation metrics.
## Invite codes
Control access to your campaign by issuing, assigning, and managing invite codes linked to user identifiers.
* [Get Invite Code Status](/api-reference/invite-codes/get-invite-code-status) - retrieve information about an invite code, including which users have used it.
* [Use Invite Code](/api-reference/invite-codes/use-invite-code) - assign an invite code to a user (identified by wallet address). This also handles user registration if the address is new, creates campaign entries, and marks the code as used.
* [Release Invite Code](/api-reference/invite-codes/release-invite-code) - release an invite code that was previously assigned to a user, making it available again.
## Wallets
Use these endpoints to award or withdraw XP and manage invite codes based on user wallet addresses. This is especially useful for blockchain-based campaigns where users interact via Web3 wallets.
* [Get Wallet Invite Code](/api-reference/wallets/get-wallet-invite-code) - returns the invite code used by a specific wallet.
* [Get Wallet Referral ID](/api-reference/wallets/get-wallet-referral-id) - returns a wallet's referral ID for a specific campaign.
* [Award Wallet XP](/api-reference/wallets/award-wallet-xp) - award an XP reward to a wallet for actions performed outside Claimr.
* [Withdraw Wallet Points](/api-reference/wallets/withdraw-wallet-points) - withdraw XP points from a wallet's balance.
## Leaderboard
Track user performance and rank participants based on the points they've earned in your campaign. The leaderboard helps you highlight top contributors, motivate engagement, and display rankings in real time.
* [Get Leaderboard](/api-reference/leaderboard/get-leaderboard) - retrieve leaderboard data for a specific campaign. Supports both the v1 format (a basic version available for all campaigns, returning a ranked list of up to 100-150 users) and the v2 format (an advanced, unlimited version available with selected packages).
## Custom API methods and integrations
Claimr offers extensive flexibility beyond its standard API methods, allowing for seamless integration with your proprietary systems.
If your project requires unique data handling or custom API endpoints tailored to your specific needs, we can create these custom API methods upon request. Contact our support team to enable this advanced feature.
# API token
Source: https://docs.claimr.io/api-guide/api-token
Generate your organization's API token and use it to authorize requests to the Claimr API.
All API requests to the Claimr system require authorization to ensure secure access and protect your organization's data. This authorization is handled through the use of an API token.
* The Claimr API token acts as your organization's key to access the API. It is associated with your organization as a whole, not with individual users.
* Keep your API token confidential and store it securely. Any API requests made without a valid API token will be rejected as unauthorized.
## Generate and authorize your API token
Navigate to the API section within the Claimr admin panel.
Click **Generate Token**. A pop-up window will appear displaying your unique API token.
Copy this token and store it in a secure location. Once you close the pop-up, you will not be able to retrieve this token again.
Open the [API Playground](/api-reference/user-token/get-user-token) and click **Authorize**. A dialog box will appear, prompting you to enter your API token.
Paste your copied API token into the designated field and click **Authorize** to complete the authorization process.
For troubleshooting or support, reach our Claimr support team or email us at [support@claimr.io](mailto:support@claimr.io).
# API
Source: https://docs.claimr.io/api-guide/overview
See what you can do with the Claimr API - retrieve user information, check balances, monitor activity, and subscribe to webhooks.
By understanding the Claimr API and utilizing your API token correctly, you can integrate Claimr's functionalities into your system and unlock new possibilities for data analysis.
**What can you do with the Claimr API?**
* **Retrieve user information**: Access data about users who have interacted with your Claimr campaigns, such as their progress, rewards earned, and participation history.
* **Check balances**: Retrieve information about user point balances tracked within your campaigns, including total points (sum of all points), referral points, and user-generated content (UGC) points.
* **Monitor user activity**: Track user actions and engagement within your Claimr campaigns, providing valuable insights into user behavior and campaign performance.
* **Subscribe to webhooks**: Receive real-time updates on events happening within your campaigns, such as task completions, reward claims, or new user registrations. This allows your system to react dynamically to user actions and provide a more personalized experience.
Generate and authorize the token that secures every request to the Claimr API.
Browse the full set of endpoints for webhooks, users, tasks, campaigns, and more.
Link your users' accounts on your platform to their Claimr profiles.
Read campaign and user statistics directly from your frontend.
# Public API
Source: https://docs.claimr.io/api-guide/public-api
Generate a Public token to read campaign and user statistics directly from your frontend with read-only GET endpoints.
Use the Public API to read campaign and user statistics directly from your frontend. It uses a separate **Public token** that you can generate in the dashboard.
## Generate and manage your Public token
Go to **Settings → Public API**.
If no token exists, select **Generate token**.
Copy the value shown under **Public token** and use it in your requests.
To immediately invalidate the token, select **Revoke token**. You can generate a new token at any time.
The Public token only allows read access to the endpoints listed below. It cannot modify data.
### Authentication and request format
All Public API endpoints are **GET** requests. Provide the token and context using query parameters:
* `pid` - Campaign ID (string or number).
* `account` - A unique identifier for the user within your system (for example, user ID or email hash).
* `platform` - A short name representing your organization or platform.
* `pub` - Your Public token.
Base URL: use your assigned environment base (for example, `https://{base}/public/api/...`). Paths below are shown without host for clarity.
## API methods
### GET /public/api/user
Get basic user info and stats for an account in a campaign.
Example request:
```json theme={"dark"}
{
"pid": "string",
"account": "string",
"platform": "string",
"pub": "string"
}
```
Field explanations:
* `pid`: The campaign ID.
* `account`: The user's ID.
* `platform`: The user's platform.
* `pub`: Your Public token.
Example response:
```json theme={"dark"}
{
"id": "string",
"name": "string",
"ref_id": "string",
"ref_xp": 0,
"ugc_xp": 0,
"xp": 0,
"xp_mul": 0,
"rank": 0
}
```
### GET /public/api/user/refs
Get user info plus the user's referrals.
Example request:
```json theme={"dark"}
{
"pid": "string",
"account": "string",
"platform": "string",
"pub": "string"
}
```
Field explanations:
* `pid`: The campaign ID.
* `account`: The user's ID.
* `platform`: The user's platform.
* `pub`: Your Public token.
Example response:
```json theme={"dark"}
{
"id": "string",
"name": "string",
"ref_id": "string",
"ref_xp": 0,
"ugc_xp": 0,
"xp": 0,
"xp_mul": 0,
"rank": 0,
"referrals": [
{
"id": "string",
"name": "string",
"valid": true,
"ref_xp": 0,
"xp": 0,
"cts": "2024-01-01T00:00:00Z"
}
]
}
```
### GET /public/api/entries/count
Get the number of entries for the provided context.
Example request:
```json theme={"dark"}
{
"pid": "string",
"platform": "string",
"pub": "string"
}
```
Field explanations:
* `pid`: The campaign ID.
* `platform`: The user's platform.
* `pub`: Your Public token.
Example response:
```json theme={"dark"}
{ "count": 0 }
```
### GET /public/api/campaign/stats
Get aggregated statistics for a campaign.
Example request:
```json theme={"dark"}
{
"pid": "string",
"platform": "string",
"pub": "string"
}
```
Field explanations:
* `pid`: The campaign ID.
* `platform`: The user's platform.
* `pub`: Your Public token.
Example response:
```json theme={"dark"}
{
"participants": 0,
"tasks_completed": 0,
"quests_completed": 0,
"xp": 0
}
```
### Security notes
* The Public token is safe to use on the frontend for the endpoints listed here, but treat it as a secret for your organization. Rotate it by using **Revoke token** and **Generate token** if it is exposed.
* Do not use the Public API for any sensitive queries. Use the server-side API for those cases.
## Troubleshooting
* **401/403**: Verify `pub` is present and correct. If you revoked the token, generate a new one and update your site.
* **429**: Reduce frequency of calls or cache responses on the client.
* **CORS**: Ensure you are calling the correct base domain for your environment.
For troubleshooting or support, contact Claimr support at [support@claimr.io](mailto:support@claimr.io).
# User token
Source: https://docs.claimr.io/api-guide/user-token
Integrate user tokens to seamlessly track user progress within your campaigns without asking users to log in separately.
## Understanding user tokens
User tokens are like digital keys that link your users' accounts on your platform to their Claimr profiles. This connection allows for a smoother, more personalized experience within your campaigns.
### How it works
Your users already have accounts on your platform - whether it's a mobile app, a website, or a crypto exchange. They've signed up, verified their identity, and are ready to engage with your Claimr campaigns.
Instead of asking them to create another account or log in separately for Claimr, user tokens let you seamlessly connect their existing account with their Claimr activity.
### Behind the scenes
* Your application sends a special request to the Claimr server to generate a unique token for each user.
* This token is then included in the Claimr widget that you embed on your platform.
* When a user opens the widget, Claimr uses the token to identify them and personalize their experience.
### Benefits of user tokens
* **No extra logins**: Users enjoy a frictionless experience without having to remember separate credentials.
* **Personalized content**: You can tailor the Claimr experience to each user's preferences and progress.
* **Seamless cross-device experience**: Users can access their Claimr profile and progress from any device, as long as they're logged in to your platform.
## Generate user token
To generate a user token, follow these steps:
### Initiate token request
Send a GET request to the `/token` endpoint from your server.
Include the following required parameters in your request:
* **Account**: A unique identifier for the user within your system (e.g., user ID, email address).
* **Platform**: A short name representing your organization or platform.
* **Authorization**: Include your organization's secret API token as a Bearer authorization header in the request. This authenticates your application's access to the token generation endpoint.
### Response
Upon successful request, a unique user token will be generated and returned in the response. This token is permanent and does not expire. You can store it securely to avoid repeated generation.
### Integrate user token with your application
Once you have generated the user token, you need to integrate it with your web or native application. This allows Claimr to recognize and associate the authenticated user with their activities.
1. **Pass the token**: Transmit the generated user token from your server to your web or application.
2. **Set the token value**: For SDK integration with Claimr, you have 2 options:
* Via the `data-user-token` attribute in the embed script.
* Using the SDK method with `window.claimr.set_user_token`.
For troubleshooting or support, reach our Claimr support team or email us at [support@claimr.io](mailto:support@claimr.io).
# Get Campaign Info
Source: https://docs.claimr.io/api-reference/campaign/get-campaign-info
/openapi.yaml get /campaign/info
Retrieves comprehensive campaign data including all tasks, quests, their properties, dependencies, and reward structures. Supports both published and development environments.
# Get Campaign Points
Source: https://docs.claimr.io/api-reference/campaign/get-campaign-points
/openapi.yaml get /campaign/points
Retrieves campaign statistics including total points earned, current season points, season index, and current season details. Calculates season progression based on configured season thresholds.
# Get Campaign Stats
Source: https://docs.claimr.io/api-reference/campaign/get-campaign-stats
/openapi.yaml get /campaign/stats
Retrieves detailed campaign statistics including total points awarded, user participation metrics, and complete stats object for analytics and reporting purposes.
# Get Custom Events
Source: https://docs.claimr.io/api-reference/events/get-custom-events
/openapi.yaml get /events
Get custom events associated with a user for tracking and triggering downstream processes. Events are stored with optional categorization and custom data payload. Results can be filtered by category and name.
# Push Custom Event
Source: https://docs.claimr.io/api-reference/events/push-custom-event
/openapi.yaml post /event
Creates a custom event record associated with a user for tracking, and triggering downstream processes. Events are stored with optional categorization and custom data payload.
# Get Invite Code Status
Source: https://docs.claimr.io/api-reference/invite-codes/get-invite-code-status
/openapi.yaml get /code
Retrieves information about an invite code including which users have used it.
# Release Invite Code
Source: https://docs.claimr.io/api-reference/invite-codes/release-invite-code
/openapi.yaml delete /code
Releases an invite code that was previously assigned to a user,
making it available for use again. The used_by parameter is optional
and can be used to specify which user to release the code from.
# Use Invite Code
Source: https://docs.claimr.io/api-reference/invite-codes/use-invite-code
/openapi.yaml post /code
Assigns an invite code to a user (identified by wallet address).
This endpoint handles user registration if the address is new,
creates campaign entries, and marks the invite code as used.
# Get Leaderboard
Source: https://docs.claimr.io/api-reference/leaderboard/get-leaderboard
/openapi.yaml get /leaderboard
Retrieves leaderboard data for a specific campaign. Supports both v1 and v2 leaderboard formats based on campaign type.
# Push Stream Value
Source: https://docs.claimr.io/api-reference/tasks/push-stream-value
/openapi.yaml post /stream/value
Pushes a value to all API stream tasks within a campaign that match the specified stream name. Automatically finds and triggers all quests/tasks configured for the given stream across all campaign schemes and groups.
# Set Task Value
Source: https://docs.claimr.io/api-reference/tasks/set-task-value
/openapi.yaml post /action/value
Records an task with a specific value for a user within a campaign quest. Validates user login, campaign bundle, and quest group before executing the task.
# Get User Token
Source: https://docs.claimr.io/api-reference/user-token/get-user-token
/openapi.yaml get /token
Creates or retrieves a user token for authentication. The user will be registered if they don't exist. Platform 'claimr' is not allowed.
# Award XP Reward
Source: https://docs.claimr.io/api-reference/user/award-xp-reward
/openapi.yaml post /user/reward
Creates an API-type reward for a user, adds the specified XP, and triggers XP processing.
If the user doesn't exist in the campaign and uses a valid web3 address, a new entry will be created.
Prevents duplicate rewards with the same ID.
# Get Referral Data
Source: https://docs.claimr.io/api-reference/user/get-referral-data
/openapi.yaml get /user/referrals
Returns the users a user has referred in a campaign, along with the referrer's own campaign statistics.
# Get Referral ID
Source: https://docs.claimr.io/api-reference/user/get-referral-id
/openapi.yaml get /user/ref_id
Gets or creates a referral ID for a user in a specific campaign. If the user doesn't have a campaign entry, one will be created. If no referral link exists, a new one will be generated.
# Get User Activity
Source: https://docs.claimr.io/api-reference/user/get-user-activity
/openapi.yaml get /user/activity
Returns everything a user has completed in a campaign: tasks, quests, and rewards, with a breakdown of the XP earned.
# Get User Profiles
Source: https://docs.claimr.io/api-reference/user/get-user-profiles
/openapi.yaml get /user/profiles
Returns a user's XP balance in a campaign together with every account linked to the user, each as an account and platform pair.
# Get User Progress
Source: https://docs.claimr.io/api-reference/user/get-user-progress
/openapi.yaml get /user/progress
Returns a user's progress across the whole campaign: every task and quest, with its completion status for this user.
# Get XP Balance
Source: https://docs.claimr.io/api-reference/user/get-xp-balance
/openapi.yaml get /user/balance
Returns a user's XP balance in a campaign, including XP earned from referrals and user-generated content, and the number of referrals.
# Set Referrer
Source: https://docs.claimr.io/api-reference/user/set-referrer
/openapi.yaml post /user/referrer
Creates a referral relationship between a referrer and a referral user in a specific campaign. Both users will be registered if they don't exist, and campaign entries will be created as needed. The referral user must not have an existing referrer or completed tasks.
# Set Referrer ID
Source: https://docs.claimr.io/api-reference/user/set-referrer-id
/openapi.yaml post /user/ref_id
Associates a user with a referrer in a specific campaign. Creates campaign entry if needed. Only works if the user has no existing referrer and no completed tasks. The referral link must exist and not be self-referential.
# Update User Profile
Source: https://docs.claimr.io/api-reference/user/update-user-profile
/openapi.yaml post /user
Updates user's name / alias / team. Creates campaign entry if needed.
# Withdraw User Points
Source: https://docs.claimr.io/api-reference/user/withdraw-user-points
/openapi.yaml post /user/withdraw
Creates a withdrawal record for a user's earned points in a specific campaign. Validates user existence, campaign bundle, and optionally checks balance before processing.
# Award Wallet XP
Source: https://docs.claimr.io/api-reference/wallets/award-wallet-xp
/openapi.yaml post /wallet/reward
Awards XP points to a wallet address for a campaign. This endpoint handles user registration
if the address is new, creates campaign entries, validates reward uniqueness, and processes
XP calculations. Also triggers webhook notifications for the reward event.
# Get Wallet Invite Code
Source: https://docs.claimr.io/api-reference/wallets/get-wallet-invite-code
/openapi.yaml get /wallet/code
Retrieves the invite code that was used by a wallet address for a specific campaign.
Returns an empty string if no invite code was used or if the wallet/campaign combination is not found.
# Get Wallet Referral ID
Source: https://docs.claimr.io/api-reference/wallets/get-wallet-referral-id
/openapi.yaml get /wallet/ref_id
Retrieves the referral ID associated with a wallet address for a given campaign.
Returns an error if the wallet is not found or has no referral ID for the specified campaign.
# Withdraw Wallet Points
Source: https://docs.claimr.io/api-reference/wallets/withdraw-wallet-points
/openapi.yaml post /wallet/withdraw
Withdraws XP points from a wallet address for a campaign. This endpoint handles user registration
if the address is new, creates campaign entries, validates withdrawal uniqueness, and optionally
verifies sufficient balance before withdrawal. Processes XP calculations after withdrawal.
# Remove Webhook
Source: https://docs.claimr.io/api-reference/webhooks/remove-webhook
/openapi.yaml delete /hook
Removes a webhook registered for a scope. Pass the same hook_id used when the webhook was set, or omit it to remove the default 'prod' hook.
# Set Webhook
Source: https://docs.claimr.io/api-reference/webhooks/set-webhook
/openapi.yaml post /hook
Registers a webhook URL that receives notifications for one scope: user_activity, user_reward, or referral. Pass a secret to have each notification signed, and a hook_id to keep more than one webhook per scope.
# Billing
Source: https://docs.claimr.io/billing
See the details of your active subscription, understand Claimr's credits-based pricing model, and review your history of past subscriptions.
The Billing section shows the details of your active subscription and a history of past subscriptions if available.
If you don't have any active subscription, you won't be able to create or run new campaigns. The page will display a message that a subscription is not available.
## Subscriptions
Claimr uses a credits-based subscription model:
* **Credits**: Your plan includes a set number of credits. Credits are used when your users complete tasks. If credits go beyond the included limit, additional charges apply.
### Credit-based subscriptions
* **Subscription Type**: Credits
* **Subscription Plan**: The selected plan.
* **Subscription Period**: The start and end date of the subscription.
* **Days Left**: The number of days until the subscription period ends.
* **Credits Limit**: The total number of credits available within the subscription.
* **Tasks Executed**: The total number of tasks your users completed during the subscription period.
* **Credits Used**: The number of credits already used.
* **Credits Over Plan**: The number of credits used beyond the subscription limit. These generate additional charges.
* **Price per Credit**: The cost of a single credit.
* **Additional Cost**: The cost of credits used beyond the subscription limit.
### Past subscriptions
The Billing section also contains a history of past subscriptions, including subscription type, plan, period, and usage.
### Renewal
Your subscription automatically renews for the same term as the current period. To prevent renewal, you need to inform our team and cancel at least 5 days before the subscription expires.
# Campaign sign-in options
Source: https://docs.claimr.io/campaigns/campaign-sign-in-options
Configure login requirements, wallet behavior, sign-in services, and supported chains for your campaign.
To ensure the Claimr widget works correctly with your dApp, make sure to configure the campaign settings accordingly.
To access these settings:
1. Log in to your Claimr account.
2. Select the **Campaign** you want to apply settings to.
3. Navigate to the campaign's **Settings** section.
4. Select **Sign-in options** from the settings menu.
### Require login to start a task
Ensure 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
If enabled, this would require a specific token to access the campaign.
### Wallet change is disabled
Prevent users from switching wallets mid-session.
### Disable users merge
Disables automatic merging of user identities across sign-in methods.
### Select sign-in services
Choose the platforms users can log in with (e.g., Twitter, Telegram, Discord). You can enable one or multiple options.
### Chains
Select the blockchain networks supported by your campaign (e.g., Ethereum). These define where wallet-based actions will be validated.
### Wallet message field
Enter a custom message that will be shown to users during wallet signature to identify the purpose of signing.
# Create new campaign
Source: https://docs.claimr.io/campaigns/create-new-campaign
Launch your first campaign in minutes and start engaging your community with rewards, quests, and gamified experiences.
## Before you start
Make sure you have:
* A Claimr account with access to the admin panel
* An organization set up (or create one during this process)
* A clear idea of what you want your campaign to achieve
## Create your campaign
Open your web browser and navigate to the login page: [panel.claimr.io](https://panel.claimr.io/). Enter your email and password to sign in.
Choose the organization for which you'd like to create a campaign. Click on the organization's tile and you'll be taken to its page.
Click **Create new campaign**. You'll be guided through the new campaign creation flow.
Configure the fundamental settings for your campaign:
* Choose a clear and recognizable name.
* Customize how points are referred to (e.g., "Points", "XP", "Tickets").
* Select the platforms your users will use to join the campaign (e.g., Twitter, Telegram, Discord).
Click **Continue** when you're ready.
* **Empty** - Start with a blank canvas. You'll set everything up manually. Best for experienced users or unique campaign structures.
* **X Basic** - Pre-configured Twitter/X tasks including follow, like, and retweet tasks. Launch a social campaign in minutes.
* **Discord Basic** - Discord-focused task templates with join server and verify role tasks. Perfect for community-building.
* **Telegram Basic** - Telegram task templates with channel join and bot interaction tasks. Great for Web3 projects.
* **Referral Basic** - Referral program template with multi-level tracking pre-configured. Start your viral loop immediately.
Click your preferred template to select it, then click **Continue**.
Select the visual theme for your campaign widget - this is your final customization before creating the campaign.
* **Claimr theme** (Default) - The standard Claimr branded design. Professional and polished, works great for most campaigns.
* **Mini theme** - Compact, space-efficient layout. Perfect for mobile-first campaigns with a clean and minimalist look.
* **Flat app** - Modern, flat design aesthetic with a streamlined appearance. Great for sleek, contemporary brands.
Click your preferred style, then click **Create campaign** to finalize.
Congratulations! You've successfully created your first Claimr campaign. It's now visible on your organization's dashboard.
After creating your campaign, you'll be redirected to the **Quest group settings** page. From there, you can begin setting up your campaign in detail.
## What to do next
Now that your campaign exists, configure it to match your goals:
1. [Set up general settings](/campaigns/general-campaign-settings): configure your campaign's core parameters.
2. [Create quests](/quests/overview): build the user journey.
3. [Add tasks](/tasks/overview): define the actions users complete.
4. [Configure rewards](/rewards/overview): set up your reward system.
5. [Customize your widget](/widget/widget-configurations): brand your campaign experience.
Start with general settings to establish your campaign's foundation, then move to quests and tasks to build the user experience.
## Common questions
**Can I change my campaign style after creation?**
Yes, you can update your widget style in the Widget settings at any time.
**What if I'm not sure which template to choose?**
Start with "Empty" for full control, or choose a platform-specific template if you're focusing on one channel. You can always add or remove tasks later.
**Can I add more login platforms after creating the campaign?**
Yes, you can modify login platforms in your General Settings.
# General campaign settings
Source: https://docs.claimr.io/campaigns/general-campaign-settings
Configure campaign identity, points, time limits, campaign flow, languages, integrations, block options, notifications, and the Public API.
To access these settings:
1. Log in to your Claimr account.
2. Select the **Campaign** you want to apply settings to.
3. Navigate to the campaign's **Settings** section.
4. Select **General settings** from the settings menu.
## General settings
This section is where you'll set the basic parameters for your campaign.
Choose a name, logo, and icons that resonate with your target audience and align with your campaign's theme. This will help create a cohesive and engaging experience for your users.
### Campaign ID
A unique, auto-generated identifier for internal reference. You won't need to change or use this unless working with the API or internal tools.
### Campaign name
This is the name users will see. It should clearly reflect the theme or goal of your campaign. Keep it short, engaging, and specific. Just type it into the field.
### Campaign logo
Your campaign's visual brand. This image appears prominently throughout the widget and admin panel. Click **Edit** to upload or update the logo.
### Description
A clear and appealing description helps users understand the campaign's value. Explain the goals, rewards, and what users should do next. You can use the rich-text editor to apply styles, add links, and insert images. Keep it concise but inspiring - this is the first impression your campaign makes.
### Campaign description tags
Tags allow dynamic personalization of your description. When inserted, they're automatically replaced with data relevant to each user, making the experience feel more custom and engaging.
To see all available tags, visit the [Descriptions: creation, usage, tags](/descriptions-creation-usage-tags) article.
Make sure all tags are correctly formatted so they are recognized and processed by Claimr.
### Animation type
Choose how your description appears in the widget. You can apply visual effects such as typing animation to add a bit of flair and draw attention. Just select an option from the dropdown.
### Collapse description
This toggle helps control visual clutter. When turned on, the description is shown in a compact view with a "Show more" link. When off, the full description is visible by default. Use this to keep your widget clean while still offering full campaign details.
### Policies
This field allows you to add a link to your company's own Terms, Privacy Policy, or any other external documentation. When provided, Claimr's widget displays both the default Claimr Terms and the custom policy link. This is useful for meeting internal compliance or offering campaign-specific terms to users.
## Points
This section is where you configure the reward system of your campaign. You can edit the default point type (e.g., XP) and create additional point types.
### Campaign points name
This is the name of the reward system you're using. It could be "Points," "XP," "Tokens," or anything else. Choose a term that fits your community's voice. This label appears across all user-facing components.
### Campaign points format
Define how points are displayed (e.g., 10,000). Use a format that matches your campaign's design and readability needs.
### Process points based on past events toggle
When enabled, this toggle automatically recalculates users' point totals if you change the point value of a task after it's already been completed. This is helpful when correcting task values or adjusting campaign dynamics.
For example, if a task was worth 100 points and you later reduce it to 50, Claimr will recalculate and apply the new value retroactively.
### Points icon
An image that represents the reward system. Use something simple and memorable. Click **Edit** to upload or replace the icon.
### Additional points
You can create new point types alongside the default one. Click **Add Point** to add a new block with the following fields:
* **Point ID** - must be entered manually and uniquely identifies the point. This ID can be used for description tags. This tag will display the total balance of that specific point for the user. To find out more about tags, visit [Descriptions: creation, usage, tags](/descriptions-creation-usage-tags).
* **Name** - the display name of the new point.
* **Image** - upload an icon for the new point.
You can add as many additional points as needed.
### Completion logic
After you create new points, they become available in all relevant reward and reporting sections:
* **Quests**: in the *Completion* reward field, you can assign values for each configured point type.
* **Tasks**: in the *Completion* reward field, you can assign values for each configured point type.
* **Activity**: the activity table displays totals for all point types in separate columns (*Total: Point 1, Total: Point 2*, etc.).
* **Export**: exports include the new columns for each configured point type.
* **Tournaments**: when configuring a tournament, you can select which point type is used to build the leaderboard.
## Constraints
### Campaign is locked
Use this toggle to prevent users from participating in the campaign, even if it's visible. This is helpful when preparing or finalizing content before launch.
### Limit campaign time
Set a campaign start and end time to control when participation opens and closes.
Enable the toggle for "Limit campaign time" and set specific start and end dates. The time format is 24-hour (e.g., 14:00), and all settings follow your local time zone.
Set clear time limits to create a sense of urgency for your audience and drive more engagement.
## Campaign flow
This section is where you design the path your users take through your campaign. Use the flow to guide your users through a well-structured experience, encouraging them to complete quests and earn rewards along the way.
* **Set initial points**: The number of points each user receives immediately upon joining the campaign, before completing any tasks. This is useful for campaigns restarting in a new season or continuing from a previous phase - allowing you to preload users with some progress. For example, setting this to 50 means every participant will automatically get 50 points added to their balance at the start.
* **Assign an Intro quest**: the first quest a user sees when joining.
* **Select Highlighted quests**: quests you want to showcase, such as special challenges or limited-time rewards.
* **Choose an Intro pop-up**: Optional messages or a complete onboarding flow to greet new users. Learn more in the [Intro pop-up](/pop-ups/into-pop-up) article.
The order of your quests in the campaign flow impacts the user experience. Arrange your quests in a logical progression, starting with the easiest or most enticing and gradually increasing in difficulty or complexity.
## Languages
Add languages to localize your campaign. The primary language is shown by default, and you can add others to reach more users.
## Integrations
Input a Telegram bot ID to link your campaign with a Telegram bot. This is optional and used in campaigns that feature [Telegram-based tasks](/tasks/telegram-tasks).
Make sure your bot is set up correctly in Telegram before linking it here to avoid errors during campaign participation.
## Block options
Protect your campaign by managing access with advanced restrictions. This section lets you block disqualified users, specific IP addresses, and traffic from selected countries.
### Block disqualified users
When enabled, this prevents users marked as disqualified (via referral settings or quest conditions) from accessing your campaign.
### IP block list
Enter one or more IP addresses to block access from known malicious sources or bot farms.
### Country limitations
Choose whether to block or allow access based on a user's country. Select specific countries to block or to allow exclusive access for targeted regions.
Combine IP and country restrictions to safeguard your campaign from fraud and unwanted traffic while maintaining access for real users.
## Widget notifications
Customize the system messages your users see during interactions with the campaign widget.
| Notification | When it's shown |
| - | - |
| **Delay (seconds)** | How long a notification should stay visible. |
| **Task complete** | Shown when a task is successfully finished. |
| **Task updated** | Appears when task progress or status is refreshed. |
| **Task pending** | Lets users know when a task is processing or being reviewed. |
| **Task failed** | Displayed when the user's attempt fails. You can encourage retries here. |
| **Reward earned** | Shown when the user earns points. You can use variables like `{reward}` to reflect the exact amount. |
| **Failed login / verification** | Used to prompt users to try logging in or verifying again if it didn't go through. |
| **Text copied** | Confirmation that the copied action (like wallet or code) was successful. |
Make your notifications friendly and on-brand to keep the user experience consistent and delightful.
## Public API
Once you've updated your campaign settings, a Public API section will appear at the heading of the page. This section allows you to generate a token that can be used to integrate your campaign with external systems.
To create the token, click **Generate token**. Once generated, the token will be displayed in a masked format for security reasons. You can click the eye icon to reveal it.
By clicking **Revoke token** you immediately disable access for any system using it.
# Leaderboard
Source: https://docs.claimr.io/campaigns/leaderboard
Set up a public leaderboard to showcase top-performing participants and boost engagement with a competitive element.
This section lets you set up a public leaderboard to showcase top-performing participants in your campaign. It helps boost engagement by adding a competitive element.
To access these settings:
1. Log in to your Claimr account.
2. Select the **Campaign** you want to apply settings to.
3. Navigate to the campaign's **Settings** section.
4. Select **Leaderboard** from the settings menu.
To customize its settings, click the edit (pencil) icon in the corner. This will open a settings window.
### Max. entries
Define the maximum number of users to be displayed on the leaderboard. For example, setting this to 100 will show the top 100 participants.
### Page size
Set how many users are shown per page. This controls pagination and helps manage large leaderboards by breaking them into smaller chunks.
### Task dependencies
Select which tasks contribute to the leaderboard score. Only points earned from the selected tasks will be counted. This allows you to filter out low-effort or irrelevant tasks and focus the leaderboard on meaningful contributions.
# Campaigns
Source: https://docs.claimr.io/campaigns/overview
See what you can do with Claimr campaigns and find your way into general settings, referrals, leaderboards, sign-in options, and test users.
Campaigns are the foundation of your engagement strategy in Claimr. Use them to build interactive experiences that captivate your audience and drive the actions that matter to your business.
A campaign is your structured container for growth. It holds quests, tasks, and rewards - all working together to achieve your specific goals.
## What you can do with Claimr campaigns
**Integrate across channels**: Connect your campaigns with email, social media, your website, and more. Create a seamless experience that reaches users wherever they are.
**Test and optimize**: Experiment with different messaging, rewards, or designs. Discover which strategies drive the best performance and double down on what works.
**Set clear goals and track results**: Define what success looks like for each campaign and measure your progress. Use real data to understand what's working and optimize your strategy.
**Target the right users**: Create tailored experiences for specific audience segments. Personalize campaigns based on user behavior, demographics, or engagement level to maximize relevance and results.
**Stay secure and reliable**: Run campaigns with confidence on Claimr's secure platform. Your data stays protected while your campaigns run smoothly.
Launch your first campaign in minutes.
Configure the core parameters of your campaign.
Define the conditions under which referrals are counted.
Showcase top-performing participants.
Control how participants authenticate into your campaign.
Preview your campaign safely before it goes live.
# Referral settings
Source: https://docs.claimr.io/campaigns/referral-settings
Set a minimum point threshold and task-based requirements to validate referrals in your campaign.
Use this section to define the conditions under which referrals are counted in your campaign. It allows you to set both a minimum point threshold and task-based requirements to validate a referral.
To access these settings:
1. Log in to your Claimr account.
2. Select the **Campaign** you want to apply settings to.
3. Navigate to the campaign's **Settings** section.
4. Select **Referral** from the settings menu.
To customize its settings, click the edit (pencil) icon in the corner. This will open a settings window.
## Min points
This is the minimum number of points a referred user must earn in order for the referral to count.
For example, if you set it to 100, the invited user needs to complete tasks worth at least 100 points before the referrer gets credit.
## Task dependencies
Here you can specify which tasks a referred user must complete for their referral to be valid.
Select one or more tasks from a list of those already used in the campaign. This helps ensure that referrals are based on meaningful engagement, like completing a UGC task or linking a social account.
If both conditions are set, the referral will be counted only when the referred user meets the point threshold and completes at least one of the selected tasks.
To explore more about how the referral system works, see [Referral tasks](/tasks/common-tasks/referral-tasks) and [Referral analytics](/data-analytics/referrals).
# Test users
Source: https://docs.claimr.io/campaigns/test-users
Grant specific users test access to a campaign so your team can safely preview quests, tasks, and rewards without affecting live data.
Test users in Claimr are specific user accounts that you designate within a campaign, granting them special access or permissions primarily for testing purposes. This feature allows you to add team members or real users to interact with your campaign in a controlled environment, often before it's launched to the public or while testing new configurations.
## Why use test users?
Adding specific users as testers before or during a campaign is crucial for ensuring a smooth experience. Use the Test Users feature to:
* Thoroughly test your campaign's quests, tasks, rewards, and overall user flow.
* Identify potential bugs, errors, or usability issues with feedback from a select group.
* Allow team members or real test users to preview and experience the campaign without affecting live user data or analytics.
* Safely test specific conditions, edge cases, or integrations.
* Gather valuable feedback on the campaign experience from a trusted group before a wider release.
## Access the Test users section
1. Log in to your Claimr account.
2. Select the **Campaign** you want to add test users to.
3. Navigate to the campaign's **Settings** section.
4. Select **Test Users** from the settings menu or sidebar.
## Add a test user
Adding a user to the test group involves two main parts: the user getting their unique ID, and the campaign manager adding that ID in the settings.
The person you want to add as a tester must first retrieve their unique Claimr User ID for that specific campaign. Provide them with these instructions:
1. Open the specific campaign you need to test.
2. Once the widget is loaded, click repeatedly (several times) anywhere on the screen or widget area.
3. A pop-up message should appear confirming: "User ID successfully copied". This copies their unique ID for that campaign to their clipboard.
4. Send this copied User ID to the campaign manager.
Once you (the campaign manager) have received the User ID from the tester:
1. Navigate to the **Test users** dashboard for the relevant campaign (go to campaign **Settings → Test Users**). You will see a list of any users already added as testers.
2. Click the **Invite** button.
3. The **Invite test user** modal window will appear.
4. Paste the User ID provided by the tester into the **User ID** field.
5. Click the green **Invite** button in the modal window.
## Invitation status and the user's confirmation
### Manager's view: invitation sent
Once you click **Invite**, you will see:
* A new entry for the invited user appears in the **Test Users** table on your dashboard.
* This entry will show the user's **ID**, **Name** (if available), and initially, the **Status** will be set to `created`.
**Understanding statuses**: there are three possible statuses for a test user invitation:
* `created`: The invitation has been sent, awaiting the user's response.
* `confirmed`: The user has accepted the invitation via the widget.
* `rejected`: The user has declined the invitation via the widget.
### User's view: accept the invitation
After the manager sends the invite, the invited user needs to confirm.
The next time the invited user opens the specific campaign widget, a pop-up notification will appear asking them to join the test group. This pop-up will have two buttons: **Reject** and **Confirm**.
* **If the user clicks `Confirm`**: They are officially added as a test user for this campaign and can participate according to any special rules or access you have configured for testers. Their status in your Test Users list will update to `confirmed`.
* **If the user clicks `Reject`**: They decline the invitation, their status in your Test Users list will change to `rejected`, and they will *not* become a test user. The invitation process would need to be restarted if they change their mind.
## Test users' table
Once a user clicks **Confirm** in the widget pop-up, their **Status** in your Test Users dashboard updates to `confirmed`. They are now officially a test user for this campaign, and you can see their complete record in the table.
Table columns meaning:
* **ID**: The test user's unique Claimr identifier (the same ID they copied from the widget). You can click an icon next to it to copy the ID again.
* **Name**: The user's display name, typically taken from their primary connected account or first login method used with Claimr.
* **Participates**: A **+** (plus) sign indicates the user is actively participating as a test user in the specific campaign you are currently viewing. A **-** (minus) sign would mean they might be a test user in other campaigns within your organization but not this one. This helps manage testers across multiple campaigns.
* **Status**: The current state of their test user invitation: `confirmed`, `created`, or `rejected`.
* **Campaigns**: Lists the names of all campaigns within the organization that this user is participating in (as a test user).
* **Logins**: Shows the different accounts or login methods the user has connected to their Claimr profile (e.g., Discord username, X handle, wallet address).
## Test user's details
To see more detailed information about a specific test user:
1. Click on the row corresponding to that user in the **Test Users** table.
2. A detailed information drawer will slide out from the right side of the screen.
### General section
Displays the fundamental information about the test user.
* **ID**: The user's unique Claimr identifier.
* **Name**: The name associated with the user account (often from their first login).
* **Status**: The current invitation status (`confirmed`, `created`, or `rejected`).
* **Current campaign user info button**: If the test user *is* actively participating in the campaign you are currently viewing (indicated by a `+` in the **Participates** column of the main table), this green button will be visible. Clicking it opens another dashboard showing details about this user's specific activity, points, and status *within this particular campaign*. This button will *not* be displayed if the user is not currently a participant in the campaign you are viewing.
### Logins section
Lists all the external accounts and login methods the user has connected to their Claimr profile.
* **Account**: The username, email, or address associated with the login.
* **Platform**: The type of login (e.g., `discord`, `email`, `web3`, `x`).
The **Delete** button allows you to remove linked accounts, but note that a user must always have at least one login method remaining connected to their profile. Consequently, the **Delete** button will not be displayed next to the last remaining account.
### Entries section
Shows a list of all campaigns within your organization that this user is participating in (as a test user or regular user).
* **User ID**: The user's ID within that specific campaign context.
* **Campaign**: The name of the campaign.
Clicking on a campaign name in this list opens that specific campaign's dashboard or settings in a new browser tab. This can be useful if a test user is part of multiple campaigns and you need to navigate between them.
### Deleting a test user
Removing individual logins (as described in the Logins section) is different from removing the user entirely from the test group. If you need to completely remove a test user:
1. Scroll to the very bottom of this drawer till you find a red **Delete from test users** button.
2. Click this red button to remove the user from the test group for this campaign. You will be asked to confirm this action.
If you remove a test user and later decide to add them again, you must repeat the full invitation process from the beginning: the user needs to provide their current User ID, you need to invite them again, and the user must confirm the new invitation.
# Claimr core components
Source: https://docs.claimr.io/claimr-core-components
Create engaging, gamified experiences that captivate your users and drive desired actions with Claimr.
## How Claimr works
Claimr campaigns are built with a clear and intuitive structure, guiding your users through a rewarding journey.
1. [**User progress**](/ux-requirements/user-progress-ux-requirements): This component displays the user's progress within the campaign, including earned points and a progress bar. This motivates users and provides a sense of accomplishment.
2. [**Quests**](/quests/overview): Quests are sets of tasks that users undertake to achieve specific objectives. They can be designed to guide users through a specific learning path, encourage them to explore different features of your product, or simply provide a fun and engaging way to interact with your brand.
* Intro Quests: These are designed to onboard new users and familiarize them with your campaign mechanics.
* Highlighted Quests: These are featured prominently to capture users' attention and encourage immediate participation.
3. [**Campaign**](/campaigns/overview): This is the foundation of your engagement strategy. It acts as a container for all the activities and challenges you create within Claimr.
4. [**Challenges**](/extra/challenges): These are standalone challenges that run alongside your main campaign, providing additional opportunities for engagement and rewards. They can be structured as seasons, eras, or any other format that aligns with your campaign theme.
5. [**Groups**](/ux-requirements/group-ux-requirements): Groups organize related quests into logical clusters, providing structure and context for users. This helps users navigate your campaign and understand the relationships between different quests. All groups include [Tasks](/tasks/overview).
Tasks are the individual actions that users complete within a quest. Claimr offers a huge variety of task types, giving you the flexibility to create truly unique and engaging experiences. Here are just a few examples:
* [**Social media tasks**](/tasks/telegram-tasks): Have users follow you on Twitter, retweet a post, or join your Telegram group.
* [**Content interaction tasks**](/tasks/youtube-tasks): Encourage users to read articles, watch videos, or engage with specific content on your platform.
* [**Referral tasks**](/tasks/common-tasks/referral-tasks): Motivate users to invite their friends to join your campaign.
* [**Web3 tasks**](/tasks/web3-tasks/overview): Connect with blockchain technology by having users connect their wallets, mint NFTs, or interact with smart contracts.
* **Educational tasks**: Create quizzes or surveys to test users' knowledge and reinforce key concepts.
* **Custom tasks**: Use webhooks and API integrations to create custom tasks tailored to your specific needs.
6. **Leaderboard**: A leaderboard showcases user rankings and fosters friendly competition, encouraging users to strive for the top spot.
## Benefits for your users
**Exciting challenges**: Make even mundane tasks fun and engaging with a gamified approach.
**Clear goals and progress tracking**: Clearly displays the user's progress within the campaign or a specific quest, providing a visual representation of their achievements and motivating them to continue their journey.
**Sense of accomplishment**: Reward users with points, badges, and other incentives as they complete tasks and quests.
**Thriving community**: Foster friendly competition and encourage interaction through leaderboards and challenges.
**Sense of urgency**: Use time-limited quests and challenges to motivate users to take action.
**Variety and engagement**: Keep users engaged with different types of quests and tasks, like inviting friends, finding secret codes in videos or posts, and sharing links.
## Benefits for your business
**Increase user engagement**: Drive higher levels of user participation and interaction.
**Improve user retention**: Keep users coming back for more with rewarding experiences.
**Enhance brand loyalty**: Create positive associations with your brand through gamification.
**Gain valuable insights**: Track user behavior and campaign performance to optimize your strategies.
With its flexible and customizable features, Claimr can be adapted to a wide range of use cases, from onboarding new users to driving product adoption and building thriving online communities.
# Gift codes
Source: https://docs.claimr.io/codes/gift-codes
Create and manage gift code lists, then distribute them as rewards for completing tasks, quests, or campaigns.
## Benefits of using gift codes
Import and manage your own gift codes to distribute to users as rewards for completing tasks, quests, or participating in your campaigns.
* **Unique codes**: Each gift code should be unique and can only be used once.
* **Security**: Ensure that your gift codes are securely stored and managed to prevent unauthorized access or misuse.
* **Tracking**: Claimr tracks which user received each gift code, allowing you to monitor distribution and usage.
## Creating a gift code list
Navigate to the **Events** section in the Claimr admin panel and select the **Gift Codes** tab.
Click **Create** to set a new list of gift codes.
* **Gift codes type**: Provide a descriptive name or category for the type of gift codes you're adding (e.g., "10% Discount," "Free Trial").
* **Codes**: Enter the gift codes you want to include in the list. You can manually enter each code or import them from a CSV or TXT file.
Click the **Create** button to save the new gift code list.
### Managing gift codes
Claimr provides a table in the Gift Codes section to manage your gift code lists. This table includes information such as:
* **Code**: The actual gift code.
* **Type**: The type or category of the gift code.
* **Date**: The date and time the gift code was added.
* **Owner**: The user who owns or is associated with the gift code.
You can use the buttons above the table to:
* **Export .csv file**: Export the list of gift codes as a CSV file.
* **Delete**: Delete selected gift code lists.
## Distributing gift codes
To distribute gift codes to users, you need to configure them as rewards within your Claimr campaign.
Go to the **Rewards** section in your campaign settings.
Click the **Create Reward** button.
Choose **Gift Code** as the reward type.
Select the specific gift code list you want to use for this reward.
Set the reward name, quantity, and any other relevant settings.
Click the **Create** button to save the new reward.
Now, when users earn this reward, they will receive a gift code from your list.
# Claim invite code task
Source: https://docs.claimr.io/codes/invite-codes/claim-invite-code-task
Configure a Claim invite code task, set how many codes a user can claim, and preview how it appears before and after completion.
Follow the [Task settings](/tasks/task-settings) steps to set up the general settings for your task. The article includes defining the task name, description, rewards, and other stages.
During the task type stage, select **Common** from the available options and choose **Claim invite code** as the task action from the list.
In the task settings section, specify the maximum number of invite codes a single user can claim for this task. You can increase it up to 25 if you want to allow users to claim multiple invite codes.
Fill out the remaining task settings according to your preferences and click **Save changes** to confirm your task configuration.
Click **Preview** to see how your task will look to users on desktop, tablet, and mobile devices.
# Enter invite code task
Source: https://docs.claimr.io/codes/invite-codes/enter-invite-code-task
Configure an Enter invite code task, select the required login platform, and preview how it appears to users.
Follow the [Task settings](/tasks/task-settings) steps to set up the general settings for your task. The article includes defining the task name, description, rewards, and other stages.
During the task type stage, select **Common** from the available options and choose **Enter invite code** as the task action from the list.
In the task settings section, choose the platform where the invite code will be used from the dropdown menu under **Required logins**.
Fill out the remaining task settings according to your preferences and click **Save changes** to confirm your task configuration.
Click **Preview** to see how your task will look to users on desktop, tablet, and mobile devices.
# Invite codes
Source: https://docs.claimr.io/codes/invite-codes/overview
Create, share, and manage invite codes, then attach them to Enter invite code and Claim invite code tasks.
## Create invite codes
From your Claimr main panel, click **Campaigns** on the header menu and select the desired campaign.
In the campaign header menu, click on the **Events** tab.
Select **Invite Code** as the event type to open the invite codes tab.
Click the **Create** button in the upper left corner. A new tab will open for creating invite codes.
* **Number of codes**: Enter the desired number of invite codes you want to generate.
* **Code holder name**: Specify a name for the person or group that will be receiving and distributing the codes.
Click the **Create** button to generate the invite codes. A table with the generated codes will appear.
## Share invite codes
Each invite code is unique and can only be used once. They are designed to prevent unauthorized use, ensuring you can accurately track who is joining your campaign through each code.
Select, copy, or export invite codes (.csv) using the buttons above the table. Share your codes through social media, email, your website, or direct distribution.
Filter codes by status (active or already used), date, code holder name, or the name of a participant who used them.
Next, select the specific task where you want users to use these invite codes.
Let users unlock a task by entering an invite code they've received.
Let users claim one or more invite codes directly from a task.
# Codes
Source: https://docs.claimr.io/codes/overview
See how invite codes, secret codes, and gift codes each drive reach, engagement, and tracking in your Claimr campaigns.
Claimr offers **three code types** - **invite, secret, and gift** - designed to supercharge your campaigns and deliver measurable results.
**Benefits of using codes:**
* **Grow your reach**: Extend your campaign's reach beyond your immediate audience as users share codes within their networks, organically expanding your reach through word-of-mouth marketing.
* **Track your success**: Gain valuable insights into your campaign's performance by assigning unique codes to different channels or promotions. Track the source of new participants and measure the effectiveness of your marketing efforts.
* **Boost engagement**: Create a sense of exclusivity and reward that motivates users to actively participate in your campaign and share it with others, fostering a vibrant and engaged community.
* **Targeted incentives**: Tailor rewards and incentives to specific user segments or actions, nurturing loyalty and encouraging continued participation.
Hide codes in your content and reward users who find them.
Generate and distribute codes that control access to your campaign.
Deliver tangible, redeemable rewards to your participants.
# Secret code tasks
Source: https://docs.claimr.io/codes/secret-codes
Configure a secret code task, embed codes in your content, and see how the code entry field appears to users.
## What are secret code tasks?
Secret Code tasks require users to enter a predefined code in order to complete the task and receive a reward. You decide where and how the code is shared. For example: in your content, on social media, during events, or as part of a hidden clue. Users must enter the exact code you've configured in the task settings.
**Use secret code tasks to:**
* Hide a code inside campaign content or announcements
* Encourage exploration, scanning, or event participation
* Gate a reward behind a known keyword or phrase
## Configure a secret code task
To configure a secret code task in Claimr:
1. Go to your campaign and click **Create task**.
2. Under the Category section, select **Common**.
3. Choose the **Secret code** task type.
4. Click **Continue** to proceed to task settings.
### Task settings
After selecting the task type, move to the next page and configure the following fields:
* **Completion points**: The number of points awarded when the user completes the task.
* **Points Multiplier (%)**: Add a percentage-based bonus to the total reward. For example, a 5% multiplier increases the final reward by 5%.
* **Recurrence**: Control how often users can complete the task:
* Once - can only be completed one time per user.
* Daily - available once every 24 hours.
* Weekly - available once every 7 days.
* Multiple - the task stays open and can be completed as many times as needed, one after another, without any waiting time.
* **Message**: Optional. Add a short instruction that will appear above the input field. Use this to guide users on where or how to find the code.
* **Secret Code**: Enter the exact code that users must submit in order to complete the task. This value is case-sensitive and must match exactly.
Once you're done, click **Create task** to save and add it to your quest right away. You'll now see the task listed in your quest. From there, you can reorder it, delete it, or edit it anytime.
Or click **Advanced settings** to continue configuring more options specific to the selected task type.
## How secret code tasks appear to users
When users encounter a Secret Code task, they see the following elements:
* The instruction text you set in the Message field
* An input field where they can enter the code
* A button to submit their entry
If the user enters the correct code, the task is completed and the reward is granted. If the entry doesn't match the configured code, the task cannot be completed.
If recurrence = multiple, users can return and enter a valid code again - with no delay between completions.
# Activity
Source: https://docs.claimr.io/data-analytics/activity
See a detailed overview of all user actions within your campaign, export activity data, and explore the full Activity table columns.
## What is the Activity section?
The Activity section provides a detailed overview of all user actions and interactions within your campaign, giving you valuable insights to optimize your strategy.
Use this data to:
* **Track user engagement:** Monitor how users are interacting with your campaign and identify which tasks or quests are most popular.
* **Identify trends:** Spot trends in user activity over time to understand how your campaign is performing and make adjustments as needed.
* **Measure the effectiveness of campaign elements:** See which tasks, rewards, or other elements are driving the most engagement and conversions.
* **Troubleshoot issues:** Identify any issues or bottlenecks in your campaign that might be hindering user progress or engagement.
## Accessing the Activity section
1. Log in to your Claimr account.
2. Select the campaign you want to analyze.
3. Click on the **Analytics** tab in the campaign's header menu.
4. Select **Activity** from the dropdown menu.
## Activity dashboard
The Activity dashboard provides a comprehensive overview of user actions and interactions within your campaign.
### Visual data representations
**Line charts** visualize trends and patterns in user activity over time, with separate charts for 3 days, 7 days, and 30 days. You can see data for new users and new tasks completed.
Each chart displays the total number of actions and the percentage change compared to the previous period.
### Exporting and searching data
**Export options:** Above the data visuals, you'll find options to export the activity data as a CSV file, to Google Sheets, or to export leaderboard data.
**Advanced search:** You can also use the Advanced Search feature to filter activity data by account and platform. The Advanced Search modal allows you to search for specific accounts, select platforms (e.g., X, Discord, Telegram), and apply other filters to refine your search.
## Activity table
The Activity table displays a wealth of information about each activity, allowing you to analyze user behavior and track campaign progress in detail.
### Table columns
**General columns** represent core information displayed by default.
* **User ID:** The unique identifier for each user.
* **Name:** The user's display name or username.
* **Status:** Indicates whether the user is active or disqualified in the campaign.
* **IP:** The user's IP address.
* **IP Score:** A score assigned to the user's IP address based on various factors, such as location, reputation, and activity history. This score can be used to assess the risk associated with the user or to identify potentially fraudulent activity.
* **Team:** If the user belongs to a team within the campaign, the team name is displayed here.
* **Date:** The date and time when the activity occurred.
* **Country:** The user's country of origin.
* **Activity:** The specific action performed by the user (e.g., completed a task, claimed a reward, logged in).
* **Status:** The status of the activity (e.g., completed, pending, failed).
* **Points:** The number of points earned by the user for the *specific activity*.
* **Multiplier:** Any multiplier applied to the Points earned for the *specific activity*.
* **Total Multiplier:** The total multiplier applied to the Points, including any referral bonuses for the *specific activity*.
* **Referral Points:** The number of points earned through referrals for the *specific activity*.
* **Total Points:** The user's total accumulated Points in the campaign.
**Custom columns** are specific to your campaign configurations.
* **Source:** The origin of the user's traffic to the campaign. This could be a website, social media platform, specific email campaign, or any other trackable source.
* **Campaign:** The specific campaign name that the activity is associated with. This is useful if you are running multiple campaigns within Claimr simultaneously.
* **Medium:** The marketing medium used to acquire the user (e.g., "email" for an email campaign, "social" for social media, "referral" for a referral program). This helps categorize the traffic source.
* **Term:** Typically used with advertising (like Google Ads) to identify the specific keyword that triggered the user's visit.
* **Content:** Used to differentiate between different versions of an ad or link within the same campaign. For example, you might use this to distinguish between two different banner ads you're testing.
* **Last Activity:** The date and time of the user's most recent activity within the Claimr platform.
### Table actions
**Selection:** Select and unselect individual or multiple rows in the table.
**Expand/Collapse:** Expand or collapse rows to view more or less detail about each activity.
**User Actions:**
* **Disqualify** a user from the campaign.
* **Qualify** a user for the campaign.
* **Delete** a user from the campaign.
**Search:** You can search the table for specific activities or users.
**Custom columns:** Customize the columns displayed in the table using the column settings menu. The available columns are: Source, Campaign, Medium, Term, Content, and Last Activity. They match the UTM source.
# Failed actions
Source: https://docs.claimr.io/data-analytics/failed-actions
See a log-by-task and log-by-user breakdown of actions users attempted that resulted in failure, to improve task clarity and user flow.
## What are Failed Actions analytics?
Failed Actions analytics provides a detailed overview of actions users attempted that resulted in failure. This helps identify common issues and potential areas for improvement in the user experience when completing tasks within Claimr.
## Use this data to
* **Identify frequent failure points:** Spot specific actions or tasks that consistently cause issues.
* **Assess impact:** Understand the proportion of users affected by task failures.
* **Improve task clarity and execution:** Address problems to minimize user frustration and ensure successful task completion.
* **Optimize user flow:** Make changes to tasks, improving the users' experience in completing the tasks.
## Accessing Failed Actions analytics
1. Log in to your Claimr account.
2. Select the relevant campaign.
3. Click on the **Analytics** tab.
4. Select **Failed Actions** from the submenu.
Once you select "Failed Actions", the dashboard will open, displaying two tables. These tables provide a comprehensive view of failed user actions, offering both aggregated and individual-level data.
## Failed Actions log by task
This table offers you detailed insights into specific task failures.
* **Task:** The specific task that users attempted to complete.
* **Type:** The type of action users performed when attempting the task (e.g., "Follow on X").
* **Platform:** The platform where the action was attempted.
* **Total attempts:** The total number of times users attempted to perform this task.
* **Unique users:** The number of unique users who tried to complete the task, regardless of success or failure.
* **Users completed:** The number of unique users who successfully completed the task.
* **Ratio %:**
* The first percentage shows the ratio of unique users who experienced at least one failure on this action, compared to the total number of unique users who attempted it.
* The percentage within parentheses shows the ratio of users who had at least one failed action anywhere within the campaign versus all of the participants in the campaign.
## Failed Actions log by user
* **User:** The username or identifier of the user who experienced the failure.
* **Date:** The date and time when the failed action occurred.
* **Task:** The name of a specific task the user was attempting to complete.
* **Type:** The type of the task the user performed.
* **Platform:** The platform where the failed action occurred.
Clicking on any field within this table will open a User Information modal, providing detailed information about the selected user.
For more details about all User information in Claimr, visit [User information](/data-analytics/user-information).
# Issues analytics
Source: https://docs.claimr.io/data-analytics/issues-analytics
Review user-reported task completion issues and drill into each report's general, task, reporter, and trace details.
## What is Issue analytics?
Issue analytics provides a detailed overview of user-reported problems encountered while completing tasks within Claimr, specifically for VAPs remarketing companies. It allows you to monitor and analyze user-submitted reports to identify and resolve potential task-completion issues.
## How your users see this
When users, aiming to **complete** tasks, encounter issues, they can report them.
The **Report an issue** link appears after three unsuccessful attempts to **complete** a task.
Clicking **Report an issue** opens a modal window where users can:
* Leave their email address.
* Provide a short issue description.
* Attach files.
## Use this data to
* **Identify task completion barriers:** Spot patterns and trends in user-reported issues preventing task **completion**.
* **Improve task clarity:** Address issues to minimize user frustration and ensure smoother task **completion**.
* **Enhance user experience:** Resolve problems promptly to improve overall satisfaction with the task **completion** process.
* **Monitor task integrity:** Ensure tasks are being **completed** correctly and effectively.
## Accessing Issues analytics
1. Log in to your Claimr account.
2. Select the relevant campaign.
3. Click on the **Analytics** tab.
4. Select **Issues** from the submenu.
## Issue dashboard
Once you select **Issues**, the dashboard will open, displaying a table of all reported issues. This table provides a summary of each issue and allows you to quickly assess the situation.
**Table elements:**
* **Reporter:** The username or identifier of the user who reported the issue.
* **Date:** The date and time when the issue was reported.
* **Task:** The name or identifier of the task the user was attempting to complete.
* **Status:** The current status of the reported issue.
* **Title:** A brief title or summary of the issue provided by the user.
* **Summary:** A short description of the issue provided by the user.
To open each issue report for detailed information, click on the respective row in the table.
## Issue details modal
Clicking on a row in the dashboard table opens a modal window containing all the details of the reported issue.
### General information
* **Date:** The date and time when the issue was reported.
* **Title:** The title or summary of the issue provided by the user.
* **Description:** The detailed description of the issue provided by the user.
* **Attached files:** Any files (e.g., screenshots) attached by the user.
### Task section
* **Name:** The name of the task the user was attempting to complete.
* **Status:** The status of the task at the time the issue was reported (e.g., "Failed").
* **Set task as completed:** A button allowing you to manually mark the task as completed if you determine the issue does not prevent successful completion.
### Reporter section
* **ID:** The unique identifier of the user who reported the issue.
* **Name:** The username of the user who reported the issue.
* **Email:** The email address of the user who reported the issue.
* **User details:** A button or link to view more detailed information about the reporting user.
For more details about all User information in Claimr, visit [User information](/data-analytics/user-information).
### Trace section
This section provides a breadcrumb trail of the user's activity leading up to the reported issue. You can recreate the user's steps and identify the source of the problem.
* **Group:** The group associated with the task. This helps identify the specific set of tasks or users involved.
* **Quest:** The quest associated with the task. This helps pinpoint the specific campaign or sequence of actions the user was attempting.
* **Task:** The name of the task the user was attempting to complete.
# Data analytics
Source: https://docs.claimr.io/data-analytics/overview
See what you can do with Claimr analytics and find your way into activity, referrals, UGC, PoW, user information, failed actions, and issues.
Analytics in Claimr provide valuable insights into your campaign's performance and user behavior. Track various metrics, such as user engagement, task completion rates, and reward distribution, to measure the effectiveness of your campaigns and make data-driven decisions.
## Analytics tabs
The Analytics section is divided into several tabs, each offering valuable insights into different aspects of your campaign.
* **Claimers:** See the data on the users who have claimed rewards within your campaign.
* **Activity:** Check the detailed overview of user activity within your campaign, such as task completions, reward claims, and logins.
* **Profiles:** Analyze the data about users, including their names, IP addresses, and other relevant information.
* **Onchain:** View on-chain activity related to your campaign.
* **Referral:** Track the performance of your referral program and see how many users joined through referral links.
* **UGC:** View data about user-generated content, such as the number of posts or videos created.
* **PoW:** Check the information about proof-of-work activities within your campaign.
* **Forms:** Analyze the performance of your forms, including completion rates and responses to individual questions.
* **Polls:** View data related to polls within your campaign.
* **Platforms:** See which platforms users are using to interact with your campaign like web or social media.
* **Events:** Track data on events within your campaign, such as the number of candidates in raffles or challenges.
* **Reports:** Check reports based on various campaign metrics, including sources, top countries, top IPs, task completion rates, quest completion rates, and more.
* **Failed actions:** View a log of actions attempted by users that resulted in a failure.
* **Issues:** Track and analyze user-reported issues related to task completion and other campaign interactions.
Track user engagement and campaign performance.
Analyze your referral program's performance.
Review and manage user-generated content submissions.
Verify and manage Proof of Work submissions.
Get deep insight into individual users' data.
Identify common failure points in task completion.
Monitor and resolve user-reported issues.
# PoW analytics
Source: https://docs.claimr.io/data-analytics/pow-analytics
Review, approve, reject, filter, and export Proof of Work task submissions to ensure the integrity of your campaign.
## What is PoW analytics?
The PoW (Proof of Work) analytics provides a detailed overview of all user submissions for your Proof of Work tasks, allowing you to review, approve, reject, and analyze the results. This gives you valuable insights into user engagement with your PoW tasks and helps ensure the integrity of your campaign.
### Use this data to
* **Verify user submissions:** Review the images, links, or answers provided by users as proof of completing tasks.
* **Maintain quality control:** Approve valid submissions and reject those that don't meet the task requirements, ensuring only genuine participation is rewarded.
* **Track submission rates:** Monitor how many users are attempting and completing your PoW tasks.
* **Identify potential issues:** Spot any problems with your PoW task instructions or requirements (e.g., a high rejection rate might indicate unclear instructions).
* **Gather and export data:** Download the PoW submission data for further analysis or reporting.
To learn more about creating and configuring Proof of Work tasks, visit [PoW tasks](/tasks/pow-tasks).
## Accessing the PoW section
1. Log in to your Claimr account.
2. Select the campaign you want to analyze.
3. Click on the **Analytics** tab in the campaign's header menu.
4. Select **PoW** from the dropdown menu (or the submenu, depending on the final navigation structure).
## PoW analytics dashboard
The PoW Analytics dashboard provides a comprehensive overview of all Proof of Work submissions within your campaign, allowing you to review, approve, reject, and analyze user-provided evidence.
The PoW dashboard provides several tools to help you efficiently manage submissions:
* **Show unverified only:** Use this toggle switch to manage your workflow.
* **Enabled:** Displays *only* submissions that are awaiting review (neither approved nor rejected).
* **Disabled:** Displays *all* submissions, regardless of their status.
* **Task filter:** Filter submissions by the specific PoW task.
* **Type filter:** Filter submissions by the type of PoW task: Image, Link, or Answer.
* **Status filter:** Filter submissions by their current status: Unverified, Approved, Rejected.
* **Search:** Use the search bar to find specific submissions.
* **View buttons:** Choose how submissions are displayed: grid or list view.
* **Export to Google Sheets:** Export the PoW submission data to a Google Sheet for further analysis, reporting, or archiving. The exported spreadsheet will contain the following columns:
1. **Entry ID:** A unique identifier for each submission.
2. **User name:** The display name or username of the user who made the submission.
3. **Date:** The date and time the submission was made.
4. **Type:** The type of PoW task: image, link, answer.
5. **Action name:** The specific name of the PoW task.
6. **Text:** The additional text input provided by the user. This additional text input is controlled by the "Show text input" toggle and the "Text Input Title" in the task settings.
7. **URI:** For "Link" and "Image" type submissions, this column will contain the URL of the submitted link or image. For "Answer" type submissions, this column will contain the text submitted by the user.
8. **Status:** The current status of the submission: approved, rejected, or unverified.
### Submission card
The PoW submissions are displayed either as cards or as rows in a table, depending on the selected view button. Each card represents a single submission and includes the following information:
* **Checkbox:** Allows you to select individual submissions for bulk actions (Approve, Reject).
* **Status Indicator:** A colored dot in the upper-right corner of each card visually indicates the submission's status:
* **Green:** Approved.
* **Red:** Rejected.
* **Orange:** Unverified (pending review).
* **Task:** The name of the PoW task the submission is for.
* **User:** The user who made the submission. A "Copy ID" button/link allows you to easily copy the user's ID.
* **Date:** The date and time the submission was made.
* **Preview (Image Tasks):** For "Image as Proof of Work" tasks, a thumbnail preview of the submitted image is displayed directly on the card. Clicking on this preview likely opens a larger view of the image.
* **Preview (Link/Answer Tasks):** For "Link" and "Answer" tasks, a preview of the submitted link or answer text would be displayed.
* **Approve/Reject buttons:** Each card has two buttons:
* **Green checkmark:** Approve the submission.
* **Red cross:** Reject the submission.
### Bulk actions
The buttons at the bottom of the dashboard allow you to perform actions on multiple selected submissions:
* **Select all:** Selects all currently displayed submissions.
* **Clear selections:** Unselects all submissions.
* **Approve:** Approves all selected submissions.
* **Reject:** Rejects all selected submissions. The number in parentheses indicates how many submissions are currently selected.
# Referrals analytics
Source: https://docs.claimr.io/data-analytics/referrals
Monitor referrers and referred users, export referral data, and understand how verified and unverified referral statuses are determined.
## What is Referrals analytics?
Referrals Analytics provides a detailed overview of your campaign's referral program performance. It allows you to monitor and analyze the activity of both referrers and the users they invite, helping you understand the effectiveness of your word-of-mouth marketing efforts within Claimr.
#### Use this data to
* **Track program performance:** Monitor the overall success and reach of your referral campaign.
* **Identify top referrers:** Discover your most influential users who are driving new participants to your campaign.
* **Analyze referred user activity:** Assess the engagement level of users who joined through a referral link.
* **Optimize your referral strategy:** Use insights to refine rewards and improve the effectiveness of your referral program.
## Accessing Referrals analytics
1. Log in to your Claimr account.
2. Select the relevant campaign.
3. Click on the **Analytics** tab in the top navigation menu.
4. Select **Referral** from the submenu.
## Referrals dashboard
Once you select **Referral**, the dashboard will open, displaying a table with all referral data. This dashboard provides tools to analyze and export your referral information.
### Dashboard features
* **Export to Google Sheets:** Click this button to export the referral data directly to a Google Sheet for further analysis.
* **Export .csv file:** Click this button to download the referral data as a .csv file.
* **Collapse/Expand:** Use this feature to collapse or expand sections of the view.
* **Hide empty:** Enable this toggle to hide users who haven't brought in any referrals. This action cleans up the view by removing empty rows.
* **Search:** Use the search bar on the right to find specific users or data within the table.
### Table elements
This table offers a comprehensive breakdown of each referral relationship.
* **User ID:** The unique identifier for the user.
* **Ref ID:** The unique identifier for this referrer.
* **Name:** The name of this user.
* **Date:** The date the user was added.
* **IP:** The IP address of this referrer.
* **IP score:** The risk or trust score associated with the user's IP address.
* **Total users:** The total number of users invited by this user.
* **Ref points:** The total points accumulated by all referrals.
* **Shared points:** The total points the referrer earned from their referrals.
* **Total points:** The total points the referrer earned during the campaign.
* **Ref IP:** The IP address of the referrals.
* **Ref status:** The status of the referral:
* **Unverified:** Not yet valid for referral rewards or program criteria.
* **Verified:** Completed required actions and passed all validation checks. A verified referral typically means the user is authenticated, passed bot checks (not disqualified), completed a required task, and earned a minimum points amount as defined by your settings.
* **Joined at:** The date and time the referral user joined the campaign.
* **Tasks points:** The total points the referral user earned from completing tasks.
* **Completed tasks:** The total number of tasks the referral user completed.
## Determine referral status (Verified/Unverified)
Your referral's status, whether **Verified** or **Unverified**, is directly determined by the **referral verification rules you set up** in your settings.
To configure these rules:
1. Navigate to **Settings**.
2. Select **Referral** from the menu. This opens **Referral System Settings**.
3. Click the **Edit icon** (pencil) to open the configuration window.
Within this window, you can:
* Specify the **minimum number of points** a referral needs to earn to be considered verified.
* Select **specific task dependencies** that must be completed.
Once you save these settings, the system will automatically assign each referral a **Verified** or **Unverified** status based on whether they've met the conditions you defined.
# UGC analytics
Source: https://docs.claimr.io/data-analytics/ugc-analytics
Review, approve, reject, and rate user-generated content submitted through UGC tasks in your campaign.
## What is UGC analytics?
The UGC (User-Generated Content) analytics section gives you a full overview of all video and media submissions shared by users as part of your UGC tasks. It helps you evaluate the quality and relevance of these submissions and make data-informed decisions about user engagement and rewards.
**Use UGC analytics to:**
* Review user submissions: Open the images or links your users submitted.
* Track post performance: See metrics like views, shares, and comments - available for tracking tasks only.
* Manage content: Approve valid submissions or reject the ones that don't meet your requirements.
* Rate content quality: Assign a score to each submission (internal use only).
* Monitor participation: Access submission timestamps, user IDs, and file or link references.
To learn more about how to create a UGC task, visit [UGC tasks](/tasks/ugc-tasks).
## How your users see UGC tasks
1. Your user selects a UGC task in your campaign.
2. They upload an image or submit a link, depending on the task type.
3. The task is marked as completed.
4. Their submission appears in your UGC analytics section, where you can see and manage it.
## Accessing the UGC section
1. Log in to your Claimr account.
2. Select your campaign.
3. Click the Analytics tab in the campaign menu.
4. Choose UGC from the analytics submenu.
### UGC dashboard
The UGC dashboard displays all user-submitted content in a visual grid. Each submission appears as a card that includes key information and actions. You can manage and evaluate incoming UGC here.
Use the dashboard to:
* View submissions: See thumbnails and link previews depending on the task type.
* Sort or filter entries: Filter by task type, status, or other parameters.
* Approve or reject: Click the check or cross icon to change the submission status.
* Score content: Assign an internal quality rating to any UGC item.
* Bulk action: Select multiple cards and perform approval/rejection actions for all selected entries.
### UGC's submission card
* **Preview:** A thumbnail for images or a visible link for URLs.
* **User information:** The user's display name and ID (with copy option).
* **Submission type:** Image or link, depending on task settings.
* **Performance metrics:** Plays, shares, and comments (for tracking tasks only).
* **Date:** When the submission was received.
* **Status:** You can approve (check) or reject (cross) any submission. By default, submissions are approved as soon as the task is completed, but you can manually override this.
* **Score:** An optional field where you can rate content. It lets you rate your users' content based on creativity, relevance, or any other criteria you choose. It does not influence task completion or point allocation.
# User information
Source: https://docs.claimr.io/data-analytics/user-information
Open a user's detail modal to see their general info, UTM data, points, quests, tasks, rewards, referrals, transactions, and account actions.
**User information** provides valuable insights into how individuals interact with your campaigns. This data can be used to personalize user experiences, optimize campaign performance, identify trends, and troubleshoot issues. Analyzing user information allows you to understand user behavior, segment your audience, and make data-driven decisions.
To view a user's detailed information:
1. Navigate to the **Analytics** section.
2. Select the relevant table (Activity, Referrals, etc.).
3. Find the user in the table.
4. Click on the user's row. This will open a modal window with a comprehensive overview.
## General
* **ID:** The user's unique identifier.
* **IP:** The user's IP address.
* **Country:** The user's country of origin.
* **Status:** The user's current status in the campaign (e.g., Active, Inactive).
* **Team:** The team the user belongs to (if applicable).
* **Tiers:** The user's current levels or ranks in the campaign.
* **Referrals:** The number of referrals the user has made.
* **Ref ID:** The user's referral ID (if applicable).
## UTM
* **UTM Source:** The source of the user's traffic (e.g., a specific website or campaign).
* **UTM Campaign:** The name of the campaign the user is participating in.
* **UTM Medium:** The medium through which the user accessed the campaign (e.g., email, social media).
* **UTM Term:** The specific keyword or search term that led the user to the campaign, typically used in paid advertising campaigns (e.g., Google Ads).
* **UTM Content:** The specific content the user interacted with before joining the campaign.
## User
* **Name:** The user's display name or username. This information can be edited.
## Profiles
This section displays the usernames or profiles associated with the user on various platforms connected to the campaign, such as X, TikTok, wallet, etc.
## Points section
The points section shows how many points were earned from various sources and allows you to adjust manually the user's total points if needed.
The following fields display the **Points** earned from different sources:
* **Initial Points** are assigned to the user at the start of the campaign.
* **Tasks Points** are earned from completing tasks.
* **Quests Points** are earned from completing quests.
* **Referral Points** are earned through referrals.
* **Rewards Points** are earned from claiming rewards.
* **Rank Points** are earned from achieving ranks.
* **Challenges Points** are earned from completing challenges.
* **Withdraws points** are any reductions to a user's total points, such as penalties or corrections applied via the Claimr API.
* **Multiplier** is applied to the earned points (e.g., due to a bonus or promotion).
* **Total Points** are accumulated points in the campaign, including any bonuses or multipliers.
* **Additional Points** field allows you to add manually points to the user's total. This can be useful for correcting errors, awarding bonus points, or adjusting points based on special circumstances.
## Quests
This section displays a table listing all the quests the user has participated in. The table includes:
* **Quest:** The name of the quest.
* **Date:** The date and time the user participated in the quest.
* **Points:** The amount of points earned for that quest.
The total points earned from all quests is displayed at the bottom of the table.
## Tasks
This section displays a table listing all the tasks the user has completed or attempted.
* **Task:** The name of the task.
* **History:** The date and time of completion or attempt.
* **Points:** The amount of points earned for the task.
* **Extra:** Any additional points earned for the task.
The total points earned from all tasks is displayed at the bottom of the table. You can also add tasks through the **Select task dropdown**.
## Challenges
This section displays a table listing all the challenges the user has participated in.
* **Challenge Name:** The name of the challenge.
* **Points:** The amount of points earned for the challenge.
* **Rewards:** Any rewards associated with the challenge.
The total points earned from all challenges is displayed at the bottom of the table.
## PoW
This section displays a table listing the user's Proof of Work (PoW) activities.
* **Date:** The date and time the PoW activity was performed.
* **Task Name:** The name of the task associated with the PoW activity.
* **Task Type:** The type of PoW task (e.g., "Image as Proof of Work").
* **Status:** The status of the PoW activity (e.g., "approved," "rejected").
* **Content:** The content submitted as proof of work (e.g., a link to a tweet or a screenshot).
* **Actions:** The available actions for the PoW activity.
## UGC
This section displays a table listing any user-generated content (UGC) that the user has submitted as part of the campaign.
* **Date:** The date and time the UGC was submitted.
* **Score:** The score assigned to the UGC.
* **Preview:** A preview of the UGC, which could be an image, video thumbnail, or text excerpt.
* **File type:** The file submitted as UGC (e.g., JPEG, GIF).
## Rewards
This section displays a table listing the rewards the user has earned.
* **Date:** The date and time when the user earned the reward.
* **Type:** The type of reward earned. This indicates the source or reason for the reward (e.g., daily login bonus, task completion, referral, etc.).
* **Reward Points:** Amount of points user got for completing the action.
## Polls
This section displays a table listing any polls the user has participated in. The table includes the following columns:
* **Task:** The name of the task associated with the poll.
* **Date:** The date and time when the user participated in the poll.
* **Answer:** The answer that the user selected in the poll.
## Withdraws
This section displays a table listing any deductions (withdrawals) made from the user's total points balance.
* **Date:** The date and time when the points were deducted.
* **Type:** The type for the point deduction indicating the deduction was made via the Claimr API.
* **Points:** The number of points deducted in this specific transaction (e.g., `50` in the example).
* **Total Points:** The user total points after all operations.
## Referrals
This section displays information related to the user's referral activities.
* **Name:** The name or identifier of the user who was referred.
* **Status:** The status of the referral.
* **Date:** The date when the referral occurred.
* **Ref. Points:** The number of points or rewards earned for the referral.
* **Total Points:** The total points accumulated by the user through referrals.
## Transactions
This section lists all transactions associated with the user's account.
* **Hash:** The unique identifier (hash) of the transaction.
* **Network:** The blockchain network on which the transaction occurred.
* **Contract:** The contract address involved in the transaction.
* **Date:** The date and time of the transaction.
* **Status:** The status of the transaction.
## Failed actions
This section displays a log of any actions attempted by the user that resulted in a failure.
* **Task:** The name or identifier of the specific task the user was attempting to complete.
* **Date:** The date and time when the action was attempted. Multiple date entries for the same task indicate multiple attempts.
* **Type:** The type of task the user attempted (e.g., "Follow on X").
* **Status:** The status of the attempted action (e.g., "Failed", "Completed"). This indicates whether the action was successful or not.
For more details about all User information in Claimr, visit [Failed actions](/data-analytics/failed-actions).
## Issues
This section lists any reported issues or problems associated with the user's account.
* **Task:** The name or identifier of the specific task associated with the reported issue.
* **Date:** The date and time when the issue was reported.
* **Title:** A brief title or summary of the issue, often provided by the user when reporting the problem.
* **Summary:** A more detailed description or explanation of the issue provided by the user.
For more details about all User information in Claimr, visit [Issues analytics](/data-analytics/issues-analytics).
## Actions
### Disqualify user toggle
* Marks the user as a bot or engaging in suspicious activity.
* Excludes the user's referrals from statistics.
* Renders the user invalid as a referral/referrer.
### Lock user toggle
* Immediately suspends the user's account.
* Removes the user's access to the campaign.
### Delete user activity button
* Initiates the permanent deletion of all user activity.
* Should be used with extreme caution as an irreversible action.
# Descriptions
Source: https://docs.claimr.io/descriptions-creation-usage-tags
Learn how to format description fields across Claimr and use dynamic tags to personalize campaigns, quests, tasks, and forms for each participant.
## What are descriptions?
Descriptions are text fields used across Claimr modules, including campaigns, groups, contests, tasks, and forms. They allow you to add instructions, tags, contextual details, and media that participants see when interacting with your campaign.
While the text editor looks the same across modules, each description field is specific to its context (for example, campaign description vs. task description).
## Description editor
Each description field opens a text editor where you can:
* Format text (fonts, styles, alignment, sub/superscript)
* Change text and background colors
* Add images
* Add links
After editing, click **Save** to apply your changes. Use the **Preview** option to check how your description will look for participants.
### Dark and light modes
Descriptions support both Light and Dark modes.
* The default text color is black.
* When using Dark mode, black text may not be visible. In this case, you should manually select a light or bright text color to ensure readability.
* The editor does not automatically adjust text colors - you are responsible for setting colors that are visible in both modes.
## Description tags
Descriptions support tags, which allow you to insert dynamic values. Tags personalize the experience for each participant by displaying campaign- or user-specific data.
### How to use tags
1. Insert a tag directly into the text editor.
2. Save your changes.
3. When participants view the campaign, the tag will be replaced with the correct value.
### Available tags
#### 1. User-related tags
Display information about the current user and their profile attributes.
* `{{claimr_id}}`: Displays the unique Claimr user ID.
* `{{user_name}}`: Displays the user's profile name.
* `{{evm_address}}`: Shows the user's connected EVM wallet address (if available).
* `{{ref_name}}`: Displays the name of the user who referred the current user.
* `{{team_name}}`: Shows the name of the team the user belongs to.
* `{{rank}}`: Displays the user's current rank in the campaign.
* `{{leaderboard_position}}`: Shows the user's position on the campaign leaderboard.
* `{{campaign_progression}}`: Displays the user's campaign progression status.
#### 2. Points-related tags
These tags display information about experience points (XP) and other custom point types.
* `{{total_xp}}`: Displays the user's total accumulated experience points (XP) in the campaign.
* `{{xp_alias}}`: Shows the campaign's custom XP label.
* `{{ref_xp}}`: Displays the XP earned from referrals.
* `{{task_xp}}`: Displays the XP earned from a specific (selected) task.
* `{{points_[PointID]_XP}}`: Displays the user's balance of an additional point type. This tag is specific to the customizable points you created. The PointID must match the ID you entered manually when creating the point.
#### 3. Campaign-level tags
These tags provide general statistics about the campaign.
* `{{participants}}`: Displays the total number of participants in the campaign.
#### 4. Referral-related tags
Track user referrals and rewards earned through referrals.
* `{{ref_count}}`: Shows the total number of referrals the user has made.
* `{{ref_xp}}`: Displays the XP earned from referrals.
#### 5. Quest and task-related tags
Show quest and task completions, as well as rewards.
* `{{completed_quests}}`: Shows how many quests the user has completed.
* `{{quests}}`: Displays the total number of quests available in the campaign.
* `{{max_quest_reward}}`: Displays the maximum reward available for a single quest. Works only within the selected quest.
* `{{task_xp}}`: Displays the XP earned from a specific (selected) task.
#### 6. API task-specific tags
Specific to API tasks and display scores, counts, and requirements.
* `{{api_task_total_score}}`: Shows the total score across all API tasks.
* `{{api_task_count}}`: Displays the number of API tasks completed.
* `{{api_task_user_score}}`: Shows the user's score for an API task.
* `{{api_task_user_total_count}}`: Displays the total number of API tasks completed by the user.
* `{{api_task_min_value}}`: Displays the minimum value required for an API task.
#### 7. Event-related tags
These tags display data collected from event-based tracking.
* `{{events_value}}`: Displays the value from event-based tracking.
* `{{events_max_value}}`: Shows the maximum event value reached.
* `{{events_last_value}}`: Displays the last recorded event value.
* `{{events_count}}`: Shows the total number of events recorded.
* `{{events_max_count}}`: Shows the maximum number of events reached.
* `{{events_last_count}}`: Shows the last recorded event count.
Make sure all tags are entered exactly as written to be recognized.
## Usage across Claimr
Descriptions appear in multiple places but follow the same principles. For details on where each description is used, see:
* [Campaign settings](/campaigns/general-campaign-settings)
* [Group description](/groups/group-settings)
* [Quest settings](/quests/quest-settings)
* [Task settings](/tasks/task-settings)
* [Form description](/forms/form-settings)
* [Pop-ups](/pop-ups/overview)
* [Challenges](/extra/challenges)
# Challenges
Source: https://docs.claimr.io/extra/challenges
Configure challenge type, requirements, and rewards, and see how challenge tiles appear and update for users.
## Understanding Claimr challenges
A challenge is a focused objective or set of tasks that users can undertake within your campaign. It adds an element of excitement and competition, encouraging users to go above and beyond the standard campaign activities.
### Benefits of using challenges
**Increased engagement**: Provide an extra layer of gamification, encouraging users to participate more actively in your campaigns.
**Targeted actions**: Design challenges to drive specific user actions, such as completing tasks, exploring content, or making referrals.
**Rewarding achievements**: Provide a sense of accomplishment and reward users for their efforts.
## Configuring challenges
Navigate to the **Events** section in the Claimr admin panel and select the **Challenges** tab.
Click **Create Challenge** to add a new one. A sidebar panel with settings will appear.
* **Name**: Provide a clear and concise name for the challenge.
* **Image**: Upload an image or icon that represents the challenge.
* **Description**: Add a brief explanation of the purpose or theme. This helps users understand what to expect within this challenge. Click **Create description** (if no description exists) or **Edit** (if a description already exists) below the Description field. This will open a text editor where you can write and format your description. Remember to click **Save** to keep your new or updated description. For more details on descriptions and tags, visit [Descriptions: creation, usage, tags](/descriptions-creation-usage-tags).
* **Challenge type**: Choose the type of challenge:
* Tasks Count: Tracks the number of tasks a user must complete.
* Quests Count: Tracks the number of quests a user must complete.
* Tasks Set: Requires users to complete a specific set of tasks.
* Quests Set: Requires users to complete a specific set of quests.
* **Configure Challenge Settings**: Depending on the challenge type, configure specific settings. For example, if you chose "Tasks Count," you'll need to specify the minimum number of tasks required in the "Min Tasks" field.
* **Set Rewards**: Define the rewards that users will earn for completing the challenge. You can include XP, as well as extra rewards like NFTs or gift codes.
Click the **Create** button to save your new challenge.
To make your challenges appear in the widget and function correctly, ensure you have enabled the necessary add-on in your Claimr campaign settings. For more information, visit [Widget configurations](/widget/widget-configurations).
## Presenting challenges to users
Challenges are presented to users as interactive tiles within the Claimr widget. These tiles include:
**Challenge name and description**: A brief description of the challenge and what users need to do to complete it.
**Reward**: Clearly displays the reward that users will earn for completing the challenge.
**Progress counter**: A visual indicator that shows the user's progress towards completing the challenge.
## How users interact with challenges
Users view the challenge tile in the widget. They attempt to complete the challenge requirements. The challenge tile's progress bar updates as the user makes progress. Once the user completes the challenge, they receive the associated reward.
# Daily check-ins
Source: https://docs.claimr.io/extra/daily-check-ins
Set up daily check-ins through the Events tab or as a quest task, configure the calendar display, customize per-day rewards, and see how check-ins appear to users.
## Understanding daily check-ins
Daily check-ins are a powerful tool for increasing user engagement and encouraging repeat visits to your campaign. They allow you to offer rewards that users can claim once a day, creating a consistent incentive to return and participate.
Daily check-ins are set up in a cycle. Once all the configured days have been claimed, the cycle restarts from Day 1.
## Setting up daily check-ins
### Access the Daily check-ins section
1. Log in to your Claimr account.
2. Navigate to the **Events** section in the main navigation menu.
3. Select the **Daily** tab.
4. Click **Create Daily Reward** to add a new daily event entry.
To modify an existing daily check-in, click the edit button (pencil icon) in the corresponding row. This will open a modal window where you can adjust the day, XP, and associated rewards.
* **Day**: Specify the day of the reward cycle (e.g., Day 1, Day 2, Day 3).
* **XP**: Enter the number of experience points (XP) that users will receive for claiming the reward on that day.
* **Rewards**: To add or modify extra rewards, click **Create reward**. This will open a new modal window where you can select the reward type (e.g., Web3 token, Discord role, Gift Code) and configure its settings. For more information about rewards, read [Reward settings](/rewards/reward-settings).
### Create daily check-ins through tasks
Log in to your Claimr account and go to the **Quests** tab.
Choose the quest where you want to add a daily event task.
Click **+ Create a new task**.
Select **Common** from the list of task types. From the expanded list, choose **Daily Checkin**.
### Configure calendar display
You can display a calendar directly within the campaign widget for Daily Check-in tasks. This calendar visually represents the user's progress and helps them track their daily check-ins.
To configure this setting:
1. Go to the **Task settings** for your Daily Check-in task.
2. Locate the **Calendar** section.
3. Select **"Daily"** to enable the calendar display in the widget. If you select "-", it will not be displayed.
### Customize daily rewards
You can also customize the reward for each individual day of the daily check-in period. This allows you to offer different incentives for consecutive check-ins.
To set unique rewards for each day:
1. Within the **Task settings** for your Daily Check-in task, navigate to the **Rewards** section.
2. You will see a list of days, each with a field to define the reward for that specific day.
3. Enter the desired reward for each day. For example, you can assign different points or digital assets for day 1, day 2, and so on.
For other settings, follow the usual instructions in [Task settings](/tasks/task-settings).
## How daily check-ins appear to users
The appearance of daily check-ins to users depends on whether the calendar option is enabled in your task settings. In both cases, only one daily check-in event is claimable at a time; subsequent days' events become visible only after the previous day's reward has been successfully claimed. Users claim their reward by clicking the designated button, after which they must wait until the next day to claim the next reward.
### When the calendar option is on
When the calendar option is switched on in your task settings, the daily check-ins are displayed within a visual calendar format in the campaign widget.
* **Visual tracking**: Users can see the number of the day, with completed days marked.
* **"Done" icon**: Once a daily task is completed, it will be tagged with a "done" icon on the corresponding day in the calendar.
* **Before claiming**: The daily check-in is presented as a button with a clear call to action (e.g., "Earn 15 XP").
* **After claiming**: Once claimed, the button is replaced with a message indicating that the reward has been claimed and encouraging the user to return the next day (e.g., "Come back tomorrow").
### When the calendar option is off
If the calendar option is switched off, the daily check-in will appear as a standalone button without the calendar grid.
* **Before claiming**: The daily check-in is presented as a button with a call to action (e.g., "Earn 15 XP").
* **After claiming**: Once claimed, the button changes to a message indicating that the reward has been claimed and prompting the user to return the next day (e.g., "Come back tomorrow").
# KOLs
Source: https://docs.claimr.io/extra/kols
Set up KOL entries with unique referral links and track referral performance metrics like valid referrals, total referrals, and XP earned.
## Understanding KOLs
KOLs, or Key Opinion Leaders, are individuals who have built a strong online presence and influence within a particular niche or community. They are often seen as experts or trusted sources of information, and their opinions and recommendations can significantly impact the decisions of their followers.
## Benefits of using KOLs
**Increased reach**: KOLs can significantly expand the reach of your Claimr campaigns. Their established audience and online presence can introduce your campaigns to a wider range of potential participants, increasing visibility and attracting new users.
**Enhanced credibility**: KOLs often have a high level of trust and credibility within their communities. By partnering with them, you can leverage this trust to enhance the perceived value and legitimacy of your campaigns, encouraging more users to participate.
**Targeted promotion**: KOLs can effectively promote specific aspects of your campaigns or target particular user segments. This allows you to tailor your message and reach the most relevant audience for your campaign goals.
**Performance tracking**: Claimr provides tools to track the performance of your KOL partnerships. You can monitor metrics such as the number of referrals, completed tasks, and overall engagement generated by each KOL, allowing you to measure the effectiveness of your collaborations and optimize your strategies.
## Setting up KOLs
Navigate to the **Events** section in the Claimr admin panel and select the **KOLs** tab.
Click the **Create** button to add a new KOL entry.
* **Name**: Enter the name of the KOL.
* **KOL ID (optional)**: Assign a custom ID to the KOL for internal management. This ID must be 8 to 24 characters long and can only contain letters, numbers, hyphens, and underscores.
* **Ref Link**:
* **Base link**: Provide the base URL for the KOL's referral link. This should be a link to a page with a Claimr widget, such as a landing page or a client's website.
* **Referral ID tag**: Select a tag that will be appended to the base link to create the unique referral link: "ref" or "invite".
Click **Create** to save the new KOL entry. This will generate a unique KOL referral link, including the specified tag and the KOL's ID.
## Tracking KOL performance
Claimr provides a table in the KOLs section to track the performance of your KOLs. It includes:
* **Name**: The name of the KOL.
* **Link ID**: The unique ID associated with the KOL's referral link.
* **Link**: The full referral link the KOL can share with their audience.
* **Valid referrals**: The number of users who joined your campaign through the KOL's unique referral link and performed a qualifying action.
* **Total referrals**: The total number of referrals attributed to the KOL, including those who may not have completed any actions.
* **XP**: The total amount of XP earned by the KOL's referrals.
* **Completed \[X] tasks**: The number of users referred by the KOL who have completed a specific number of tasks (1, 3, 5, 7, and 10).
## Presenting KOLs to users
When users click on a KOL's unique referral link they are directed to a page with a Claimr widget.
A typical KOL widget might display the title, the rewards information, a brief instruction ("Click to earn 10 XP"), and a button.
# Extra
Source: https://docs.claimr.io/extra/overview
See what the Extra section offers - raffles, daily check-ins, challenges, ranks, KOLs, and tournaments - to keep users coming back for more.
The Extra section in Claimr provides a powerful set of tools to enhance your campaigns with dynamic activities and rewards. Here you can configure various features to incentivize users, foster engagement, and create a more interactive experience.
This section includes the following features:
* **Raffles**: Create exciting raffles and giveaways to reward users and generate excitement. Configure the prize, entry requirements (e.g., completing specific tasks), and duration of the raffle.
* **Daily check-ins**: Offer daily events and rewards to encourage regular participation. Configure the reward cycle, XP awarded, and any extra rewards associated with each day.
* **Challenges**: Create standalone challenges that run alongside your main campaign, providing additional opportunities for engagement and rewards. Configure the challenge type (tasks count, quests count, tasks set, or quests set), define the requirements, and set the rewards.
* **Ranks**: Establish a ranking system to foster friendly competition and motivate users to progress. Define the different ranks, the criteria for achieving each rank, and the associated rewards or benefits.
* **KOLs**: Incorporate Key Opinion Leaders (KOLs) into your campaigns to leverage their influence and reach a wider audience. Define the KOL's role in the campaign, the tasks or actions they will promote, and any associated rewards or incentives.
* **Tournaments**: Run temporary, time-boxed leaderboard sessions alongside your main campaign leaderboard.
* **Invite codes**: Generate and distribute invite codes to control access to your campaign or reward loyal users. Configure the code generation parameters, distribution methods, and any associated benefits or restrictions.
* **Gift codes**: Offer gift codes as rewards, providing users with tangible benefits or discounts. Configure the type of gift codes, their value, and the redemption process.
Randomly select winners from a defined user group based on eligibility conditions.
Reward users for returning to your campaign every day.
Set up standalone objectives that run alongside your main campaign.
Build a tiered achievement system to motivate progression.
Track referral performance from Key Opinion Leaders.
Run temporary, time-boxed leaderboard events.
Control access to your campaign with unique invite codes.
Deliver tangible, redeemable rewards to your participants.
# Raffles
Source: https://docs.claimr.io/extra/raffles
Configure raffle type, leaderboard source, eligibility requirements, and review winners and analytics for Claimr raffles.
## What are raffles?
Raffles are special events that allow you to randomly select winners from a defined user group.
Each raffle works as an independent draw based on eligibility conditions such as connected logins, completed quests or tasks, and accumulated points. It is used to form a list of users who participate in a draw. The system then automatically selects the winner(s) according to the configured logic.
Users do not see raffles in the app interface: participation happens automatically based on activity and eligibility.
## Configuration steps
In the header menu, go to **Extra** and select **Raffles**.
Click the **Create Raffle** button. This opens the raffle settings window.
**Raffle name**
Enter the raffle name.
**Type**
Select how the winner(s) will be determined.
* Hiscores - selects winners based on the highest number of points.
* Random - selects winners completely at random.
* Random based on points - selects winners randomly but with higher probability for users who have more points.
**Leaderboard**
Select the leaderboard from which participants will be drawn.
* General campaign leaderboard - includes all users participating in the campaign.
* Tournament leaderboard - includes only users who are part of active tournaments.
**Max participants**
Define the maximum number of users allowed to qualify for the raffle. For example, if there are 20 eligible participants but the limit is set to 10, only the top 10 will qualify as winners.
**Min points**
Set the minimum number of points required for a user to enter the raffle.
**Required logins**
Select the connected platforms users must have to qualify for the raffle.
**Required quests**
Select the quests users must complete to become eligible.
**Required tasks**
Select the tasks users must complete to qualify. Tasks can be linked to quests or used independently.
When all fields are configured, click **Create**. The raffle will appear in the list of raffles.
## Raffle status and management
Once the raffle is created, it appears as a card in your Raffles dashboard. On the raffle card, you can see:
* The raffle status
* The selected type and leaderboard
* The number of participants
* The required points threshold
* The required logins, quests, and tasks
**Raffle statuses**:
* Created - the raffle is configured but not yet finalized. Raffles remain in created status until they are closed.
* Closed (ended) - the raffle is completed, and results are available for review.
Once closed, the system compiles the participant list based on all configured conditions and determines the winners according to the selected type.
Raffles can be managed using the available actions:
* End - close the raffle and generate the results.
* Edit - modify raffle settings.
* Delete - remove the raffle.
* Analytics - open participant details and winner information.
## Analytics
From the raffle card, click the Analytics icon in the upper corner to view participant data.
The leaderboard table displays:
* Position - participant ranking in the raffle.
* Status - allows you to manually disqualify or restore users.
* Name - participant name.
* Quests - completed quests (if applicable).
* Tasks - completed tasks (if applicable).
* Points - total points earned.
Users marked in gray are excluded from the export file and do not appear in the list of winners.
Click **Get leaderboard .csv** to export the final participant data, including usernames, connected platforms, and point totals. Only qualified users (within the defined participant limit and meeting all requirements) are included in the exported file.
## User view
Raffles are invisible to users in the app interface. Participation and winner selection are handled entirely in the admin panel. You can optionally use the exported data to announce winners or manage prize distribution externally.
# Ranks
Source: https://docs.claimr.io/extra/ranks
Configure rank tiers, point thresholds, and rewards, and see how ranks and progress bars appear to users.
## Understanding ranks
Ranks are a powerful gamification tool that allows you to create a tiered system of achievement within your campaigns. Users earn points by completing tasks and quests, and as they accumulate points, they progress through different ranks. Each rank can be associated with specific rewards, benefits, or recognition, providing a clear path for users to strive for and a sense of accomplishment as they advance.
### Benefits of using ranks
**Increased engagement**: Ranks provide a clear goal for users to work towards, encouraging them to participate more actively in your campaigns.
**Motivation and progression**: The tiered system motivates users to continue engaging with your campaign to reach higher ranks and unlock new rewards.
**Sense of accomplishment**: Achieving new ranks provides a sense of accomplishment and recognition, fostering a positive user experience.
**Community building**: Ranks can be used to create a sense of community and hierarchy within your campaign, encouraging users to compare their progress and strive for higher levels of achievement.
**Personalization**: Ranks can be customized to match your campaign's theme and branding, creating a more immersive and engaging experience for your users.
## Configuring ranks
Navigate to the **Events** section in the Claimr admin panel and select the **Ranks** tab.
Click the **Create Rank** button to add a new rank.
* **Name**: Provide a clear and concise name for the rank (e.g., "Bronze," "Silver," "Gold").
* **Image**: Upload an image or icon that represents the rank.
* **Rank points**: Specify the number of points required to achieve this rank.
* **Points**: (Optional) Award bonus points to the user upon achieving this rank.
* **Rewards**: (Optional) Add additional rewards associated with this rank (e.g., NFTs, gift codes).
Click the **Create** button to save your new rank.
## Presenting ranks to users
**Rank display**: The user's current rank is clearly displayed within their profile or progress section. This typically includes the rank name or icon and the user's current points progress.
**Progress bar**: A progress bar visually represents the user's progress towards the next rank, showing how many points they need to earn to reach the next level.
## How users interact with ranks
Users earn points by completing tasks and quests within your campaign. As they accumulate points, their rank automatically updates. Users can see their current rank and progress towards the next rank in their profile or progress section.
# Tournaments
Source: https://docs.claimr.io/extra/tournaments
Configure tournament requirements and point types, manage tournament status, and review tournament analytics and the user-facing leaderboard tab.
## What are tournaments?
Tournaments are temporary events that you create and manage from the admin panel. Each tournament runs as a separate leaderboard session, independent of the standard leaderboard. This allows you to track user activity within a defined time frame. Only one tournament can be active at a time. All tournaments can be reviewed in the **Analytics** section.
## Configuration steps
In the header menu, go to **Extra** and select **Tournaments**. Click **+ Add Tournament**. This opens the tournament settings window.
Configure the following fields:
* **Name**: enter the tournament name.
* **Required logins**: select the connected platforms that users must have to be eligible for the tournament leaderboard.
* **Required quests**: select the quests that users must complete to qualify.
* **Required tasks**: select the individual tasks that users must complete. Tasks can be linked to quests or used independently.
* **Points type**: if your campaign has multiple point types configured in Points settings (e.g., XP plus additional customizable points), select which point type will be used to calculate the tournament leaderboard.
When all settings are configured, click **Create**. The tournament will appear in the list of tournaments.
Manage the tournament using the available actions:
* Start - activate the tournament. A dedicated leaderboard will be created.
* End - finish the tournament. The leaderboard is closed and stored as historical data.
* Edit - change the tournament name.
* Delete - remove the tournament.
## Completion logic
* Only one tournament can run at the same time.
* Created tournaments remain in status created until started.
* When started, the status changes to started and all user activity contributes to the tournament leaderboard.
* When ended, the status changes to ended and the final leaderboard is stored for analytics.
Once a tournament is started, you can access its analytics directly from the tournament card by clicking the Analytics icon in the upper corner next to the Edit button.
## Analytics
1. You can access tournament analytics in two ways:
* In the header menu, go to Analytics and select Tournaments.
* From the Tournaments view, click the analytics icon in the upper corner of a specific tournament card.
2. The overview table will open showing all tournaments with their name and status. Clicking a tournament opens its leaderboard.
3. The leaderboard is displayed as a dynamic table with the following columns:
* Name - username or identifier.
* Points - total points earned.
* Connected accounts - Twitter, wallet, Discord, or other linked accounts (columns appear dynamically depending on available data).
4. You can sort the table, copy wallet addresses, and export the leaderboard to a .csv file.
5. Clicking a user opens detailed information about that participant.
## User view
* In the app leaderboard, a Tournament tab appears next to the Main leaderboard when a tournament is active.
* Users can switch between the main leaderboard and the tournament leaderboard to see rankings.
* Tournament leaderboards have the same structure and options as the main leaderboard.
# Blocks
Source: https://docs.claimr.io/forms/blocks
Explore every form block type - short answer, long answer, email, link, choice, quiz, rich text, video, and address - and their settings.
Form blocks are the individual elements that make up a form in Claimr. You can move blocks from one page to another within the form.
## Add blocks
Click the **+ Block** button.
A pop-up window will appear where you can select the block type.
Choose the block type that best suits the information you want to collect.
Click **Add Block** to add the block to the page.
Customize the labels, placeholders, and validation rules for the block.
Each page in a form must have at least one block.
## Blocks common structure
* **Block label:** A small label that identifies the block type (e.g., "Short answer," "Email"). This is primarily for internal organization and is not always visible to the user.
* **Field label:** The label displayed to the user, indicating what information should be entered in the block (e.g., "Your name," "Email address").
* **Input field:** The actual input field where the user enters their response.
* **Settings icon:** A gear icon that opens the block's settings menu.
Customize the labels, placeholders, and settings for each block.
## Block settings
Most blocks share these common settings:
**Optional toggle:** Make the block optional or required.
**Error message:** Customize the error message displayed for invalid input.
To customize a block:
Click the gear icon to the left of the block to open the block settings menu.
Adjust the settings as needed.
Click **Apply** to save your changes or **Delete block** to remove the block.
## Block types
Each block serves a specific purpose in collecting user information or creating interactive elements within your forms.
### Short answer
Collect short text answers from users. Ideal for fields like names, addresses, or social media handles.
**Regular expression settings:** Define a pattern to validate user input conforms to specific rules or formats.
**Examples**
Include a specific emoji: If you want to include a specific emoji (e.g., ✨) in the user's name, you could use a regular expression like `.*✨.*` to allow for any characters before or after the emoji.
Start with a specific word or phrase: If you want to ensure the user's name starts with a specific word or phrase, you could use a regular expression like `^YourKeyword` to match any string that begins with "YourKeyword".
**Resources**
* **Regular expression builder:** [regex101.com](https://regex101.com/)
* **AI assistants**
### Long answer
Collect longer text answers or paragraphs from users. Perfect for gathering feedback, comments, or detailed explanations. This block has common settings with an optional toggle and customizable error message text.
### Email
Collect email addresses from users.
### Link
Collect website links from users.
### Choice
Allow users to select from a list of options. This is great for creating multiple choice questions or offering a set of predefined answers.
**Choice settings**
* **Shuffle:** Randomize the order of choices to prevent bias.
* **Allow multiple choices:** Enable users to select more than one option.
* **Optional toggle:** Make the block optional or required.
* **Use "Other" answer:** Include an "Other" option for users to provide their own answer if none of the predefined choices are suitable.
**Using scores**
* **Converting score to XP:** You can convert the user's quiz score into XP (experience points) that can be used in your Claimr campaign. To do this, enable the "Score to XP" option when configuring the Form task within your quest. To find out more information, visit [Form tasks](/tasks/form-tasks).
* **Determining the correct answer:** The choice with the highest assigned score is considered the correct answer.
* **Minimum score:** You can also set a minimum score that users must achieve on the quiz to complete the Form task.
### Quiz
Use this block to create interactive quizzes within your forms. This allows you to engage users, test their knowledge, or gather information in a fun and interactive way.
#### Quiz structure
**Question:** Clearly state the quiz question.
**Answer Choices:** Provide a list of possible answers for the user to choose from. Only one answer can be marked as correct.
**Score:** Assign a score to each answer choice. The choice with the highest score is considered the correct answer.
**Explanation (optional):** Add a reason for each answer choice. This explanation will be displayed to the user after they answer the question, regardless of whether their answer is correct or not.
To find out more, read our [Quizzes](/forms/quizzes) article.
### Rich text
Add a heading with rich text formatting to your form. This helps break up long forms and improve readability. Use the built-in editor to format the heading text (e.g., change font size, color, or add bolding). For more details on descriptions and tags, visit our [Descriptions: creation, usage, tags](/descriptions-creation-usage-tags) article.
### Video
Embed a video into your form to provide visual instructions or entertainment. Enter the URL of the video you want to embed.
### Address
Collect users' wallet addresses. This is useful for campaigns involving cryptocurrency or blockchain interactions.
By utilizing these diverse block types and their customizable settings, you can create forms that are not only visually appealing but also highly effective in gathering valuable user information and enhancing the overall campaign experience.
# Create forms
Source: https://docs.claimr.io/forms/create-forms
Access the forms section, create a new form, and learn how the forms table lets you sort and manage what you've built.
Log in to your Claimr account and go to the **Forms** tab in the Claimr admin panel.
Click the **Create form** button to create a new form. You'll be redirected to the form creation page, where you can name your form and add content.
Once you've created a form, you'll see a table listing all your forms. This table includes:
* **Form ID:** A unique identifier for each form.
* **Name:** The name you assigned to the form.
* **Pages:** The number of pages in the form (this feature is currently deprecated).
## Table features include
* **Sorting:** You can sort the table by form name.
* **Deleting a form:** Select the checkbox next to the form you want to delete and click the **Delete** button.
See the following articles to learn more about configuring form settings, pages, and blocks.
# Form settings
Source: https://docs.claimr.io/forms/form-settings
Rename your form, configure page pagination and legacy quiz mode, and set a minimum height to keep multi-page forms visually consistent.
Customize the appearance and behavior of your forms with Claimr.
## General
* **Form name:** This field displays the current name of the form. You can edit the form name directly within this field.
* **Quiz mode (Deprecated):** This toggle enables quiz functionality within forms. However, this method is outdated and no longer recommended. To create quizzes, use the dedicated Quizzes feature, which provides a significantly improved experience. To find out more, read our [Quizzes](/forms/quizzes) article.
* **Enable page pagination:** This toggle enables page numbering within the form. When enabled, users will see the current page number, allowing them to track their progress through multi-page forms or quizzes.
## Customization
* **Form min-height:** This field specifies the minimum height of the form in pixels. This helps maintain a consistent visual appearance when your form has multiple pages with varying content. By setting a minimum height, you prevent the form from shrinking or expanding drastically as users navigate between pages.
If you have a multi-page form with some pages having a lot of content and others having very little, setting a form min-height will prevent the form's overall height from jumping around as users navigate. This creates a smoother and more visually consistent experience.
# Forms
Source: https://docs.claimr.io/forms/overview
See what you can do with Claimr forms and find your way into creating forms, form settings, pages, blocks, and quizzes.
Forms are a versatile tool for collecting data from your users. Use forms to gather contact information, feedback, preferences, or any other data for your campaign goals.
**Use forms to**
* Collect information to understand your audience better, personalize their experience, and improve your campaigns.
* Make your campaigns more interactive by incorporating forms that allow users to provide feedback, express preferences, or participate in surveys and quizzes.
* Capture leads and build your email list or contact database.
* Gather information upfront to personalize the user journey and provide more relevant content and rewards.
## Understanding forms structure
Forms in Claimr have a hierarchical structure:
**Forms:** The overall container for collecting user information.
**Pages:** Forms can have multiple pages, allowing you to organize the information you're gathering into logical sections.
**Blocks:** Each page consists of different blocks, which are the individual elements that make up the form (e.g., text fields, email fields, dropdown menus, checkboxes).
To learn more about managing existing forms, editing forms, configuring form settings, and utilizing different block types, see the following articles.
Create your first form and start collecting user data.
Customize the appearance and behavior of your forms.
Organize your form's content into logical pages.
Explore the block types available to collect user information.
Build interactive quizzes within your forms.
# Pages
Source: https://docs.claimr.io/forms/pages
Add pages to your form and customize page settings to create visually appealing and user-friendly forms that match your brand.
Once you've created a form, start adding pages and blocks to build its structure and collect the desired information.
## Add page
This opens a modal window where you can select the type of block you want to add to the new page.
Choose the block type that best suits the information you want to collect (e.g., Short Answer, Long Answer, Email, Choice, Quiz) and configure settings. For more information, visit [Blocks](/forms/blocks).
Pages cannot be empty. Make sure to add at least one block to each page.
You can rearrange the order of pages and blocks within the form by dragging and dropping them.
## Page settings
Each page has its own settings that you can customize to match your branding and enhance the user experience. To access the page settings, click the settings button (gear icon) next to the page name in the form editor.
### General page settings
**Page title:** Enter a descriptive title for the page. This title will be displayed to users as they navigate through the form.
**Page title color:** Use the color picker to choose a custom color for the page title.
### Buttons settings
**Back button:** Customize the text displayed on the "Back" button. This button allows users to navigate to the previous page in the form.
**Submit button:** Customize the text displayed on the "Submit" button. This button is used to submit the form on the last page.
### Customization options
**Background image:** Upload an image to use as the background for the page.
**Edit:** Click this button to edit or replace the existing background image.
**Background color:** Choose a background color for the page using the color picker.
**Text color:** Select the color of the text on the page.
**Button text color:** Choose the color of the text on the buttons.
**Button background color:** Select the background color for the buttons.
**Disabled button text color:** Choose the color of the text on disabled buttons.
**Disabled button background color:** Select the background color for disabled buttons.
### Page actions
**Delete:** Click this button to delete the current page.
**Cancel:** Click this button to cancel any changes and return to the page settings.
**Update:** Click this button to save your changes to the page settings.
# Quizzes
Source: https://docs.claimr.io/forms/quizzes
Configure the Quiz block's questions, answer choices, scores, and explanations to engage users and test their knowledge.
## What are quizzes?
The Quiz block in Claimr forms allows you to create interactive quizzes to engage users, test their knowledge, and gather information in a structured way. Quizzes provide a more engaging alternative to traditional surveys and can be used for various purposes, including:
* **Knowledge checks:** Assess user understanding of a topic.
* **Lead qualification:** Gather information about potential customers through interactive questions.
* **Interactive tutorials:** Guide users through a learning process with immediate feedback.
* **Fun and engagement:** Create lighthearted quizzes to entertain your audience.
* **Contests and giveaways:** Use quizzes as entry mechanisms for contests.
Quizzes are created using a dedicated [block](/forms/blocks) within the Claimr form builder.
## Quiz block settings
Within the form editor, add a new **Quiz block** to the desired page. Remember, you can only have one Quiz block per page.
### Configure the Quiz block
Enter the text of your quiz question in this field.
Add multiple answer choices directly within the Quiz block. Each answer choice has the following fields:
* **Answer text:** Enter the text of the answer choice.
* **Score:** Assign a numerical score to this specific answer choice. This can be:
* **Positive:** Award points for a correct answer.
* **Zero:** No points are awarded or deducted.
* **Negative:** Deduct points for an incorrect answer.
* **Explanation (Optional):** Provide an explanation for this specific answer choice.
**If an explanation is provided:** The answer choice is treated as part of the quiz, and the score will be applied. The explanation will be shown to the user after they answer the question, providing feedback.
**If no explanation is provided:** The answer choice is treated as part of the survey.
* **+ Block:** Use this button to add additional answer choices to your question.
* **Shuffle:** Use this setting in the Form to make the answers appear in random order.
# Use Claimr docs with AI coding agents
Source: https://docs.claimr.io/frameworks/ai-coding-agents
Give Claude Code, OpenAI Codex, Cursor, GitHub Copilot, and other AI coding agents the rules and references they need to integrate Claimr into your app correctly.
AI coding agents can integrate Claimr for you, as long as they know how the widget loader behaves. Without that context, agents tend to make the same mistakes: injecting the script from the component that shows the widget, using the wrong script ID, or calling `destroy()` on unmount. This page gives you three ways to prevent that.
1. [Add a rules file](#add-a-claimr-rules-file-to-your-project) to your repository so the agent follows the integration rules on every task.
2. [Point the agent at the Markdown docs](#point-the-agent-at-the-docs) so it can read the full guides.
3. [Connect Claimr MCP](#configure-campaigns-with-claimr-mcp) if you also want the agent to create or edit campaigns.
## Add a Claimr rules file to your project
Copy the block below into the instructions file your agent reads, fill in the **Project values** section, and commit it.
| Agent | File |
| - | - |
| Claude Code | `CLAUDE.md` in the project root. If you already keep rules in `AGENTS.md`, add the line `@AGENTS.md` to `CLAUDE.md` instead. |
| OpenAI Codex | `AGENTS.md` in the project root. |
| Cursor | `AGENTS.md`, or a rule file such as `.cursor/rules/claimr.mdc`. |
| GitHub Copilot | `.github/copilot-instructions.md`, or `AGENTS.md`. |
| Other agents | `AGENTS.md` is read by most coding agents. |
```markdown AGENTS.md expandable theme={"dark"}
## Claimr widget integration
Claimr is embedded with one script, `https://widgets.claimr.io/claimr.min.js`. The script renders the
campaign in an iframe inside a container element and exposes an SDK at `window.claimr`.
There is no npm package.
### Project values
- Organization ID:
- Campaign ID:
- Container ID: claimr-widget
- Sign-in model:
- Framework:
### Reference docs (Markdown, read before writing code)
- Rules and shared loader module: https://docs.claimr.io/frameworks/overview.md
- React: https://docs.claimr.io/frameworks/react.md
- Next.js: https://docs.claimr.io/frameworks/nextjs.md
- Vue and Nuxt: https://docs.claimr.io/frameworks/vue-and-nuxt.md
- SDK methods and callbacks: https://docs.claimr.io/sdk-guide.md
- Script attributes: https://docs.claimr.io/widget/widget-attributes.md
- User tokens: https://docs.claimr.io/api-guide/user-token.md
- Full index: https://docs.claimr.io/llms.txt
### Rules
1. Use the shared loader module (`lib/claimr.ts`) from the overview page. Do not write a new loader.
2. Load the script exactly once per page session, from the app root: root provider (React), root layout
(Next.js App Router), `_app` (Pages Router), app plugin (Vue), or `plugins/*.client.ts` (Nuxt).
Never load it from the component that displays the widget.
3. The script element must have `id="claimr-script"`. There must be only one on the page.
4. Configure the widget with `data-*` attributes on the script: `data-organization`, `data-campaign`,
`data-container`, `data-autoresize="true"`. They are read once at load. For runtime changes use SDK
methods (`set_language`, `set_theme`, `set_user_token`), or `reloadClaimr(config)` to switch campaigns.
5. Show the widget by rendering an empty element whose `id` equals `data-container`. The loader attaches
the iframe when that element appears and removes it when it disappears. Never render children inside
it and never bind an inline `height` to it.
6. Never call `window.claimr.destroy()` when a component unmounts.
7. Read `window.claimr` at call time. Never store it in state, context, or a module variable.
8. Assign SDK callbacks (`on_user_info`, `on_campaign_info`, `on_logout`, `on_wallet_request`, and so on)
in exactly one place, the `setup` function passed to `loadClaimr`, and share the data through app state.
9. `set_language`, `set_theme`, `complete_task`, `select_wallet`, `open_profile_popup` and `platform_login`
need a loaded widget: wrap them in `withWidget(...)`. `set_user_token`, `connect_wallet`, `open_quest`
and `login` are safe to call earlier.
10. Run Claimr code in the browser only. Next.js: `'use client'` and `useEffect`. Nuxt: `.client` plugin
and `onNuxtReady`. Rendering the empty container on the server is fine.
11. The Claimr API token is a server secret. Never expose it with `VITE_`, `NEXT_PUBLIC_`, or
`NUXT_PUBLIC_`. Generate user tokens on the server:
`GET https://prod.claimr.io/api/v1/token?account=&platform=`
with `Authorization: Bearer `. The response is `{ "success": true, "data": { "token": "..." } }`.
Pass the token to the browser, then to `set_user_token`. Call `window.claimr.logout()` on sign-out.
12. When the widget component unmounts, reset `document.body.style.overflow = ''`.
13. To disable autoresize, omit `data-autoresize`. The value `"false"` still enables it.
14. Only use SDK methods, callbacks, and attributes listed in the SDK guide and widget attributes pages.
If something is not documented, ask instead of guessing.
### Definition of done
- The widget renders on the target page and `window.claimr.is_claimr_ready` is `true`.
- Navigating away and back re-attaches the widget, and `document.querySelectorAll('#claimr-script').length === 1`.
- No server-side rendering errors and no hydration warnings.
- The API token does not appear anywhere in the client bundle.
```
## Point the agent at the docs
Every page on this site is also available as plain Markdown, which agents read more reliably than HTML:
| Resource | URL |
| - | - |
| Index of all pages | `https://docs.claimr.io/llms.txt` |
| All pages in one file | `https://docs.claimr.io/llms-full.txt` |
| Any single page | Add `.md` to the page URL, for example `https://docs.claimr.io/frameworks/react.md` |
Agents with web access, such as Claude Code, can fetch these URLs on their own when the rules file lists them. If your agent runs without network access, open the page you need here, use the page menu at the top to copy it as Markdown, and paste it into the conversation.
## Example prompts
Use prompts like these after adding the rules file. Name the framework, the page, and the sign-in model so the agent does not have to guess.
```text theme={"dark"}
Add the Claimr widget to the /quests page of this Next.js App Router app.
Follow the Claimr rules in AGENTS.md and https://docs.claimr.io/frameworks/nextjs.md.
Use NEXT_PUBLIC_CLAIMR_ORGANIZATION and NEXT_PUBLIC_CLAIMR_CAMPAIGN for the IDs.
Users sign in inside the widget, so skip user tokens.
When you are done, list the files you changed and how to verify the integration.
```
```text theme={"dark"}
Our users already sign in with our own auth. Connect them to Claimr with user tokens:
add a server route that generates the token with CLAIMR_API_TOKEN, pass it to the
Claimr provider, and call logout on sign-out. Follow the "Sign users in with your own
accounts" section of https://docs.claimr.io/frameworks/react.md.
Never expose CLAIMR_API_TOKEN to the browser.
```
```text theme={"dark"}
When a user finishes the onboarding checklist in src/features/onboarding, mark the
Claimr front-end task "" as complete using completeTask from useClaimr.
The widget may not be mounted at that moment, so rely on withWidget.
```
```text theme={"dark"}
This dApp uses wagmi and RainbowKit. Make the Claimr widget use the connected wallet
instead of asking the user to connect again: set platform "dapp" and implement
on_wallet_request as in https://docs.claimr.io/frameworks/react.md#connect-the-users-wallet-dapps.
```
```text theme={"dark"}
Review our Claimr integration against the rules in AGENTS.md. For each rule, say whether
the code follows it and point to the file and line. Fix any violation you find.
```
## Configure campaigns with Claimr MCP
The rules file teaches an agent how to **embed** a campaign in your code. To let the same agent **build or edit** the campaign itself (quests, tasks, rewards, widget layout, translations), connect it to Claimr MCP.
```bash theme={"dark"}
claude mcp add --transport http claimr https://prod.claimr.io/mcp
```
For Cursor, VS Code, and other clients, see [Connect an AI assistant](/mcp/connect-an-ai-assistant). With both in place, a single request such as "create a three-quest onboarding campaign and add it to the /quests page" can cover the campaign setup and the code.
# Integrate Claimr into a Next.js app
Source: https://docs.claimr.io/frameworks/nextjs
Add the Claimr widget to a Next.js app with the App Router or Pages Router, keep it working across client-side navigation, and generate user tokens on the server.
This guide adds Claimr to a Next.js 13.4+ app. It covers the App Router first, then the [Pages Router](#pages-router). The widget always runs in the browser; Next.js server features are only used to keep your API token secret while generating user tokens.
| File | Runs on | Purpose |
| - | - | - |
| `lib/claimr.ts` | Browser | Framework-agnostic loader, readiness helpers, and TypeScript types. |
| `claimr/ClaimrProvider.tsx` | Browser (`'use client'`) | Loads the script once from the root layout and shares Claimr state through context. |
| `claimr/ClaimrWidget.tsx` | Browser (`'use client'`) | Renders the container the widget attaches to. |
| `claimr/useClaimr.ts` | Browser | Hook for Claimr state and SDK methods. |
| `lib/claimr-server.ts` | Server only | Generates user tokens with your secret API token. |
| `app/api/claimr/token/route.ts` | Server | Returns a user token to the signed-in user. Optional. |
Paths below assume the `@/` import alias points at your source root, which is the `create-next-app` default.
Read [How the loader works](/frameworks/overview#how-the-loader-works) for the reasoning behind this layout. In short: the script loads once in the root layout, which persists across client-side navigation, and the widget attaches to whichever page currently renders the container.
## Set up the integration (App Router)
```bash .env.local theme={"dark"}
# Public: inlined into the browser bundle
NEXT_PUBLIC_CLAIMR_ORGANIZATION=your-organization-id
NEXT_PUBLIC_CLAIMR_CAMPAIGN=your-campaign-id
# Server only: never prefix these with NEXT_PUBLIC_
CLAIMR_API_TOKEN=your-secret-api-token
CLAIMR_PLATFORM=your-platform-name
```
You only need `CLAIMR_API_TOKEN` and `CLAIMR_PLATFORM` if your users sign in through your app. `CLAIMR_PLATFORM` is a short name for your platform. It cannot be `claimr`.
Create `lib/claimr.ts` with the contents of [the shared loader module](/frameworks/overview#the-shared-loader-module). It guards every `window` access, so importing it from a client component is safe during server rendering.
```tsx claimr/ClaimrProvider.tsx expandable theme={"dark"}
'use client';
import { createContext, ReactNode, useEffect, useMemo, useState } from 'react';
import { ClaimrCampaignInfo, ClaimrUser, getClaimr, loadClaimr } from '@/lib/claimr';
export const CLAIMR_CONTAINER_ID = 'claimr-widget';
export interface ClaimrState {
loaded: boolean;
error: Error | null;
user: ClaimrUser | null;
campaign: ClaimrCampaignInfo | null;
}
export const ClaimrContext = createContext(null);
interface Props {
children: ReactNode;
/** User token generated on the 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(null);
const [user, setUser] = useState(null);
const [campaign, setCampaign] = useState(null);
useEffect(() => {
// Effects only run in the browser, so window is available here.
loadClaimr(
{
organization: process.env.NEXT_PUBLIC_CLAIMR_ORGANIZATION!,
campaign: process.env.NEXT_PUBLIC_CLAIMR_CAMPAIGN!,
container: CLAIMR_CONTAINER_ID,
autoresize: true,
language,
userToken,
},
(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 effect below.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
useEffect(() => {
if (loaded && userToken) getClaimr()?.set_user_token(userToken);
}, [loaded, userToken]);
const value = useMemo(() => ({ loaded, error, user, campaign }), [loaded, error, user, campaign]);
return {children};
}
```
```tsx claimr/ClaimrWidget.tsx theme={"dark"}
'use client';
import { useEffect } from 'react';
import { CLAIMR_CONTAINER_ID } from './ClaimrProvider';
export function ClaimrWidget({ className }: { className?: string }) {
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 ;
}
```
The empty `
` is rendered on the server too. That is intended: the script loads after hydration, so the loader adds its iframe to a node React has already hydrated, and there is no hydration mismatch.
```ts claimr/useClaimr.ts theme={"dark"}
'use client';
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 ');
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 };
}
```
The root layout is a Server Component. It can render the client provider directly.
```tsx app/layout.tsx theme={"dark"}
import type { ReactNode } from 'react';
import { ClaimrProvider } from '@/claimr/ClaimrProvider';
export default function RootLayout({ children }: { children: ReactNode }) {
return (
{children}
);
}
```
Put the provider in the **root** layout, not in a nested layout or a page. The root layout never unmounts during client-side navigation, so the script loads exactly once.
Pages stay Server Components. Only the widget itself is a client component.
```tsx app/quests/page.tsx theme={"dark"}
import { ClaimrWidget } from '@/claimr/ClaimrWidget';
export default function QuestsPage() {
return (
Quests
);
}
```
When the user navigates with `` to a page without `ClaimrWidget`, the loader detaches the widget. When they come back, it attaches it again.
Prefer `next/script`? You can load the script with `` in the root layout instead of `loadClaimr`. Keep the ID exactly `claimr-script`, keep it in the root layout only, and assign callbacks in `onLoad`. The rest of this guide works the same way.
## Use the SDK from components
Any client component inside the provider can call SDK methods through the hook:
```tsx components/OpenQuestButton.tsx theme={"dark"}
'use client';
import { useClaimr } from '@/claimr/useClaimr';
export function OpenQuestButton({ questId }: { questId: string }) {
const { openQuest, user, login } = useClaimr();
return user ? (
) : (
);
}
```
`openQuest` works on pages without the widget too: the quest is remembered and opens when the user reaches a page that renders `ClaimrWidget`. Methods such as `completeTask` and `setLanguage` wait for the widget internally.
## Sign users in with your own accounts
If your users already sign in to your app, generate a Claimr user token on the server and pass it to the provider.
```ts lib/claimr-server.ts theme={"dark"}
import 'server-only';
export async function getClaimrUserToken(account: string, name?: string): Promise {
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!);
if (name) url.searchParams.set('name', name);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.CLAIMR_API_TOKEN}` },
cache: 'no-store',
});
const body = await response.json();
if (!response.ok || !body.success) throw new Error('Claimr token request failed');
return body.data.token as string;
}
```
The `server-only` import makes the build fail if a client component ever imports this file. Install it with `npm install server-only`.
```tsx app/layout.tsx theme={"dark"}
import type { ReactNode } from 'react';
import { ClaimrProvider } from '@/claimr/ClaimrProvider';
import { getClaimrUserToken } from '@/lib/claimr-server';
import { auth } from '@/auth'; // your auth library, for example Auth.js
export default async function RootLayout({ children }: { children: ReactNode }) {
const session = await auth();
const claimrToken = session?.user?.id
? await getClaimrUserToken(session.user.id, session.user.name ?? undefined)
: undefined;
return (
{children}
);
}
```
Reading the session in the root layout makes every route dynamic, and this example calls the Claimr API on each request. The token never expires, so store it with your user record after the first request and read it from there.
If you want to keep pages static, or users sign in without a full page load, expose the token through a route handler and fetch it from the client.
```ts app/api/claimr/token/route.ts theme={"dark"}
import { NextResponse } from 'next/server';
import { getClaimrUserToken } from '@/lib/claimr-server';
import { auth } from '@/auth';
export async function GET() {
const session = await auth();
if (!session?.user?.id) return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
const token = await getClaimrUserToken(session.user.id, session.user.name ?? undefined);
return NextResponse.json({ token });
}
```
```tsx claimr/ClaimrAuthProvider.tsx theme={"dark"}
'use client';
import { ReactNode, useEffect, useState } from 'react';
import { useSession } from 'next-auth/react'; // or your auth library's client hook
import { ClaimrProvider } from './ClaimrProvider';
export function ClaimrAuthProvider({ children }: { children: ReactNode }) {
const { status } = useSession();
const [token, setToken] = useState();
useEffect(() => {
if (status !== 'authenticated') return setToken(undefined);
fetch('/api/claimr/token')
.then((r) => r.json())
.then((body) => setToken(body.token));
}, [status]);
return {children};
}
```
Use `ClaimrAuthProvider` in the root layout in place of `ClaimrProvider`.
```ts theme={"dark"}
'use client';
import { signOut } from 'next-auth/react';
import { getClaimr } from '@/lib/claimr';
export async function handleSignOut() {
getClaimr()?.logout();
await signOut();
}
```
Enable the matching sign-in option in the campaign under **Settings** > **Sign-in options**. See [User token](/api-guide/user-token).
## Pages Router
The same files work with the Pages Router. Drop the `'use client'` directives (they are ignored there), replace `server-only` with a plain module that you only import from API routes or `getServerSideProps`, and wire it up like this:
```tsx pages/_app.tsx theme={"dark"}
import type { AppProps } from 'next/app';
import { ClaimrProvider } from '@/claimr/ClaimrProvider';
export default function App({ Component, pageProps }: AppProps) {
return (
// claimrToken is optional: return it from getServerSideProps, or fetch it from the API route below.
);
}
```
```ts pages/api/claimr-token.ts theme={"dark"}
import type { NextApiRequest, NextApiResponse } from 'next';
import { getClaimrUserToken } from '@/lib/claimr-server';
import { getUserFromRequest } from '@/auth'; // your auth helper
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
const user = await getUserFromRequest(req);
if (!user) return res.status(401).json({ error: 'Unauthorized' });
res.json({ token: await getClaimrUserToken(user.id, user.name) });
}
```
`_app` persists across client-side navigation in the Pages Router, just as the root layout does in the App Router.
## Wallets and Telegram
* **dApp with its own wallet**: add `platform: 'dapp'` to the `loadClaimr` config and render the `ClaimrWalletBridge` component from the [React guide](/frameworks/react#connect-the-users-wallet-dapps) inside your wagmi providers. Mark it `'use client'`.
* **Telegram Mini App**: add `platform: 'telegram'` to the config. See [Telegram Mini App](/how-to/integrating-claimr-widget-into-telegram-mini-app).
## Verify the integration
1. Run `npm run dev` and open the page with `ClaimrWidget`. The campaign renders, and the terminal shows no `window is not defined` errors.
2. In the browser console, `window.claimr.is_claimr_ready` returns `true`.
3. Navigate away with a `` and back. The widget comes back, and `document.querySelectorAll('#claimr-script').length` is still `1`.
4. Run `npm run build`. The build succeeds, and `CLAIMR_API_TOKEN` does not appear in `.next/static`.
5. If you use user tokens, sign in to your app and confirm the widget shows the same user without a second sign-in.
# Integrate Claimr into a JavaScript framework
Source: https://docs.claimr.io/frameworks/overview
Learn how the Claimr widget loader behaves inside single-page apps, and the rules every React, Next.js, Vue, or Nuxt integration must follow.
The Claimr widget works in any JavaScript framework. There is no npm package to install: you load one script, `claimr.min.js`, and it renders the widget inside an element you choose. This page explains how that script behaves inside a single-page app (SPA), and lists the rules that keep an integration stable across route changes, re-renders, and server-side rendering.
Read this page first, then follow the guide for your framework:
Vite, Create React App, React Router.
App Router and Pages Router.
Vue 3 with Vite, and Nuxt 3 or 4.
Building with an AI coding agent such as Claude Code, Codex, or Cursor? See [Use Claimr docs with AI coding agents](/frameworks/ai-coding-agents) for a ready-made rules file you can drop into your project.
## Before you start
Collect these values from the Claimr admin panel. Open your campaign, click **Publish**, then click **Get embed code**.
| Value | Where it goes | Secret? |
| - | - | - |
| Organization ID | `data-organization` | No. Safe to ship to the browser. |
| Campaign ID | `data-campaign` | No. Safe to ship to the browser. |
| Container ID | `data-container`. Any element ID you choose, for example `claimr-widget`. | No |
| API token | `Authorization` header when you [generate user tokens](/api-guide/user-token) on your server. Only needed if your users sign in through your app. | **Yes.** Never send it to the browser. |
## How the loader works
When `claimr.min.js` runs, it does the following:
1. Finds the script element with `id="claimr-script"` and reads every `data-*` attribute from it. The ID is fixed: the loader looks it up by that exact name.
2. Creates the SDK object at `window.claimr` and posts a `claimr::ready` message to the page window.
3. Looks for the element whose ID matches `data-container`. If it exists, the loader appends the widget `