​
What are Users?

Users are the individual people that use your product. You tell Trophy about your users through APIs and use the dashboard to design gamification experiences around them. Users must be individuals, they cannot be companies or organisations. To create organizational structures or user groupings, consider using a custom user attribute.

​
Key Attributes

Key attributes are properties of users controlled and managed by Trophy and are for things like id or email, some are required while others are optional.

​
Required Attributes

Trophy only requires one key attribute, id. Every user you tell Trophy about must have an id, this is what identifies them as a unique person.
​
id
string
required
This is the ID of the user in your database.
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.

​
Optional Attributes

Additionally, you can tell Trophy about any of the following optional 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.

​
Custom User Attributes

Custom user attributes are managed by you and can be anything you like based on your use case. For example a language learning app might use a custom user attribute for the language a user is learning, or a study platform might use one for the users favourite subject. Custom user attributes let you tell Trophy about this contextual information and use it to personalize gamification features.

​
Creating Attributes

To create a new custom user attribute, head to the attributes tab of the users page in the Trophy dashboard and hit the Add User Attribute button. Give the attribute a name and a unique key. The key is what you’ll use to reference the attribute in API calls.

​
Setting Attributes

Attributes can be assigned values for specific users using their unique key either inline, as users increment metrics through the metric increment API, or explicity through the user identification, create user, or update user APIs.
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: pln. Please ensure all attribute keys match those set up at https://app.trophy.so/users/attributes."
}
Across all APIs, the schema for setting attribute values is consistent. Here’s an example of a request payload that sets the value of two custom user attributes subject and plan: 
{
  "name": "Joe Bloggs",
  "email": "joe.bloggs@example.com",
  "attributes": {
    "subject": "physics",
    "plan": "free"
  }
}

​
Using Attributes

Use custom user attributes across Trophy to personalize gamification features , aggregate and filter data returned from APIs, and to segment and compare user cohorts in analytics.

​
Feature Personalization

Custom user attributes can be used to personalize achievements, customize the way points are earned by different users and more. Follow the links to the relevant pages below to learn more.

Personalizing Achievements

Configure achievements that can only be unlocked by specific users.

Personalizing Points

Personalize how different users earn points.

Email Segmentation

Control which users receive gamified emails.

Email Personalization

Personalize email copy and subject lines with custom user attributes.

​
Data Aggregation and Filtering

You can use custom user attributes to aggregate and filter data returned from some APIs to support a wide range of gamification use cases. In all cases, attributes are included in the userAttributes query parameter using a consistent schema: ?userAttributes=city:london,subscription-plan:pro Here’s a list of all APIs that support the userAttributes query parameter:

​
Segmented Analytics

Custom user attributes can be used to segment and compare retention and engagement charts between user groups. This is useful to understand which cohorts are making full use of your gamification features, and which are struggling to engage and therefore require some attention.

​
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!