Events are a piece of structured information that your application or application backend sends to SCILL. Those events are processed in real-time to drive challenges and battle passes that you setup in the Admin Panel and that you activate for your users. Events are also stored in the SCILL backend to drive game analytics.

An event is a simple data object and consists of * event type * meta data You should send events from your application backend/server, otherwise it's easy for everyone to send events and completing challenges by just sending events using a REST-API client or short script.

URL	api/v1/events?auth={auth}
Method	POST
Authentication	API Key or Access Token
Payload	{ "event_name": "reach-checkpoint", "event_type": "single", "session_id": "Session", "user_id": "1607084651822", "meta_data": { "checkpoint_id": "Charlie", "armor": 95, "health": 67 } }

##### Path Parameters ##### Payload Parameters

const SCILL = require("@scillgame/scill-js");

// In Backend code use your API-Key
const eventsApi = SCILL.getEventsApi("__YOUR_API_KEY__");

// In frontend code you need to generate an access token before
// See SCILL.getAuthApi for more info on that
const eventsApi = SCILLClient.getEventsApi(accessToken);

eventsApi.sendEvent({
    event_name: 'reach-checkpoint',
    event_type: 'single',
    session_id: Game.CurrentSession,
    user_id: Game.UserId,
    meta_data: {
        checkpoint_id: "Charlie",
        armor: Player.Armor,
        health: Player.Health
    }
}).then((response) => {
    console.log("Event send successfully", response);
}).catch(error => {
    console.warn("Event could not be sent", error);
});

// In Backend code, you can create instances via API-Key
var scill = new SCILLBackend("__YOUR_API_KEY__");

// In Frontend code, you should use the access token
var scill = new SCILLClient("__ACCESS_TOKEN__");

// Create Metadata object
var metaData = new EventMetaData();
metaData.checkpoint_id = "Charlie";
metaData.armor = Player.Armor;
metaData.health = Player.Health;

// Create Event payload
var payload = new EventPayload(Game.UserId, Game.CurrentSession, "reach-checkpoint", "single", metaData);

// Send the events
var response = await scill.SendEventAsync(payload);
if (response.status < 300) {
    // Event has been sent
}

{
  "status": 200,
  "message": "OK"
}

Challenges (if activated) react to incoming events in real time by the event_name set in the Challenge settings in Admin Panel.

For example, think about this simple challenge: Make 4 or more goals in a match and you set achieve-score as the event name for this challenge. If the user (or the developer automatically) activates the challenge, the challenge will “listen” to achieve-score events. Depending on the content of the event payload of achieve-score the counter of the challenge will increment in real-time.

Once the match starts, your game sends achieve-score events of type single (we’ll come to that later) and in the meta_data object you set amount: 1. This way, the counter of the challenge (and a nice looking progress bar for example) will be incremented in real-time for each incoming event. Now, let’s assume the player only made 2 goals. He did not achieve the challenge. Challenge counter is at 2 of 4. Now, the player tries again, as this is the reason to implement challenges: Increasing the stickyness of the game! Player achieves the next goal, now, if we would not prevent that, the challenge counter would advance to 3 of 4.

But this is not what we want to have! We want the challenge counter to start from scratch. To achieve that, you now send an achieve-score event of type group and set amount: 0 as the event_type. Using group events lets you reset the counter of (active) challenges to the value you like.

One more thing: Events also allow you to set a session_id. This is used to group events to sessions. A session can be anything, but in this example the session would be a match. So, for each match you would create another session id. This can be randomly generated based on time for example, or if you store matches in your database, this can also be a primary id or key of your database.

Whenever the session changes for a specific user_id and event_name the counter starts from scratch. Understanding that know might make you think why we sent that group event to reset the counter of the challenge before, as it would reset for the next match automatically. You are right, but only once the player would score a goal. In this experience the player would see challenge 2 of 4 until he scores the first goal, then it would reset to 1 of 4 after sending the event with a new session id. Depending on the game this might be what you want, sometimes it might not make any difference as the sessions you create a not matches with a lot of time in between, but perhaps in a Hack & Slay with checkpoints it does not make much difference as challenge counter changes very quickly all the time.

In a nutshell:

• Use single event types for incremental updates to the counter of (active) challenges
• Use session_id to group single events into sessions. If the session of changes for an event_name and a user_id the counter is reset automatically.
• Use group event types to set the counter of (active) challenges to the amount given in the meta_data object

Known issues and limitations

Thinking of above example: Make 4 goals in a match. You could also think of a challenge: Make 1.000 goals in a match. Those two challenges are mutally exclusive in our current system. Let’s dig into that to understand:

The first challenge, as said before requires you to send events of type achieve-score and you need to either reset the counter after each match or it will automatically be reset once you change the session_id. Now, the other challenge would require you to send 1.000 events of type achieve-score. You can do that of course if you never change the session_id you could count goals forever. For example you could set the session_id to 1 or the user_id. But having both challenges active at the same time would not be possible.

Why this limitation?

We want to build a system that encourages players to stay in the game and try one more time. We know, that it’s better to provide more granular, incremental goals rather then having that big targets. You quickly forget about them and if players don’t make much progress it’s rather demotivating then motivating. Therefore it’s better to have more short living challenges and than to have a couple of long living challenges.

The idea behind battle passes is the same: Give players many smaller things to complete and reward them afterwards to keep them motivated and to “just do that other thing before going to bed”. Having 101 of 1000 goals will not make most players stay out of bed to come closer, but winning a game with 4 goals might keep them playing.