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.

1	Create 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.
2	Test 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.
3	Add 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.
4	Add 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.
5	Unlock 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.
6	Customize	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:

• destroy-item

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 a 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.

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:

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:

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.

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