User Settings

Some mobile apps allow the end-user to customize the behavior of the app by changing some "options" or "settings". If you want to enable this capability in your app, use the User Settings feature. it allows you to create one or more user settings/options, changing their name, type, and other properties. Typically, these user settings are used in expressions (security filters, slice filters, display name expressions, column constraints, format rules, etc) to control the behavior of the app.


User Settings are modeled as a row of data in a special hidden UserSettings table. Because it is 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 is maintained inside each app on each device, and is available for use within expressions in the app.


Take a look at the Driver Jobs sample in our app gallery. There are five drivers, each assigned jobs by a central dispatcher. The app is meant for the drivers to find the jobs assigned to each of them. In the app's menu, there is a Settings option.

UserSettings1.PNG  UserSettings2.PNG  UserSettings3.PNG

When this option is selected, the user sees a form that asks for a driver ID. When the user selects one of the driver IDs, the app shows the jobs for that specific driver. 

How to create User Settings:

When creating your app, go to the Data -> User Settings pane. This shows the structure of the user settings. There is a fixed maximum number of options, all of which are initially hidden. Click to unhide one or more of the 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.



How to use User Settings to change app behavior:

It is easy to access the user settings in any expression within the app via the USERSETTINGS({OptionName}) function. For example, in the Driver Jobs sample, there is a Security Filter of the form [Driver] = USERSETTINGS(Driver). 


The User Settings option values are persisted in the app on each device or browser the app is running in. If the app requires user sign-in, then 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, the 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. 

Appropriate use and limitations:

Here are some common and appropriate use cases for User Settings:

  • Your app has data analytics for ten different countries. Ask the user to select a country via the User Settings, and filter the data (via a Security Filter or Slice) to show just the appropriate information for that country.
  • Your app supports users in more than one language. Ask the user to choose a preferred language via the User Settings, and modify the user interface using DisplayName expressions based on the chosen language. 
  • Your app is for members of a soccer league to see the upcoming matches for their team. Ask the user to choose their team via the User Settings, and filter the data appropriately.
  • Just as in the Display Jobs sample, your app is for members of a team to pick up tasks to work on. Each team member provides an identifier or name via the User Settings, and the app filters the data appropriately.

User Settings should not be used as a security mechanism. In particular, do not create a "homegrown" username/password mechanism via User Settings. Any capture of an end-user password needs especially secure implementations for data capture, transport, and storage. End-users tend to reuse passwords across systems, and their data is only as secure as the weakest link across all these systems. In other words, if a password is compromised in one system, it typically compromises many other systems used by the end-user. This is why we believe this is a very serious matter, and any such use within AppSheet violates the terms of use of the platform.

There are restrictions on the subscription plans that enable the User Settings option. 

  • Among the Publisher/per-app plans, this feature 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 does not 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, this feature is only available with the Premium and Pro plans. Please note again that User Settings are not a mechanism to lower licensing requirements. For example, if there are five members of a team using a deployed AppSheet app, the system 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. 
Have more questions? Submit a request


Please sign in to leave a comment.