Creating challenges

The basic concept of a challenge is pretty simple: You set a goal and ask the user to reach that goal within a certain period. Goals must be measurable with one simple integer. Every active challenge has a current state which is also an integer. A simple challenge for example is: “Invite 5 other users”. The goal here is 5, the current state will be 0 when the challenge is activated. After the user invited one other user an event is sent to SCILL. SCILL will process that event and increases the counter of the current state by 1. SCILL cloud will then notify your backend by calling a Webhook (if defined) and will notify any connected clients of this user to reflect this change in the user interface in real time.

It’s simpler to describe how to work with SCILL on a concrete example or product. For this guide, we have selected an open-source Tetris game called: Mimstris.

Quick overview

Challenges are a nice way of adding user interaction into your game by letting users pick challenges and pickup rewards once they have achieved those challenges. Personal vhallenges are defined like this:

  • Need to be unlocked and activated (not necessarily by users)
  • Have a duration (in minutes)
  • Can be repeatable - users can try over and over again, or they are a one-shot

Follow this Step-by-Step guide to add Personal Challenges to your game or application.

1Create Challenges

In the Admin Panel create an app, and API key for the app, create categories and challenges. More info on this topic can be found in the section below.

2Test in Playground

In the app list in Admin Panel we provide a Playground button next to each app. Click on that button and a new browser window will be opened with the Playground-Application. The Application settings have already been made for you and you can directly start playing around with the challenges you have created. More info on that topic in our Testing challenges section.

3Add SDK

We provide SDKs for many programming languages and platforms. Please consult the documentation on how to add the SDK to your application or game. Official SCILL SDKs.

4Add events

Below the “Send Event” button in Playground you’ll see code generated for you that you just need to Copy & Paste in your applications source code. Just select your programming language and copy the code generated by Playground to your own codebase to send the same event from your code.

5Unlock rewards

Depending on your settings, Challenges have rewards that users can claim. There are various different methods of unlocking rewards to the user, either by implementing real time notification into your client to handle unlocking in your app or game or Webhooks to unlock rewards from your backend (i.e. send a mail with a redeem code). More info in our Rewarding Users section.


Implement User Interfaces to show challenges to your users. We have built some examples for various different platforms. Check out our Github repository for example code or the Examples section of this documentation.

That’s it. You have added SCILL Personal Challenges to your game.

Defining events and challenges

Now, that we have set up the app in SCILL, we need to figure our which events we have in the game and what challenges we can create based on those events. We recommend getting started by defining obvious events and challenges for your game to get started. Once you have done that, you’ll figure our other interesting challenges which might require some other events. It’s a bit a back and forth process, but a lot of fun and as it’s an iterative process you can always start with something simple to get more complicated down the road.

SCILL events are preconfigured for you. You can find the complete list of event definitions in our Supported Events list in this documentation.

By digging through the list, we found these events that we can pretty easily define and implement for this game:

This event has a couple of properties that we can set. One of those properties is item_id. We can use that to distinguish events with the same event name. In total, we’ll use three different values for item_id.

Is used for a “standard” Tetris row
Describes a line where all pieces in the line have the same color
A block of four lines, cleaned at once

Every event has a couple of parameters that can be attached to the event. Some of them are required, others are optional. The documentation describes all those parameters in detail.

Based on those events, some challenges are obvious:

  • Complete 10 lines (listens on the item_id line)
  • 4 Lines at once (listens on the item_id block)
  • 5 lines with same color (listens on the item_id sameColor)

Of course, these are simple challenges, but especially the “5 lines with same color” challenge is completely changing the game. How many times have you played Tetris, and did you ever try to create lines with the same color? By just adding this simple challenge, the game is completely different and it’s fun to see different people figuring out different strategies to solve that problem.

Setting up challenges

In the Admin Panel, make sure the app is selected from the list and click on “Challenges” in the menu. First, we need to create a category. Challenges are organized into categories.

Adding Basic Challenges category

Adding Basic Challenges category

You can enable and disable categories. This way, you can create many challenges in advance and unlock them anytime. You could create “Christmas” challenges and unlock them at christmas or you could organize your challenges in seasons and switching them every month. If you add great rewards to some challenges, users will be forced to manage challenges in time which also drives users retention.

Let’s create our first, simple challenge. For this, choose the Challenges tab in the Personal Challenges section of the Admin Panel and click on Add Challenge.

You will be guided through 5 setup steps.

Challenge Type

Step 1: Choosing challenge type

Step 1: Choosing challenge type

1Manual Challenge

Users have to manually unlock and activate this challenge. This challenge also time ous/fails after the duration is over. A user can only lose a challenge if it expires before the user reaches the setup goal.

2Daily Challenge

The daily challenge is an automatic challenge that repeats every 24 hours. Users can get rewards if they complete the challenge before it resets. Challenges like “Make 10.000 steps per day” are a good example of usage.

3Weekly Challenge

This challenge type resets each week. Users can get rewards if they complete the challenge before it resets. Challenges like “Run 10 miles every week” are a good example of usage.


Achievements are challenges that never expire, and that never repeat once achieved. This is used for long-term goals. Challenges like “Invite 100 friends” are a good example of usage.


An advanced setup lets you cherry-pick the options you need. See image below.

Advanced challenge setup

Advanced challenge setup

Advanced Challenge Setup

This is the description/name of the challenge. This is the action plan the user must follow to achieve this challenge. Keep it short and precise.
This is the category the challenge is attached to. In this case, choose the “Basic Challenge” category created before.
Choose the event that this challenge will track. The challenge will wait for events coming in of this type and process them. You can further specify which events are processed in the Meta Data section below. We’ll come to that later. In this case we choose the destroy-item event type.
Challenge Goal Condition
This can be set to 0 or 1. If 0, then the challenge is achieved if you increment the counter greater or equal than the goal. I.e. we set the goal to 10, and the challenge requires to kill at least 10 enemies, so we set this to 0. We could also create a challenge: “Don’t get hit more than 5 times”, then we would need to set this to 1, because in this case the challenge will only be achieved if we stay below 5.
This is the goal as an integer value of the challenge. As we want to have 10 kills, we set it to 5.
Live Date
We leave this field blank, which means, we don’t set any date. You can create challenges and assign a date when they should “go live”. I.e. create a Halloween challenge and set to October 31st and this challenge will automatically pop up.
Challenge Icon
You can set any string here. In a web game, we just set it to the name of an image provided in the games asset folder. We set to h-piece.png which is an image of a tile the user wins if he achieves this challenge.
Challenge Icon HD
Same as Challenge Icon, but allows you to set a high res image, for example for some teasers or for Desktop version of your game, while you use the Challenge Icon for the mobile version with a much denser UI. We leave that out in this example.
Reward Type
You can set different types of rewards. There is no logic within SCILL for rewards, it’s up to you to unlock rewards, but using our options it’s easier to organize your data. Choose an item from the list. Within the API response or SDK this will be available as reward_type_name in the Challenge object. In this case we selected Item.
Enter any string you like. This will be returned as reward_amount in the Challenge object. In this case the user will get another type of piece which looks like an H.
Price and XP
These are integer values that you can set and use as you like. We don’t make use of them right now, so just leave them blank.
Time Management
Choose which time management you want to have for this challenge. You can choose between Manual where your user or you via script in the app need to unlock and activate the challenge manually. This allows for fine graded timing in combination with duration and life_date. The other option is Automatic. In this case SCILL backend handles the lifetype of the personal challenge. Depending on this settings, subsequent settings are different. Please see below on details on each of these settings.
Here, we choose the property item_id and set the condition to AND. You can also set that to OR as we will only provide one possible value. In the value field, enter the value sameColor and press return to add that value to the list. This challenge will only track events hat have the same value in item_id. You could provide multiple values to make challenges respond to both (AND) or any of those (OR).

Manual Time Management

These settings are availabe if have chosen manual time management:

Settings available in manual time management mode

Settings available in manual time management mode

Set the time limit for the challenge in minutes. We set it to 30 minutes in this case.
Challenges have a duration and need to be unlocked/activated. This setting defines what happens if the Challenge has been lost (timed out) or won (achieved within time constraint). If it’s set to be repeatable, it will be reset and available for another round. If it’s not repeatable this challenge will not be available for the user again. In this case we set it to be repeatable.

Automatic Time Management

If you choose automatic time management you’ll have these options:

Settings available in automatic time management mode

Settings available in automatic time management mode

Period Range
In Automatic mode, challenges are automatically activated and reset for each user. This settings defines the lifetime of the challenge. It can by day, week, month or unlimited.
Time Zone
Time management always is dependant on the location of the users. In this setting you can set your time zone.
Reset Time
The time (default is midnight) when the challenges should be reset and get activated.
Sets if the challenge should be available again once it has been reset or won (after reset time). If you set this to No, then this challenge will only be available once.

More info on the lifecycle and about manual and automatic time management for challenges can be found in the API reference documentation: Challenges API Reference.

Basic Challenge Info

Step 2: Adding basic challenge information

Step 2: Adding basic challenge information

See the field explanation above

Challenge Reward

Step 3: Choosing challenge reward

Step 3: Choosing challenge reward

See the field explanation above

Event Settings

Step 4: Choosing challenge event settings

Step 4: Choosing challenge event settings

See the field explanation above

Next Steps

Step 5: Testing and sending events

Step 5: Testing and sending events

Save the challenge. Congratulations, we just created our first challenge. Time to play around with the challenge in SCILL Playground Application.