Tasks

Task

Tasks module in YarsaPlay handles assigning both tasks and achievements to the user. This module is responsible for checking tasks and achievements for completion and updating their progress if not completed. There are multiple endpoints provided for this module, including one for claiming reward.

Each task requires a target value which needs to be achieved within the specified number of games, and is associated with only one game stat at a time. When a player’s statistics is updated, the game tasks associated with that stat are checked for completion.

A task can be divided into parent and child tasks. A parent task can be a single task or be composed of two or more child tasks. A child task cannot be composed of other child tasks.

Tasks can be assigned to the gamers by making API calls. A game task consists details of progress, completion, claimed rewards, and expiry date and time. Once a task is expired, it is removed from the task pool.

Achievements are those tasks with true isAchievement flag. All achievements fall under the Lifetime task family.

info

BaseEndpoint: /api/v1

Available Endpoints

1. Get List of Configured Tasks and Achievements for an Application

• Method & Path: GET /:applicationId/tasks
• Description: Returns all the tasks or achievements for an application.
• URL Parameters:
  • applicationId — Unique identifier of an application.
• Query Parameters:
  • isAchievement — Returns achievements when true else return tasks.
• Response Body: An array of objects, each representing a task or an achievement. Each includes:
  • id: The unique identifier of an application task or achievement.
  • name: Name of the task or achievement.
  • description: Description about what needs to be done for the task.
  • targetValue: Minimum value to be achieved for task completion.
  • numberOfGames: Total number of games for achieving the target value.
  • family: Family of a task( daily, weekly, monthly, seasonal, lifetime)
  • parentTaskId: ID of the parent task if present or null if no parent.
  • applicationStatId: ID of the statistics to which this task is associated.
  • isAchievement: Boolean representing if the task is achievement or not.
  • rewards: Array of rewards for completing the task. Each includes:
    • id: Unique identifier of an application reward.
    • inventoryItemId: Id of the inventory item received as reward.
    • quantity: Number of inventory item to be received.

cURL Command

curl --request GET \
  --url 'https://api.yarsaplay.com/api/v1/__APPLICATIONID__/tasks?isAchievement='

Response Body

{
  "applicationStatsId": "string",
  "description": "string",
  "family": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isAchievement": true,
  "name": "string",
  "numberOfGames": 1,
  "parentTaskId": "string",
  "rewards": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 1
    }
  ],
  "targetValue": 1
}

2. Assign Tasks According to Task Family to the Gamer

• Method & Path: POST /tasks/assign
• Description: Assigns the specified number tasks to the gamer selecting randomly according to the family.
• Headers:
  • Authorization — Required for authenticated access. Includes:
    • applicationId: Unique identifier of the application.
    • gamerId: Id of the gamer for assigning task.
• Request Body:
  • family: Family of the task to be assigned.
  • numberOfTasks: Actual number of tasks to be assigned. If the family is seasonal all the seasonal task present for the application is assigned.
• Response Body:
  • id: Unique identifier of game task.
  • createdAt: Data creation date.
  • task: Detail of associated task for the gamer task.
    • id: Unique identifier of application task.
    • targetValue: Minimum value to be achieved for task completion.
    • numberOfGames: Total number of games for achieving the target value.
    • family: Family of a task (daily, weekly, monthly, seasonal, or lifetime)
    • applicationId: Database ID of an application.
    • applicationStatsId: ID of the statistics to which this task is associated.
    • parentTaskId: ID of the parent task if present, or null if no parent.
    • rewards: Array of rewards for completing the task. Each includes:
      • inventoryItemId: ID of the inventory item received as rewards.
      • quantity: Number of inventory items to be received.
    • children: Array of child tasks for the application task.
      • id: Database ID of children task.
  • expiredAt: Expiry date of the game task.
  • progress: Achieved value for the task.
  • completed: Boolean representing if the task is completed or not.

cURL Command

curl --request POST \
  --url https://api.yarsaplay.com/api/v1/tasks/assign \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json'

Response Body

{
  "completed": true,
  "createdAt": "2024-06-27T10:54:12.544Z",
  "expiredAt": "2024-06-27T10:54:12.544Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "progress": 0,
  "task": {
    "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "applicationStatsId": "string",
    "children": [
      {
        "id": "string"
      }
    ],
    "family": "DAILY",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "numberOfGames": 1,
    "parentTaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rewards": [
      {
        "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "quantity": 1
      }
    ],
    "targetValue": 1
  }
}

3. Get a Single Configured Task for an Application

• Method & Path: GET /:applicationId/tasks/:taskId
• Description: Retrieves details of single application task for the ID.
• URL Parameters:
  • applicationId: Unique identifier of an application.
  • taskId: ID of the task to be retrieved.
• Response Body: Object which includes —
  • id: The unique identifier of an application task or achievement.
  • name: Name of the task or achievement.
  • description: Description about what needs to be done for the task.
  • targetValue: Minimum value to be achieved for task completion.
  • numberOfGames: Total number of games for achieving the target value.
  • family: Family of a task (daily, weekly, monthly, seasonal, or lifetime)
  • parentTaskId: ID of the parent task if present, or null if no parent
  • applicationStatId: ID of the statistics to which this task is associated.
  • isAchievement: Boolean representing if the task is achievement or not.
  • rewards: Array of rewards for completing the task. Each includes:
    • id: Unique identifier of an application reward.
    • inventoryItemId: Id of the inventory item received as reward.
    • quantity: Number of inventory item to be received.

cURL Command

curl --request GET \
  --url https://api.yarsaplay.com/api/v1/__APPLICATIONID__/tasks/__TASKID__

Response Body

{
  "applicationStatsId": "string",
  "description": "string",
  "family": "string",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "isAchievement": true,
  "name": "string",
  "numberOfGames": 1,
  "parentTaskId": "string",
  "rewards": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "quantity": 1
    }
  ],
  "targetValue": 1
}

4. Get List of All, Completed or Not Completed Gamer Tasks

• Method & Path: GET /tasks
• Description: Retrieves details of gamer tasks.
• Headers:
  • Authorization: Required for authenticated access. Includes:
    • applicationId: Unique identifier of the application.
    • gamerId: Id of the gamer for assigning task.
• Query Parameters:
  • completed: Set true to get completed task, false to get in completed gamer tasks and empty to get all gamer tasks.
• Response Body: Array of objects which includes:
  • id: Unique identifier of game task.
  • createdAt: Data creation date.
  • task: Detail of associated task for the gamer task.
    • id: Unique identifier of application task.
    • targetValue: Minimum value to be achieved for task completion.
    • numberOfGames: Total number of games for achieving the target value.
    • family: Family of a task (daily, weekly, monthly, seasonal, or lifetime)
    • applicationId: Database ID of an application.
    • applicationStatsId: ID of the statistics to which this task is associated.
    • parentTaskId: ID of the parent task if present, or null if no parent.
    • rewards: Array of rewards for completing the task. Each includes:
      • inventoryItemId: ID of the inventory item received as rewards.
      • quantity: Number of inventory items to be received.
  • expiredAt: Expiry date of the game task.
  • progress: Achieved value for the task.
  • completed: Boolean representing if the task is completed or not.
  • childTasks: Array of child gamer tasks for the above task
    • id: Unique identifier of game task.
    • createdAt: Data creation date.
    • task: Detail of associated task for the gamer task.
      • id: Unique identifier of application task.
      • targetValue: Minimum value to be achieved for task completion.
      • numberOfGames: Total number of games for achieving the target value.
      • family: Family of a task (daily, weekly, monthly, seasonal, or lifetime)
      • applicationId: Database ID of an application.
      • applicationStatsId: ID of the statistics to which this task is associated.
      • parentTaskId: ID of the parent task if present, or null if no parent.
      • rewards: Array of rewards for completing the task. Each includes:
        • inventoryItemId: ID of the inventory item received as rewards.
        • quantity: Number of inventory items to be received.
    • expiredAt: Expiry date of the game task.
    • progress: Achieved value for the task.
    • completed: Boolean representing if the task is completed or not.

cURL Command

curl --request GET \
  --url https://api.yarsaplay.com/api/v1/tasks \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response Body

{
  "childTasks": [
    {
      "completed": true,
      "createdAt": "2024-06-27T10:55:56.183Z",
      "expiredAt": "2024-06-27T10:55:56.183Z",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "progress": 0,
      "task": {
        "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "applicationStatsId": "string",
        "children": [
          {
            "id": "string"
          }
        ],
        "family": "DAILY",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "numberOfGames": 1,
        "parentTaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "rewards": [
          {
            "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "quantity": 1
          }
        ],
        "targetValue": 1
      }
    }
  ],
  "completed": true,
  "createdAt": "2024-06-27T10:55:56.183Z",
  "expiredAt": "2024-06-27T10:55:56.183Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "progress": 0,
  "task": {
    "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "applicationStatsId": "string",
    "children": [
      {
        "id": "string"
      }
    ],
    "family": "DAILY",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "numberOfGames": 1,
    "parentTaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rewards": [
      {
        "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "quantity": 1
      }
    ],
    "targetValue": 1
  }
}

5. Claim Rewards for a Task if It’s Completed

• Method & Path: POST /tasks/:taskId/claim
• Description: Assigns the rewards to the gamer inventory if the task is completed.
• Headers:
  • Authorization: Required for authenticated access. Includes:
    • gamerId: ID of the gamer for assigning task.
• URL Parameters:
  • taskId: ID of the task for claiming rewards.
• Response Body: Array of reward items. Includes:
  • inventoryItemId: ID of inventory item which will be provided as reward.
  • quantity: Number of Inventory item to be rewarded.

cURL Command

curl --request POST \
  --url https://api.yarsaplay.com/api/v1/tasks/__TASKID__/claim \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response Body

{
  "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "quantity": 1
}

6. Get All, Completed and Not Completed Achievements for a Gamer

• Method & Path: GET /achievements
• Description: Retrieves details of gamer tasks.
• Headers:
  • Authorization: Required for authenticated access. Includes:
    • applicationId: Unique identifier of the application.
    • gamerId: ID of the gamer for assigning task.
• Query Parameters:
  • completed: Set true to get completed task, false to get in completed gamer tasks and empty to get all gamer tasks.
• Response Body: Array of objects which includes:
  • id: Unique identifier of game task.
  • createdAt: Data creation date.
  • task: Detail of associated task for the gamer task.
    • id: Unique identifier of application task.
    • targetValue: Minimum value to be achieved for task completion.
    • numberOfGames: Total number of games for achieving the target value.
    • family: Family of a task (daily, weekly, monthly, seasonal, or lifetime)
    • applicationId: Database ID of an application.
    • applicationStatsId: ID of the statistics to which this task is associated.
    • parentTaskId: ID of the parent task if present, or null if no parent.
    • rewards: Array of rewards for completing the task. Each includes:
      • inventoryItemId: ID of the inventory item received as rewards.
      • quantity: Number of inventory items to be received.
  • expiredAt: Expiry date of the game task.
  • progress: Achieved value for the task.
  • completed: Boolean representing if the task is completed or not.
  • childTasks: Array of child gamer tasks for the above task
    • id: Unique identifier of game task.
    • createdAt: Data creation date.
    • task: Detail of associated task for the gamer task.
      • id: Unique identifier of application task.
      • targetValue: Minimum value to be achieved for task completion.
      • numberOfGames: Total number of games for achieving the target value.
      • family: Family of a task (daily, weekly, monthly, seasonal, or lifetime)
      • applicationId: Database ID of an application.
      • applicationStatsId: ID of the statistics to which this task is associated.
      • parentTaskId: ID of the parent task if present, or null if no parent.
      • rewards: Array of rewards for completing the task. Each includes:
        • inventoryItemId: ID of the inventory item received as rewards.
        • quantity: Number of inventory items to be received.
    • expiredAt: Expiry date of the game task.
    • progress: Achieved value for the task.
    • completed: Boolean representing if the task is completed or not.

cURL Command

curl --request GET \
  --url https://api.yarsaplay.com/api/v1/achievements \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

Response Body

{
  "childTasks": [
    {
      "completed": true,
      "createdAt": "2024-06-27T10:57:50.936Z",
      "expiredAt": "2024-06-27T10:57:50.936Z",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "progress": 0,
      "task": {
        "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "applicationStatsId": "string",
        "children": [
          {
            "id": "string"
          }
        ],
        "family": "DAILY",
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "numberOfGames": 1,
        "parentTaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "rewards": [
          {
            "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "quantity": 1
          }
        ],
        "targetValue": 1
      }
    }
  ],
  "completed": true,
  "createdAt": "2024-06-27T10:57:50.936Z",
  "expiredAt": "2024-06-27T10:57:50.936Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "progress": 0,
  "task": {
    "applicationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "applicationStatsId": "string",
    "children": [
      {
        "id": "string"
      }
    ],
    "family": "DAILY",
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "numberOfGames": 1,
    "parentTaskId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "rewards": [
      {
        "inventoryItemId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "quantity": 1
      }
    ],
    "targetValue": 1
  }
}