Tracking Player Events

Events are the main pillar that signals an interaction between your customers/consumers and Gameball. An event could be anything that describes an action that the customer does, for example in case of an e-commerce platform, an event could simply be visiting a product page, a customer adding an item to his cart, or could be a more complex one such as placing an order. Furthermore, an event could be a physical one tracked through any digital medium; such as an app with a QR code scanner to track “entering a room” event for instance.
In this tutorial we take a look at multiple use cases through which we discuss different scenarios. For example, how you can track various events on different platforms, and further engage your users by configuring tailored event-based challenges/messages which are handled by Gameball.
The wide variety of events introduces a huge pool of possibilities that we can make use of in our Gameball event engine to enhance your customers' experience.

The below figure illustrates in a nutshell how the user interaction with your system is translated into events to be sent to Gameball.
Before we dive in, you may find it useful to take a look at the following API(s) that will be used throughout this tutorial, where we will demonstrate how each one can contribute to better track your players' events.
In this tutorial we explore the following use cases:
​Track add to cart event​
​A Mobile App Event​
​On Ground Event Attendees Engagement​
​Online Meetings Events​
Track Add-to-Cart event
Assuming you have an e-commerce store and you need to simply keep track of an Add-to-Cart event. Tracking such events could help you configure specific cart related challenges or send customized messages to your customers. We will dive - step by step - into how to send an event to Gameball and make use of such events to build an interactive experience.
Sending the “Add-to-Cart” event
Let’s say you need to send Gameball information whenever a customer adds a product to his cart. In this example, we assume that you’re tracking a customer who’s adding an “iPhone 12” to his cart. First of all, let’s start by simply sending the “Add-to-Cart” event to Gameball.
On clicking “Add to Cart”, that’s how the event's request body - to be sent to Gameball - should look like in this case:
{
  "events": {
    "add_to_cart": {}
  },
  "playerUniqueId": "user_123"
}
After sending the above event, Gameball now knows that your player “user_123” has triggered an “add_to_cart” event. You can make use of tracking the above event by linking this event with customized challenges or messages, for example a “Cart Ninja” challenge whenever a user adds 10 products to their cart for the first time.
Sending the “Add-to-Cart” event with additional information.
Now, you might want to enrich your data a little by adding additional information to the add-to-cart event. Gameball enables you to build a better, more interactive experience for your customers by configuring customized challenges or sending out relevant messages to them. In order to achieve such an experience, you may find it useful to send additional information along with your event body that better describes the event. The more metadata you send with the event gives you more liberty and options to design your engaging and interactive experience. Some useful information could be the product_id, category, price, etc.. .
In such case your event body should for example, look like this:
{
  "events": {
    "add_to_cart": {
      "product_id": "231402",
      "price": 1350.00,
      "weight": 1.45,
      "vendor": "Apple"
    }
  },
  "playerUniqueId": "user_123"
}
Configure a relevant challenge
Now, having this extra information, the next step would be to play around with such information a little to configure a certain challenge. For example an “Apple Top Fan” challenge, for the first time a player adds to their cart a product sold by “Apple”.
In order to achieve that, you should navigate to Gameball admin dashboard, go to Programs → Challenges → Create New Challenge, and configure the described challenge as follows:
Configure a customized message.
Now, let’s make use of this additional information to send your customer a customized message, for example “Save up to 6% of the total order price if you also added a charger with your order”. In such case, this message is to be sent to the user when the added item to the cart is sold by “Apple” and belongs to the “Mobile Phones” category, making use of the vendor property sent with the event body.
As a result, you will need to add a category property to make sure it belongs to the “Mobile Phones” category to be able to configure your challenge accordingly.

In this case, the “add_to_cart” event payload will look like this:
{
  "events": {
    "add_to_cart": {
      "product_id": "231402",
      "category": "Mobile Phones",
      "price": 1350.00,
      "weight": 1.45,
      "vendor": “Apple”
    }
  },
  "playerUniqueId": "user_123"
}
In order to create this customized message, navigate to Messages → Player Messages → Add New Player Message, and start composing your message as follows:
Then you will have to identify the message trigger as Event, and select your configured event “add_to_cart”; specifying the rule based on which the player should receive the message.

After that, the player will now receive the message when the event is triggered.
A more challenging use case for the above example, would be to send a message for your user upon adding a product with category “Mobile Phones” and sold by “Apple” with price above 1200 USD.
A Mobile App Event
Let’s assume you own a music streaming service, something like Spotify for example. There could be many possible ways on how you can track your player's events on a streaming service. For instance, you need to reward a user for liking 10 songs. In order to be able to track such activity you need to trigger an event and send its details upon hitting the like button.
In such case, you would need to send an event with related details to Gameball to be able to track such event using the following payload:
{
  "events": {
    "song_liked": {
      "song_id": "231402",
      "title": "Coping",
      "album_id": "95621",
      "artist_id": "4773",
      "tags": ["Pop", "R&B"]
    }
  },
  "playerUniqueId": "spotify_user123"
}
In the above event details, other challenges could be configured using the above example. For instance, let’s assume this album is new and your goal is to boost the listening count of this album, so you may find it useful to create a challenge if a user likes for example 3 songs of the album to complete a “Rosie’s Cheerleader” (name of the artist) challenge.
In this case the configured challenge will look like this:

On Ground Event Attendees Engagement
Assuming your goal is to track a physical event such as a TEDx event. Tracking this event is to be achieved using for instance a mobile app for your users to register for that event, get information about the event's timeline, number of sessions, duration, speakers, sponsors and so on.
Assume you have a scannable QR code on each session's room, through which your mobile app would be able to check and track your attendees' attendance.
A possible scenario is to boost your attendees engagement with the sessions, which take place in different rooms.

For example, you need to motivate attendees to attend a certain session in the event. Accordingly, you can configure a challenge upon the event of attending this session specifically.
To track such an event we may assume that using a QR code and a mobile device of a registered attendee on your app, this event could be sent upon scanning the QR code before entering that specific session room.
Let’s assume that upon scanning the QR code you can capture some relevant information, such as attendee’s entrance time, attendee’s departure time, session duration etc.. .
You can make use of the above information and configure a challenge for any attendee, who attended three different sessions that belong to a specific category, for instance an “AI Warrior” for an attendee who attended 3 sessions belonging to the “AI” category.
You can now send Gameball the “attend_session” event, The event payload in this case could possibly be as follows:
{
  "events": {
    "attend_session": {
      "session_id": "231402",
      "title": "Using Artificial Intelligence for marketing analytics",
      "event_id": "15",
      "session_duration": 90,
      "category": "AI"
    }
  },
  "playerUniqueId": "attendee_123"
}
REST API - Previous
Object Reference
Next - Tutorials
Build Custom UI 👑
Last modified 10mo ago
Copy link
Outline
Track Add-to-Cart event
Sending the “Add-to-Cart” event
Sending the “Add-to-Cart” event with additional information.
Configure a relevant challenge
Configure a customized message.
A Mobile App Event
On Ground Event Attendees Engagement