What are events?

Events are user actions captured and sent from your app or website to Scrimmage for tracking and analysis. They help monitor user activities such as claiming quests, receiving rewards, and obtaining perks. These events are closely linked to your business logic and are triggered by your API. By tracking events, you can gain insights into user behavior, measure the effectiveness of features and campaigns, and enhance the overall user experience based on actual user interactions.

Event Types

1. Custom Events

These events are fully customizable: you can specify the name and properties of each event. This flexibility enables you to capture the exact data you need to understand user behavior and optimize your application's features and campaigns effectively.

Read more about creating custom events

2. Scheduled Events

Scheduled events are triggered at specific times. These events can be set up to occur at predetermined intervals or times, allowing you to automate actions such as sending reminders, promotions, or updates to users.

🚧

Only 1-hour intervals are supported. For example: every hour, at 10:00 PM.

3. User Property Events

User property events are triggered when a user property is updated. These events track changes to user attributes, helping you maintain up-to-date information about your users and respond to changes in their profiles or behaviors.

4. Internal Events

Internal events are triggered by users within the loyalty program. These events are predefined and linked to specific actions triggered by the program's internal elements. Users do not have control over these events, as they are mapped to actions generated by the loyalty program itself. Examples of internal events include LEVEL_UP, QUEST_COMPLETED, PERK_ACTIVATED, and REDEEM_TRANSACTION_COMPLETED. All internal events are predetermined, and there is no option to add new ones.

Custom events

Custom events are a cornerstone of your tracking system. They allow you to define and capture specific user actions tailored to your application's needs.

Naming

When creating a custom event, the name you choose is crucial. Certain characters like '/', '%', spaces, or other special symbols and their combinations may cause issues. Ensure that your event names are clear, concise, and free of any potentially problematic characters.

Event properties

Event properties allow you to pass additional data within an event. They specify additional event conditions that must be met to receive a reward.

Naming

There are several possible variants of event properties that can be specified:

• Plain fields
• Nested fields - .
• Arrays [*]
• Arrays of objects [*]

📘

Although we support arrays and arrays of objects, we highly recommend not using them to prevent overcomplication, which could lead to errors.

Data Types

Event properties can be specified with one of six data types:

• string
• number
• boolean
• Array<string>
• Array<number>
• Array<boolean>

Optionally, you can define predetermined values, which will appear in a dropdown menu for event conditions or automatically selected as default values during test event submissions.

Conditions

Event conditions filter events based on event properties. They are used for Reward Rules, Quests, Perks, etc. Depending on the event property data type, different operations are available:

• string: one of, matches any, matches all
• number: ≥, >, =, <, ≤
• boolean: true, false
• Array: contains, contained by, overlap, not contains, not contained by, not overlap

📘

To store and compare dates, convert them to Unix timestamps (in seconds or milliseconds) and store them as numbers. This allows you to use numerical operators for date comparisons.

Event structure

The sending of the event itself can be a trigger for many actions in the system (like receiving a reward or changing a user's property), while attaching additional properties to an event can be used to add additional conditions for these triggers.

For more details on event and their usage, check the API documentation.

Required Event Properties

• userId: The ID of the user. Events will only be tracked only if the user exists.
• dataType: The type of the event, consistent with the body. If a custom event type doesn't exist, it will be automatically created.

Example of event

{
   "userId": "15",
   "dataType": "betExecuted"
}

Optional Event Properties

• eventId: The ID of the event. If not provided, it will be generated. Must be unique for every event. Events with the same ID will be ignored.
• body: The body of the event, consisting of event properties for the specified event, or it can be empty.

Example of event

{
   "userId": "15",
   "dataType": "betExecuted",
   "eventId": "test",
   "body": {
      "betType": "single",
      "odds": 5.2,
      "description": "Just a cool bet",
      "wagerAmount": 1500,
      "netProfit": 1500,
      "outcome": "win",
      "betDate": 1678933476000,
      "bets": [
         {
            "type": "spread",
            "odds": 5.2,
            "teamBetOn": "Bulls",
            "teamBetAgainst": "Huricane",
            "league": "NBA",
            "sport": "Basketball"
         }
      ]
   }
}

Event Log

You can check all sent events on the Dashboard. Go to the ‘Log’ page to see a table with all events, their types, sent bodies, user IDs, and the time they were sent.