Preconfiguration of Mobile Apps

Right now, preconfiguration is only available for the iOS app and only when using a MDM (Mobile Device Management) system.

It is possible to provide the app with a custom configuration dictionary, which is read out on every app start and also during runtime of the app. With this it is possible to customize the experience for app users right from the beginning when they install the app. Possible options include pre-configuring parameters like connection URL or login name which lead to a better onboarding experience. Also, certain features of the app can be configured and enabled / disabled.

Grape iOS adheres to the configuration standards for business apps as defined by the AppConfig community. For further information please visit www.appconfig.org.

How to use

The iOS app is using the Managed App Configuration interface to allow MDM systems to push down a dictionary with configuration options right into the managed app for the purpose of remotely configuring the app (c.f. Apple Developer Docs)

The easiest way to get started is to download the Grape spec XML file. Some MDM systems can directly import this file to automatically build a custom UI for setting the configuration. When this is not possible the key-value pairs need to be entered manually, as defined in the XML file or in “Available configuration options”.

When the “Install App” command is send from the MDM system the app already comes preconfigured with the options that were specified in the configuration dictionary. In addition to that, values can also be changed when the app was already installed. The app will respond to these changes right away (if it is currently running) or at the next app start (if the app is in the background).

Available configuration options

Right now, there are the following configuration options:

  • connectionUrl / String: The default URL to connect to (e.g. https://subdomain.chatgrape.com or https://grape.example.com). If you set this, the app will have the connection URL preset. The “Select Connection URL” screen is skipped. Users can not change the URL in the app.
  • subdomainOfStartingOrganization / String: If your Grape instance has more than one organization (e.g. Grape Cloud or on-premise with multiple organizations), you can specify a subdomain of an organization here. This organization will automatically be joined after login and the user will not see the “Choose Organization” screen. However, the user can still change the organization after login (on the Settings tab).
  • userLoginName / String: Set a user variable here to pre-fill the username / email on the login screen.
  • userLoginNameCanBeChanged / Bool / Default true: Uncheck this, if you do not want users to be able to change the pre-filled username on the login screen. This only has any effect if the default login name was also set.
  • forceSSOLogin / Bool / Default false: Check this, if users should only be allowed to login via SSO. Users will see a special login screen with SSO being the only login option. Please be also sure to set the Connection URL (including subdomains) to take full advantage of this feature.