​
What are Events?

Events store information about individual user interactions that are tracked against Metrics in Trophy. One event corresponds to a single interaction made by a single user.

When you integrate metrics into your platform, you’re setting up your platform to continuously stream events to your Trophy metrics for each user interaction. These interactions then drive all the gamification features you set up around these metrics.

​
Key attributes

​
Metric-backed

Each event increases or decreases a specific metric that you’ve configured in Trophy for a specific user.

​
Value

The value of an event is the numerical amount that will be added to the user’s total metric count as a result of the user interaction it relates to. The value can be positive or negative, and can be a whole number or a decimal.

​
Tracking Metric Events

Each metric has a unique key which you can use to reference and track events against it in your code. You can find the key in the metric settings page.

To start tracking user interactions as events against your Trophy metrics, use the Metrics API or one of our type-safe Client SDKs supported in most major programming languages.

Here’s an example where a fictional book-writing platform is using a metric to track the number of words written by each author. Each time an author edits their book, the platform sends an event to Trophy telling it how many words they wrote:

curl -X POST https://app.trophy.so/api/metrics/words-written/event \
     -H "X-API-KEY: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "user": {
    "id": "18",
    "email": "user@example.com",
    "tz": "Europe/London"
  },
  "value": 750
}'

Any Achievements, Streaks or other gamification features that have been set up against this metric will be automatically processed, and the response will contain any updates to the users progress that are a direct result of the event occurring:

Response
{
  "metricId": "d01dcbcb-d51e-4c12-b054-dc811dcdc623",
  "eventId": "0040fe51-6bce-4b44-b0ad-bddc4e123534",
  "total": 750,
  "achievements": [
    {
      "id": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "trigger": "metric",
      "metricId": "5100fe51-6bce-6j44-b0hs-bddc4e123682",
      "metricName": "words written",
      "metricValue": 500,
      "name": "500 words written",
      "achievedAt": "2020-01-01T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  }
}

With custom code, this response data can then be used to drive any in-app experience you wish including:

  • Triggering in-app notifications
  • Sound effects
  • Animations

Watch Charlie integrate metric tracking into a simple NextJS application using the NodeJS SDK:

​
Get Support

Want to get in touch with the Trophy team? Reach out to us via email. We’re here to help!