​
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

Events only have one required attribute, 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.

​
Custom Event Attributes

You can specify a number of custom event attributes to help you track additional information relevant to your use case against events you send to Trophy. For example, a language learning app might have a ‘Questions Completed’ metric and use a custom event attribute to store wether the answer to each question was correct. Similarly a fitness app might use an ‘Excercises Completed’ metric and use a custom event attribute to store the weight that was used in each excercise and another custom event attribute to store how long the excercise lasted. Using custom event attributes in this way allows you to enrich events in Trophy with additional context relevant to your use case and use it to power even more engaging gamification features.

​
Creating Attibutes

To create a new custom event attribute, head to the metrics page in the Trophy dashboard and hit the Add Event Attribute button. Give the attribute a name and a unique key, you’ll use the key when referencing the attribute in API calls.

​
Setting Attributes

To set the value of a custom attribute on an event, pass its value in the attributes object in your metric tracking code.
Trophy will only set values of attributes that have first been created in the dashboard. We do this to help you keep a clean set of attributes and prevent accidental overwrites.If you receive an error similar to the following then you might have miss-spelled the attribute key in the request, or you need to create the attribute first in the Trophy dashboard:
{
  "error": "Invalid attribute keys: devce. Please ensure all attribute keys match those set up at https://app.trophy.so/metrics."
}
Here’s an example of an event payload where the values of two attributes, device and duration, are set: 
{
  "user": {
    "id": "18",
    "tz": "Europe/London"
  },
  "value": 25,
  "attributes": {
    "device": "ios",
    "duration": "120"
  }
}

​
Using Attributes

Custom event attributes can be used to power more advanced triggers for achievements and points and can be used in email templates to customize copy and to control the data shown in charts.

​
Advanced Feature Triggers

Custom event attributes can be used to set up achievements or points triggers that only track events with specific attribute values. Follow the links to the relevant pages below to learn more.

Achievement Triggers

Configure achievements that can only be unlocked by events with certain attribute values.

Points Triggers

Set up points triggers to only award points from events with specific attribute values.

​
Email Customization

If you use any Trophy Emails, event attributes can be used to customize the data shown in certain email blocks. Firstly, when using metric-based variables in email copy you can use event attributes to further control what data the variable refrences. For example here’s a case where we use an email variable to tell users what their total number of workouts they’ve done on different gym equipment is using a metric ‘Workouts’ and an attribute ‘Equipment’:
Secondly, here’s an example where we add a chart to an email that shows users how many workouts they’ve done on a bike over time:
There’s a huge number of possibilities here, so get creative!

​
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": {
    "point-system-key": {
      "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:

​
Idempotent Events

Trophy supports enforcing uniqueness on events so that users cannot increase a metric by taking the same exact action over and over. For example, a language learning app could specify that users can only increase the lessons completed metric by 1 for each unique lesson completed, so if they complete the same lesson twice only the first counts. This helps keep your codebase free of logic that checks if users have completed actions before, and can instead trust Trophy to uphold the constraints you need. To use idempotent events, use the Idempotency-Key header in the metric event API. Learn more about idempotency.

​
Get Support

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