Add custom points to users

Introduction

Add points to your users' balances in claimr. Use these methods to reward your users in claimr based on actions they complete outside the platform — for example, in your own app or product. This effectively syncs off-platform activity with your claimr reward system.

Benefits of adding points from external actions

• Expand engagement: Extend user engagement beyond the claimr platform by rewarding activity in your own application or product.

• Reward specific behaviors: Recognize and incentivize particular actions or achievements that occur outside of claimr.

• Create a holistic reward system: Build a unified reward experience that combines both in-claimr and external user activities.

You can add points to user balances in claimr through three primary mechanisms, each leveraging specific API endpoints. The method you choose depends on how you want to track and reward the external user activity.

1. Direct point management (Using API)

These API calls allow you to directly add points (POST /user/reward) or deduct points (POST /user/withdraw) from a user's balance in claimr.

You can initiate these requests from your external system to claimr, specifying the user, campaign, and the amount of points to add or remove.

POST /user/reward

• Purpose: Use this endpoint to reward your users in claimr based on actions they complete outside the platform — for example, in your own app or product. This allows you to sync off-platform activity with your claimr reward system.

• Process: This action occurs in the background. The user receives points through this API request, and these points automatically appear in claimr.

• Body (JSON Request):

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "id": "string",
  "xp": 0
}

account: The user's account identifier in your platform (e.g., email, nickname, ID).

platform: Platform identifier.

pid: Campaign ID.

id: A unique identifier for each reward given to a specific user. If this ID is not unique for a given user, the reward will be ignored.

xp: The number of points you are assigning to the user (e.g., 100 points).

• JSON Response (Success):

{
    "success": true
}

POST /user/withdraw

• Purpose: This endpoint allows you to deduct or withdraw points from your users' balances in claimr. This is useful for adjusting user points based on actions outside of claimr or for managing specific campaign mechanics.

• Process: This action occurs in the background. The specified points are deducted from the user's balance in claimr.

• Body (JSON Request):

{
  "account": "string",
  "platform": "string",
  "pid": "string",
  "id": "string",
  "xp": 0,
  "strict": true
}

account: The user's account identifier in your platform (e.g., email, nickname, ID).

platform: Platform identifier.

pid: Campaign ID.

id: A unique identifier for each withdrawal transaction given to a specific user. This ID ensures that the withdrawal is processed only once.

xp: The number of points you wish to withdraw from the user's balance (e.g., 50 points).

strict: (Meaning not explicitly provided, but included in the JSON structure).

• JSON Response (Success):

{
    "success": true
}

Monitoring points in Analytics

To view a user's detailed information:

1. Navigate to the Analytics section.

2. Select the relevant table (e.g., Activity, Referrals).

3. Find the user in the table.

4. Click on the user's row. This will open a modal window with a comprehensive overview.

5. Go to the points section within this modal. It shows many points were earned from various sources and allows you to adjust manually the user's total points if needed.

Withdrawn points are any reductions to a user's total points, such as penalties or corrections applied via the claimr API.

All information about the points for each user can be checked in our User information.

2. API tasks: stream and action value

POST /stream/value and POST /action/value methods are used when you want to reward users based on continuous value streams or specific actions that carry a quantifiable value.

You can configure these tasks by navigating to Task → API in the claimr admin panel and choosing one of the following task types.

POST /action/value

• POST /action/value supports two types of API tasks:

  • API Number value tasks: Used when you need to track an expected numerical result. For example, a user earns a reward once a specific target (like receiving 10 likes) is reached.

  • API Score tasks: Used for directly adding a score or a specific amount of points to a user's total, immediately changing their balance.

• Body (JSON Request):

  {
  "account": "user_identifier",
  "platform": "platform_identifier",
  "pid": "campaign_id",
  "cid": "quest_id",
  "aid": "action_id",
  "value": 123
  }

  • account: User identifier.

  • platform: Platform identifier.

  • pid: Campaign ID.

  • cid: Quest ID.

  • aid: Action ID.

  • value: The numeric value to set or update.

• JSON Response (Success):

  {
  "success": true
  }

POST /stream/value

• POST /stream/value specifically supports the task type API Stream Value. It accumulates numeric attributes associated with user actions (e.g., total transactions).

• Body (JSON Request):

{
    "account": "user_identifier",
    "platform": "platform_identifier",
    "stream": "attribute_stream_id", 
    "pid": "campaign_id",
    "value": 123 
}

• account: User identifier.

• platform: Platform identifier.

• stream: Attribute stream ID.

• pid: Campaign ID.

• value: The numeric value to accumulate.

• JSON Response (Success):

{
    "success": true
}

3: Events task

• POST /event is used to reward users for a wide range of specific events or occurrences that take place within your client application, identified by category and name.

• How it works: When you create a task in claimr with the type Events, claimr listens for POST /event calls from your application that match the criteria you define in the task settings. For instance, if your game registers a "dice roll" event, you can configure a task to reward users for it.

POST /event

• Purpose: This endpoint allows your application to send information to claimr about a specific event that has occurred within your client application. This helps you track and filter user actions for campaign purposes.

• Body (JSON Request):

  JSON

  {
    "account": "string",
    "platform": "string",
    "pid": "string",
    "category": "string",
    "name": "string",
    "date": "string",
    "ts": "string"
  }

  • account: A unique identifier for the user (e.g., their email, nickname, or internal user ID within your platform).

  • platform: An identifier indicating the platform where the user's action or account originates.

  • pid: The Campaign ID to which this event belongs.

  • category: A broad classification for the event (e.g., "game", "transaction"). This helps in filtering events later.

  • name: The specific name of the action or event (e.g., "level_up", "purchase_complete").

  • date: Internal information from your system that you deem relevant to include for processing this event.

  • ts: The timestamp of the event from your client's system.

• JSON Response (Success):

  JSON

  {
    "success": true
  }

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.

You configure these tasks as either:

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

• For an Events value task, claimr directly adds points based on a specific value included within the event data received via POST /event.

User identification: claimr identifies the user associated with the event using the account and platform fields in the POST /event payload. For instance, if a user logged in via Web3 (using their wallet), claimr uses their wallet address to link any incoming events to that user. This ensures that points are accurately attributed to the correct participant.

For more information about the settings, read our article Events tasks.