Preferences

Preferences are used to add attributes to users and groups. This information is used in blocks, web components, APIs, and reporting.

If you're storing attributes that will be used by missions, you should use groups instead of preferences.

User Preferences

You can use preferences to add additional information about the user, such as first name, last name, preferred name, hire date, or other custom data. Preferences are stored as a name:value pair. Preference names are case-sensitive when used in APIs, blocks, and web components. Case-sensitivity is ignored when adding preferences to reports in Data Export.

There are six special reserved preferences that Nitro displays in user-facing elements such as profiles, leaderboards, search lists, etc.

firstName - The user's first name.
lastName - The user's last name.
additionalName - The user's preferred name or nickname. Used to help differentiate between users with the same first and last name in the Recognitions web component search.
userPhotoUrl - The user's photo/avatar image. If an image is not set, the user's level icon or a default icon will display. Group icons set in the Group Management view display in group leaderboards.

role - The user's job title/role.
anonymous - Hides the user from leaderboards and events feeds. When the preference exists, the user is anonymous. The value can be ANY value, including no value. You must delete the preference to remove the anonymous setting. Note: Anonymous users will still appear in the Recognitions search list as a user that can receive a recognition.

Note: The userPhotoUrl preference maps to the iconUrl preference. When preference information is pulled via API, the image set in userPhotoUrl will be returned in the iconUrl parameter.

You can manage user preferences in the User Management view, Group Management view, via data import, or with the PUT /users/{userId}/preferences method.

Security Guidelines

To increase security and prevent cross site scripting (XSS) attacks, security is enforced on the firstName, lastName, additionalName, iconUrl, and userPhotoUrl user preferences.

The firstName, lastName, and additionalName preference values only allow letters (any language), numbers, hyphens (-), underscores (_), periods, commas, backticks (`), parenthesis (), straight brackets [ ], forward slashes (/), accents (ñ), the at sign (@), and spaces. iconUrl and userPhotoUrl check the format of the URL to ensure it's valid, but no check is done to verify that it's a real image.

Site Preferences

Site preferences are stored at a site-wide level for access across the site (Configuration > Site Settings > Preferences). The following site preferences are available for configuration by Bunchball support. Please contact support to enable or modify the following:

Preference	Description
challengeCompletionLimitExpiringSoonThreshold	Defines the number of mission completions remaining to show as expiring soon. Once this number is reached, the number of missions remaining display in the Missions web component list view. Defaults to 5.
challengeEndTimeExpiringSoonThreshold	Defines the number of days remaining in a mission to show as expiring soon. Once this number is reached, the number of days remaining display in the Missions web component list view. Accepts a value between 1 and 24. Defaults to 2.
challengePointLimitExpiringSoonThreshold	Defines the number of points remaining in a mission to show as expiring soon. Once this number is reached, the number of points remaining display in the Missions web component list view. Defaults to 100.
challengeStartTimeStartingSoonThreshold	Defines the number of days remaining before a mission with a future start date shows as locked in the Missions web component. Defaults to 5.
daysUntilPasswordExpire	Defines the number of days a Nitro Studio user's password is valid.
displayLeadersLastInitial	Enables leaderboards to only show the first letter of a user's last name. Setting this preference to true displays the user's name as Jane D rather than Jane Doe.
enable_multiple_locales_flag	Enables/disables localization.
ignoreLeaderboardMaxRankLimit	When set to true, enables leaderboards and leaderboard APIs to have a return count higher than 100.
rankedEligibleChallenges and rankedEligibleChallengesUserOption	Enables our AI driven mission recommendation engine in the Missions web component. Note: Does not apply to Impact. The Impact block always uses the mission recommendation engine. When enabled, users see missions ordered based on featured, importance, in progress, and other statuses. When disabled, users see missions in the legacy mission order. You can enable the mission recommendation engine for all users or only for individual users. All Users - Set rankedEligibleChallenges to true to enable for all users. Individual Users - Set the rankedEligibleChallengesUserOption site preference to true, then set the rankedEligibleChallenges user preference to true to enable for an individual user. When using rankedEligibleChallengesUserOption, rankedEligibleChallenges cannot exist as a site preference. rankedEligibleChallenges always overrides rankedEligibleChallengesUserOption.
rewardExpiringSoonThresholdInDays	Defines the number of days remaining in a mission reward to show as expiring soon. Once this number is reached, the number of days remaining for the reward will display in the Missions web component. Defaults to 7.
showCurrentLevelIconForUserProfile	Displays a user's level when the user does not have an image/avatar set in the userPhotoUrl preference. When set to true and userPhotoUrl is not set, web components and the Recognitions block display the level image. Click the image to see this example When set to false and userPhotoUrl is not set, Leaderboards display a default image in the bottom section and no image in the list. The Recognitions block displays the user's initials (a name is set) or a default image (no name is set). Click the image to see this example
userSegments	Defines user preferences.