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
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:
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:
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
- 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
- 4 Lines at once (listens on the item_id
- 5 lines with same color (listens on the item_id
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.
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.
- 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
- 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.
- 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.pngwhich 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_namein the Challenge object. In this case we selected
- Enter any string you like. This will be returned as
reward_amountin the Challenge object. In this case the user will get another type of piece which looks like an
- 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
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_idand set the condition to
AND. You can also set that to
ORas we will only provide one possible value. In the value field, enter the value
sameColorand 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:
- 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:
- 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
- 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.
Save the challenge. Congratulations, we just created our first challenge. Time to play around with the challenge in SCILL Playground Application.