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.

Create an app

Create a game in the Admin Panel:

Adding a game in the Admin Panel

Adding a game in the Admin Panel

After that, select the new app from the app selection in the top bar and navigate to “API Keys” to add an API key for the new game:

Adding an api key for our new game

Adding an api key for our new 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 types in our Event Types 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.

line
Is used for a “standard” Tetris row
sameColor
Describes a line where all pieces in the line have the same color
block
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 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.

Adding the 5 Lines with same color challenge

Adding the 5 Lines with same color challenge

Name
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.
Category
This is the category the challenge is attached to. In this case, choose the “Basic Challenge” category created before.
Challenge-Type
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, than 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.
Goal
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 31th 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.
Reward
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.
Meta-Data
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

Duration
Set the time limit for the challenge in minutes. We set it to 30 minutes in this case.
Repeatable
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.
Repeatable
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.
Tip

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.

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