​
User Attributes

Users in Trophy have a number of attributes, some are required while others are optional. Here we look at the different attributes and how to use them.

​
Key Attributes

Every user you tell Trophy about must have an id, this is what identifies them as a unique person.
To make things simple, Trophy lets you use your own id that you already have in your database instead of needing to manage another one just for Trophy.
​
id
string
required
This is the ID of the user in your database.

​
Optional Attributes

Additionally, you can tell Trophy about any of the following key attributes and it will make them available to you as part of your gamification experience:
​
name
string
The user’s full name. This is accessible in email templates and other areas where you may want to address the user by name.
​
email
string
The user’s email address. This address will be used in any Emails that you set up as part of your gamification experience with Trophy.
​
tz
string
The user’s time zone. Must be specified as an IANA timezone identifier. Used to calculate streaks and send emails to users in accordance with their local clock.
​
subscribeToEmails
boolean
default:"true"
If you’ve configured any Trophy Emails, then they’ll only be sent to a user when this field is true. Note: If you don’t provide an email, attempting to set this field to true will result in an error.

​
Identifying Users

When you tell Trophy about a User in your platform, we call this identification. There are two ways you can identify users with Trophy, inline and explicit identification.
We recommend getting started with inline identification if you’re new to Trophy. If you decide you need more control, try explicit identification.

​
Inline Identification

Inline identification is the easiest way of telling Trophy about your users as it doesn’t require any specific user identification code. You simply tell Trophy about users as they go about normal use of your platform. In practice this means whenever you use the Metric Event API, you pass along full details of the user who triggered the event. Here’s an example where an API call is made to the metric events API, and the details of the user who made the interaction are passed along in the request body: 
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
}'
In this case, if this is the user’s first interaction (i.e. they are a new user) then a new record will be created for them in Trophy automatically. However if Trophy finds an existing record with the same id, then Trophy will update any details of the user that are passed through. In other words, inline identification is by means of an UPSERT operation.

Identifying users in this way has two key benefits:
  • All new users that sign up for your platform and increment a metric are automatically tracked in Trophy without any explicit identification code written by you
  • Any changes to existing user properties like name or email address are automatically synced to Trophy the next time the user increments a metric
In this way inline identification allows you to keep your entire userbase in constant sync with Trophy with the least amount of code required by you. This is why we recommend starting with inline identification first, then exploring explicit identification if you discover you need more control.

​
Explicit Identification

Explicit identification is when you write code in your application that explicitly tells Trophy about users seperate from any metric interactions. This is useful if you want complete control over how and when Trophy learns about your users. Scenarios where you might want to use explicit identification might be:
  • You want to tell Trophy about new users immediately on sign-up, before they increment a metric
  • You track a lot of metrics in Trophy, and don’t want to repeat inline identification code.
  • You want to only tell Trophy about a specific cohort of users, of which you control the conditions around
In this case, you can tell Trophy about new users using the User Identification API. 
curl --request PUT \
  --url https://app.trophy.so/api/users/{id} \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
  "email": "user@example.com",
  "name": "User",
  "tz": "Europe/London",
  "subscribeToEmails": true
}'
Just like in inline identification, explicit identifcation also works by means of an UPSERT operation meaning all user attributes are kept in sync with Trophy automatically.

​
Creating Users

To explicitly create a new user in Trophy, use the Create User API.

​
Keeping Users Up To Date

To tell Trophy about an update to a user in your platform you can use the Update User API. Any properties that you pass to Trophy will be updated to the new values you specify.

​
Retrieving User Information

To fetch the details of a user that you’ve already identified with Trophy, use the Get User API. This will return the full details of the user along with the control attribute that you can use to conditionally enroll users in any gamification features. Learn more about Experimentation.
Response
{
  "id": "user-id",
  "control": false,
  "created": "2021-01-01T00:00:00Z",
  "email": "user@example.com",
  "name": "User",
  "subscribeToEmails": true,
  "tz": "Europe/London",
  "updated": "2021-01-01T00:00:00Z"
}

​
User Analytics

​
Basic Analytics

By default Trophy includes high-level user analytics including on the Users page including:
  • The total number of users that you’ve told Trophy about
  • The number of users that are active on a daily basis
  • The number of users that are active on a monthly basis
On this page you can also search through every User that Trophy has recorded, which can be useful for debugging.

​
Top Users

Additionally, on the Dashboard, Trophy shows a Top Users list with the set of users who have made the most progress against your platform’s metrics. These are your most engaged users, so it’s useful to know who they are!

​
Frequently Asked Questions

​
Get Support

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