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, display name expressions, column constraints, format rules, etc.) to control the behavior of the app.
Here's the Data > User Settings tab in the 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.
User settings are modeled as a row of data in a special hidden UserSettings table. Because it's just a row of data, you can control the structure of the data in standard ways (by editing its column structure) and you can use the data in standard ways inside expressions. Each user has exactly one row in this special table. The row is not stored physically in a backend spreadsheet; instead, it's maintained inside each app on each device, and is available for use within expressions in the app.
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 Premium and Pro 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).