POST AddAction

{baseurl}/api/v1/Integration/AddAction

Overview

The AddUserAction endpoint allows users to submit actions that can be tied to various triggers within the gamification system. The service submits a user action to the system. The system evaluates the action against configured triggers and updates the user's progress on related challenges.

The User Actions API in the gamification system is designed to track and process various user actions that contribute to triggering milestones and rewards. The system can integrate user actions in two primary ways: Direct API Calls and Kafka Queue Integration.

Direct API Calls

This method involves directly sending user actions to the API as they occur. The API will collect these actions and store them temporarily, assessing them against predefined triggers in the system.

Process:

• Collecting Actions: Each time a user performs an action (e.g., earning points), you send this action to the API.

• Matching Triggers: The API looks for challenges associated with the specific trigger that the action relates to. For instance, if the action is related to earning points, the API will identify challenges that require points accumulation.

• Assessing Milestones: If the user’s actions fulfill the criteria for a milestone (e.g., accumulating enough points), the API marks these actions as used. The user then is awarded the milestone, but it remains unclaimed until further action is taken by the user.

• Example Scenario: Imagine a user needs to accumulate 100 points to achieve a milestone. Every time the user earns points, this information is sent to the API. Once the user reaches 100 points, the API will recognize this and assign the unclaimed milestone to the user.

Special Case - Non-Sum Trigger:

• This type of trigger does not accumulate actions but instead checks for specific conditions to be met exactly (e.g., hitting a specific tier or segment).

• The user must match the exact conditions of the trigger in one go to achieve the milestone. If the conditions are met, the milestone is awarded immediately, and the user can move to the next tier.

Kafka Queue Integration

In this approach, user actions are sent as JSON objects to a Kafka queue instead of directly calling the API. This method is beneficial when dealing with large volumes of actions or when actions need to be processed in bulk.

To use the Kafka Queue Integration, a proper mapping between your object and the UserAction object should be provided, the object you produce should contain 3 main elements:

1. UserId, or any relevant and agreed field that contains the user's mobile number.

2. TriggerId, a field that defines the type of action the user has done.

3. Frequency, the amount of progress the user had on this trigger.

Those fields should exist on the object, and names must be agreed on so it can be mapped to a UserAction object.

Process:

• Sending Actions to Kafka: User actions are formatted into JSON objects and sent to a Kafka queue. These JSON objects contain the same information as the direct API call, such as user ID, trigger type, and action frequency.

• Processing by the Consumer: A Kafka consumer service listens to the queue and retrieves the JSON objects.

• Processing Actions: The consumer processes these actions similarly to the direct API method. It collects the actions, checks for eligible challenges, and awards milestones if the conditions are met.

• Example Scenario: A user action JSON object might look like this:

{
  "userId": "151631",
  "triggerId": 1,
  "value": 1000,
  "actionType": 1
}

This object is placed in the Kafka queue, where it is eventually consumed by the system, processed, and evaluated against the relevant challenges and triggers.

Key Benefits:

• Scalability: Kafka allows handling large volumes of data efficiently, making it ideal for high-traffic scenarios.

• Asynchronous Processing: Actions can be processed asynchronously, allowing for more flexible and resilient handling of user data

Use Cases Examples:

1. Use Case 1: Submitting a Sum-Based Action

   A user performs an action related to a trigger that accumulates values over time. The system will check if the accumulated value meets the threshold for any active challenges and will grant a milestone if achieved.

2. Use Case 2: Submitting a Non-Sum-Based Action (e.g., Hit Tier or Segment Triggers)

   A user performs an action that does not accumulate over time but is instead evaluated as a discrete event (e.g., reaching a certain segment). The system will check if the event qualifies for any active challenges and will grant a milestone if achieved.

---

Request

Header Parameters

Attribute	Type	Options	Description
X-ClientId	string	Required	Provided Client Id.
X-Message	string	Required	Provided encrypted message.
Accept-language	string	Optional	Selected language for response.

X-ClientId and X-Message are only required with V1 API.

Body Parameters

Parameter	Type	Options	Description
UserId	string	Required	The phone number of the user performing the action.
TriggerId	string	Required	The ID of the trigger associated with the action.
Value	decimal	Required	The value associated with the action. Default is 1.
ActionType	enum	Optional	Not used.

TriggerId Values

• Earned Points = 1

• Subscribe Vouchers Count = 2

• Redeemed Points = 3

• Redeemed Vouchers Count = 4

• Total Points Balance = 5

• Hit Tier = 6

For non-summed triggers, such as hitting a tier or segment, the system doesn't accumulate actions. Instead, when the specific trigger is met, it directly evaluates whether the challenge is achieved.

Body Sample

{
  "userId": "12365984",
  "triggerId": 1,
  "value": 100
}

Scenario: Adding a User Action in the Gamification System

when a user performs an action in the gamification system, the system carefully processes it to see if it contributes to any challenges. It validates the action, updates the user’s progress, assigns any rewards, and ensures everything is tracked correctly. The user is then informed of their progress, keeping them engaged and motivated.

Steps of Adding a User Action in the Gamification System

Step 1: User Submits an Action

A user performs an activity in the system, such as making a purchase, redeeming a coupon, or reaching a specific milestone.

Step 2: Tracking User Actions

The gamification system receives the action submitted by the user.

Step 3: System Identifies Relevant Challenges

The system has a set of challenges representing different types of triggers and milestones that can be tracked (e.g., earning a certain number of points or redeeming a voucher). The system looks at the user’s action and checks if there is any eligible challenge that has this trigger.

For example, if the action is redeeming a coupon, the system checks if there is a challenge for "Coupon Redemption."

Step 4: Validating the Action

Before proceeding, the system ensures that the action is valid. If everything checks out, the system marks the action as valid and the action is stored in the system's database.

Step 5: Checking for Challenges

Next, the system evaluates the action to see if it contributes to any active challenges the user is participating in.

The system checks if the user’s action helps them progress toward any of these challenges.

Step 6: Updating Progress

If the action is part of a challenge, the system updates the user’s progress. For example, if the challenge is to earn 100 points and the user’s action earned 10 points, the system records these points towards the challenge.

If the action completes a challenge (e.g., the user has now earned all 100 points needed), the system marks the challenge as completed.

Step 7: Rewarding the User

When a user completes a challenge, the system calculates and assigns any rewards they’ve earned. Before issuing a reward, the system checks for the challenge capping, if the user reached the limit, no rewards are issued.

Rewards can be points, vouchers, or badges. The system makes sure the user receives these rewards and updates their profile accordingly.

Step 8: Preventing Duplicate Actions

To ensure that the same action isn’t counted multiple times, the system marks the action as "used" once it’s been processed. This way, if the user performs the same action again, the system will treat it as a new, separate action.

Step 9: Updating Reward History

The system updates the user history with the won reward.

---

Response

Indicates the success or failure of the operation.

200

Success respone

{
  "message": "Process completed successfully",
  "statusCode": 1,
  "statusName": "Successfully"
}

401

Unauthorized

content-length: 0 
date: Tue, 05 Jan 2021 21:46:37 GMT 
strict-transport-security: max-age=15724800; includeSubDomains 
www-authenticate: Bearer 

Notes

• The system supports both sum-based and non-sum-based triggers.

• Actions marked as used are not counted in future evaluations to prevent duplicate milestone achievements.

• The system can handle encrypted user IDs if required by configuration.