Admin Panel

Understanding events

The primary driver for all Scill core modules are events. Events are a JSON data representation that you send to Scill, to notify us that something has happened and that we need to update challenge statuses, leaderboards, etc. Let’s see what events consist of in the example below:

{
  "event_name": "finish-round",
  "event_type": "single",
  "user_id": "1234",
  "meta_data": {
    "round_id": 1,
    "health": 100,
    "amount": 2
  }
}

The field event_name is one of our predefined, supported events. The event name is the representation of a user’s action; a user action like shooting a weapon, killing an enemy, finishing a race, jumping, etc. is each represented with a different event in Scill.

Tip

You can find the complete list of supported event types in our Supported Events list in this documentation.

You can send individual events using event_type value of single, where amount could be used for bulk sending. Single events add up until the challenge goal is met. Group events (group) are sent after a round/match/race or similar game mechanism, and they require additional identifiers, like session_id. Group events don’t add up, they overwrite old values.

In challenges, a challenge_goal is the target value a user must reach. This is done by sending a group event type that matches or exceeds the goal, or by sending one or more single events whose value sum matches or exceeds the goal.

Every event must have a user_id, represented by a string value.

The optional meta_data send us additional info about the event that happened - the countable number of events, user health, armor, elapsed time, and so on, depending on the event. THe most used countable meta_data property is amount, however, some events may use something else, like distance, duration, lap_position, and similar.

For example, let’s say you created a challenge of type kill-enemy, with the challenge_goal of 10, which would display to the user as “Make 10 kills”.

You can send 10 individual events, each containing a payload similar to:

{
  "event_name": "kill-enemy",
  "event_type": "single",
  "user_id": "1234",
  "meta_data": {
    "amount": 1
  }
}

You can also send these events in bulk, by saving a certain amount of events locally and sending after a certain time interval. If you were to send 2 events like the one below, the user will have completed the challenge:

{
  "event_name": "kill-enemy",
  "event_type": "single",
  "user_id": "1234",
  "meta_data": {
    "amount": 5
  }
}

You could also collect all events during the round/match and send them after the round/match is over:

{
  "event_name": "kill-enemy",
  "event_type": "group",
  "session_id": "777",
  "user_id": "1234",
  "meta_data": {
    "amount": 1
  }
}

Please note that the group event type is mostly used for challenges like “Make 10 kills in one match”. In this example, the session_id is your match ID, and changing it would reset the challenge progress until the challenge goal is met, or the challenge expires.

Tip

You can find out more details about our Supported Events list in this documentation.

Common questions

Can I send my custom payload to Scill?
Can I send bulk events?
Why don't all events use amount for specifying value?
What are the supported event types?