Assignments function similarly to quests but target a specific user rather than a broader group. They allow you to create personalized challenges or tasks for an individual user and offer rewards upon completion.

Example Use Cases

Assignments can be tailored to various scenarios, such as:

• Read our latest tutorial within 24 hours — earn 10 tokens for completing it on time.
• Spend $50 in our online store — receive an exclusive Gold Trophy for your profile.
• Enable 2FA and verify your setup — get 5 status points and unlock advanced features.

Prerequisites

Before creating an assignment, ensure you have the appropriate events and rewards configured. If your existing event structure does not capture the action you need to track (for example, a new purchase type or a specific user action), you may need to create or customize an event. Similarly, if the default rewards (tokens, trophies, perks) are not suitable, you can define custom rewards that align with your platform’s needs.

Creating an Assignment

Assignments currently exist only in the API. Within the Scrimmage dashboard, the only way to create an assignment is by sending a “Reward”, where you define raw JSON with the provided structure:

{
  "event": "string",     // required
  "eventType": "string", // required
  "title": "string",     // required
  "iconUrl": "string",
  "rewardBundle": {},
  "conditions": [],
  "acceptancePeriodInMinutes": 0,
  "completionPeriodInMinutes": 0,
  "onClickRedirect": "string"
}

Structure

When configuring an assignment, certain fields are required while others are optional:

• event (required)
  The event name (e.g., "article_read", "purchase_made").
• eventType (required)
  Typically "rewardable.event," indicating how the system should handle the event.
• title (required)
• description (optional)
• iconUrl (optional)
• rewardBundle (optional)
  An object specifying the rewards granted upon completion.
• conditions (optional)
  An array of criteria for completing the assignment. It can be empty ("conditions": []) if you only want to track the event without filtering properties.
• acceptancePeriodInMinutes (optional)
  The time the user has to accept the assignment before it expires (no limit if omitted).
• completionPeriodInMinutes (optional)
  The time the user has to complete the assignment after accepting it (no limit if omitted).
• onClickRedirect (optional)
  The property for integration with Widget Events.

Configuration

Assignments are described in JSON, allowing you to specify detailed rules, conditions, and rewards. A basic configuration might look like this:

{
  "event": "article_read",
  "eventType": "rewardable.event",
  "conditions": [
    {
      "elements": [
        {
          "path": "$.body.articleId",
          "filter": {
            "type": "string",
            "operator": "equals",
            "value": "tutorial-101"
          }
        }
      ]
    }
  ],
  "title": "Read the Tutorial",
  "iconUrl": "https://example.com/icons/book.png",
  "acceptancePeriodInMinutes": 60,
  "completionPeriodInMinutes": 1440,
  "rewardBundle": {
    "rewards": [
      {
        "type": "TOKEN",
        "templateFields": {},
        "config": {
          "amount": 10
        },
        "visibility": "visible"
      },
      {
        "type": "GOLD_TROPHY",
        "templateFields": {},
        "config": {
          "path": "$.goldTrophy",
          "operation": "ADD",
          "dataType": "integer",
          "value": 1
        },
        "visibility": "promoted"
      }
    ]
  }
}

In this example, the user must trigger an "article_read" event with a specific articleId to satisfy the condition. Upon completion, they earn 10 tokens and 1 gold trophy if they finish the assignment within 24 hours (1440 minutes) after acceptance. If no time limits or rewards are necessary, you can omit or adjust those fields accordingly.

Rewards

For more details on configuring rewards, refer to our documentation. You can customize the exact reward in the rewardBundle section of the assignment’s JSON. If no rewards are specified, the assignment simply stands as a task to be completed without extrinsic incentives.

Restrictions and Eligibility

Assignments differ from polls or quests as they are inherently designed for individual users. Therefore, global restrictions, such as user-level requirements, are not applicable. Since assignments are distributed directly to a specified user, there are no default restrictions for user eligibility.