The User Settings feature allows the user to customize the behavior of the app by changing options or settings. You can change the names, types, and other properties of one or more user settings. User settings may be used in expressions (security filters, slice filters, app formulas and initial values, column constraints, format rules, etc.) to control the behavior of the app.
Here's the Data > User Settings tab in the app editor:
There are a fixed number of options, each of which is initially hidden. Click to unhide one or more options, change their names, types, and other properties to control the structure of the user settings for your app. This is identical to the way you refine the column structure of regular tables in the app. You can use many of the same mechanisms: column constraints, initial values, etc.
Learn more about when to have user settings in your app and some of their limitations in the article, User Settings: Appropriate Use and Limitations.
Each individual user setting is a row in a hidden table. The columns of this hidden table have the same column features as normal table columns, such as column types, column constraints, app formulas, initial values, and display names. Column values from the user settings table are available within expressions using the USERSETTINGS() function.
Unlike normal tables, the user settings are stored on the device itself, not in the cloud. Consequently, user settings do not follow the user between devices.
Each signed-in user has their own user settings; one user may not access another's user settings.
The user settings option values are saved in the app on each device or browser in which the app is running. If the app requires user sign-in, the user settings are unique to each signed-in user. These values persist across restarts of the app.
However, when the app is being run in the emulator within the app editor, user settings (along with all other cached information) are deleted every time the page is refreshed. This allows the app creator to work with a clean state each time the app is run.
User Settings and Your Subscription Plan
There are restrictions on the subscription plans that allow user settings:
- Among the Publisher/per-app plans, user settings is only available with the Publisher Pro plan. It allows this class of apps to react to the option choices of individual users, but it doesn't take the place of a sign-in mechanism. For a sign-in mechanism, use one of the secure per-user plans with the Require Sign-in app setting.
- Among the secure per-user plans, user settings is only available with the Starter and Core plans. Note that user settings is not a mechanism to lower licensing requirements. For example, if there are five members of a team using a deployed app, we still requires five user licenses. It is inappropriate to share a single user sign-in account across multiple users of the app, having them differentiate via user settings.
User Settings Example
In the Driver Jobs sample app, user settings are used so each driver can view their own job assignments. There are five drivers, each assigned jobs by a central dispatcher. Drivers can use the app to find what jobs they've been assigned. In the app's menu, there is a Settings option. We're going to walk through how to apply user settings so that this works properly.
Since we're interested in having a list of drivers from which a user can select themself, we uncheck the Driver option.
Next, navigate to the Settings icon in the app emulator. You can select it and choose from a list which user you are. In this case, the users are drivers and will have a particular driver number, which can be selected.
Access user settings in any expression with the USERSETTINGS() function. For example, in the Driver Jobs sample, there is a security filter of the form,
[Driver] = USERSETTINGS("Driver").