​
What are Events?

Events represent individual user interactions 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 the total value of 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 Points 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",
      "description": "Write 500 words in the app.",
      "achievedAt": "2025-04-02T00:00:00Z"
    }
  ],
  "currentStreak": {
    "length": 1,
    "frequency": "daily",
    "started": "2025-04-02",
    "periodStart": "2025-03-31",
    "periodEnd": "2025-04-05",
    "expires": "2025-04-12"
  },
  "points": {
    "total": 5,
    "added": 5,
    "awards": [
      {
        "id": "2414266f-9d02-4820-866b-47b03e87b702",
        "awarded": 5,
        "trigger": {
          "id": "8126234a-2d8c-498d-b919-2459378accad",
          "type": "metric",
          "metricName": "Words Written",
          "metricThreshold": 10,
          "points": 5
        }
      }
    ]
  }
}

In this example the response includes the following:

  • Newly unlocked achievements as a result of the event
  • The users latest streak as result of the event
  • Any points awards as a result of the event

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

  • Triggering in-app notifications
  • Sound effects
  • Animations

Additionally, any Emails configured to track the metric will be scheduled automatically by Trophy.

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

​
Get Support

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