Configure the Digitise Apps Client on Android Devices

The standard Digitise Apps Client can't be configured before you install it and so must be configured after it has been installed. A pre-configured Client, on the other hand, can be configured as part of the build request and allows you to optionally lock individual settings to prevent them being changed by the user. If you configure all the required settings for a pre-configured Client in the build request, you will not need to perform any further configuration after it has been installed to a device. Settings which aren't pre-configured or locked, can be edited after the Client has been installed.

This topic explains how to configure either type of Client on Android devices. It assumes you are configuring a Client for the first time which doesn’t have the App Server address pre-configured. After the initial configuration, you can view and edit the settings at any time following the same method described here.

Note that locked settings will be visible within the Client but cannot be changed and not all the options available in the standard Client may be available in the pre-configured version of the Client.

In order for a user to run apps within a Client, the Client must at least be configured to set the connection details for the App Server to which the apps have been, or will be, published. A pre-configured Client may already have this information configured, but if not and for standard Clients, you will need to enter these details before the user can use the Client to run apps. You may also want to view the current settings or edit other available settings.

To configure or re-configure a Digitise Apps Client on an Android device:

1. When you install a Client, at the end of the installation you will be asked if you want to load the Client.

   Tap Open to load the Client or to close the install without opening the Client, tap Done.

   If you open the Client, you can configure any settings you need to, but if you don't you can load it and configure it later.

   To load the Client later, tap on the Digitise Apps icon, , from the device's App Drawer or Home screen.

2. In either case when the Client loads, the Applications screen will be displayed:

   

   This screen displays the Digitise apps which have been downloaded to this device. If this is the first time you’ve run the Client, there won’t be any apps listed, as in the picture above.

3. At this point the following login screen may be displayed:

   

   For example, you may be asked to log in if the Client has been configured to check for updates on startup and has its App Server details configured. This could occur if you are installing a pre-configured Client, whether you are running it for the first time or not, or if you are loading a standard Client which has been loaded and configured appropriately on a previous occasion. If you are running the standard Client for the first time, you should not be required to log in.

   The user login determines which Digitise apps will be available to the user.

   Whenever the login screen appears, you will need to log in or cancel. If you only want to configure the Client at this point and don’t intend to download or use any Digitise apps, you can cancel the login, which should still allow you to access the configuration settings.

   If you want to log in, you will need to obtain the login credentials from whoever configured the App Server, if that wasn’t you. There are four types of possible user - a Digitise Apps User, a Windows Domain User, a Google OAuth User or an Anonymous User.

   To log in anonymously, simply select the Login anonymously check box.

   To log in using Digitise Apps User credentials enter the username and password. If there is a value in the domain field, you will need to delete this. Note that if you are unable to delete this field, this means that the Client has been configured to only allow Windows authentication and you cannot log in as a Digitise Apps User. If you are configuring a pre-configured version of the Client, the domain field may have been hidden as part of the pre-configuration settings. This should only have been done if you don’t need this field to login.

   To log in using Windows authentication you will need domain, username and password. You can enter the domain name in the domain field or include it with your username in the username field in the standard format:

   <domainname>\<username>

   Including the domain name in the username field will overwrite any domain name specified in the domain field.

   By default, values you enter in the username field and, if shown, the domain field are automatically saved and filled in the next time the Login screen is displayed. When building a pre-configured version of the Client, you can turn off username saving within the build request options, if required.

   If the Save password option is displayed, you can instruct the Client to remember your password as well and automatically fill in the password field the next time you log in. Select the Save password option to save your password. The password entered will be stored in an encrypted database on the device.

   If you are installing a pre-configured Client, the domain and Save password options can be pre-configured and can also be locked so that the user cannot change them on the device. If the domain field is locked, you cannot include the domain in the username field and an attempt to do so will result in an error message being displayed. If the Save password option is set to not allow password saving and is locked, the option will not be displayed on the Login screen.

   If you log in anonymously after logging in as a Digitise Apps User or Domain User, the next time the Login screen displays, the credentials fields will be blank.

   When you have entered your credentials, tap OK.

   If you need to log in as an OAuth User rather than using Digitise Apps credentials or Windows Active Directory Authentication, the Client will load a browser and present you with the Google login page instead of the login fields shown above. For more details about logging in using OAuth see Log In Using Google OAuth Authentication.

4. If you have an SD card in the device, a message will be displayed asking whether you want to store application data on the storage card. Application data includes the local database tables used to store data when running your Digitise apps. Tap Yes to use the SD card to store this data or No to use internal storage instead. In general, it is usually faster and more secure to use the device memory than the storage card, but in deciding which to use you will also need to take into account the speed of your SD card and the amount and sensitivity of the data you will be downloading to the device.

   • If you opt to store application data on the SD card, the application resources and data will be visible to all other apps running on the device. For example, this means that any images used in your Digitise apps will be visible in the photo Gallery app and could accidentally be deleted. Database files are also accessible, but the data is stored within them using a strong encryption cypher (AES 256-bit).
     In addition, if you store application data on the SD card, the application and database files will not be deleted when a Digitise app is uninstalled and will need to be deleted manually if required.

5. You will then see a message informing you that you have no servers configured. Tap Yes to configure the details of your App Server or No to go straight into the Client. If you choose No you can configure the App Server details later – see below.

6. If you tapped Yes, the New Server dialog box will be displayed:

   

   Enter the DNS Name or IP Address of the PC running the App Server in the Address field.

   • If you will be using the enhanced certificate-based private key exchange encryption mechanism for data in transit between your App Server and Digitise Apps Client, and you enter a DNS name here, the DNS name you enter must match one of the hostnames specified in your SSL Certificate’s Common Name field and/or Alternative Names fields.

   Leave the Port Number at its default setting of 3431, unless you are sure that this port is already in use by another application. Note that if you do change it here, you also need to change it on the App Server, which you do using App Manager - the Port setting can be found within the Server category Properties.

   Tap on OK to save your changes.

7. The Server settings page will be displayed including the Servers list showing the details you just entered:

   

   You can enter more than one server in this list if required, for example to provide access to a backup server, and when the Client attempts to connect to the App Server, if the first address in the list fails it will automatically try the next one down and so on. On subsequent connections within the same session, the last used successful address will automatically be used first. A session ends when you close down the Client or modify the server list.

   To add another address, tap on Add server at the top of the screen.

   To edit or delete an entry in the Servers list, tap and hold the relevant server details to display a menu and then tap the required item on the menu. If you have multiple servers listed, the context-sensitive menu will also include options to change the position of the server in the list by moving it up or down one position.

   • If you are installing a version of the Digitise Apps Client which has been pre-configured, the developer can lock some individual settings when the Client is created. Settings which have been locked can be viewed but not edited. If the server addresses have been pre-configured and locked, the Add server option will be disabled. This also applies to some of the other configuration settings described below.

8. When you have finished adding your Server(s), from the Server settings press the device’s Back key to return to the Applications screen.

9. To view and edit the configuration settings, including the Server settings, from the Applications screen tap the Menu button, , and choose Settings from the menu displayed.

10. This will take you to the Settings screen which provides access to the client configuration options and system information:

    

    If you haven’t yet entered your App Server connection details, you will need to at least do this before you can download and use your Digitise apps.

    This Settings screen contains the following items:

    General section

    Server settings

    Add a new App Server address and view currently configured server list.

    Tap this option and then tap Add Server to add a new server – see above for more details about entering connection details for an App Server.

    • You cannot download or run any of your Digitise apps until you have entered the connection details for the App Server to which the apps have been published.

     

    Always login anonymously

    If selected, this option automatically logs into the App Server as an anonymous user when you load the Digitise Apps Client. If not selected, the user may be prompted to enter their login credentials when the Client is loaded.

    By default, this option is Not Selected.

     

    Display simple progress

    If selected, this option displays a simpler set of messages to indicate the progress of data and app downloads. By default, the option is not selected and the full messages are displayed.

     

    Allow Untrusted Certificates

    This option is only relevant if you are using the enhanced certificate-based private key exchange encryption mechanism for data transferred between the App Server and the Digitise Apps Client and you are using an SSL Certificate which doesn’t have a trusted third-party Root Certificate, e.g. if you are using a self-signed Certificate.

    By default, the option is not selected, which means the device must have an appropriate trusted Root Certificate installed in order for the Client to communicate with the App Server. If you are using a self-signed Certificate or the Client displays a message saying that the Certificate is untrusted, selecting this option will allow you to use your chosen Certificate.

     

    Status section

    About

    Displays system information including the version of the Client, the Client’s Device ID as it will appear to identify this device within the App Manager, the screen size and density and the device’s IP Address.

    The About screen also indicates whether the Google Firebase crash reporting facility is enabled or not.

     

    Username

    Displays the username of the currently logged in user.

     

    LastServer

    Displays the last App Server the device connected to. If this is not the first server in the Servers list, the next time you attempt to connect to an App Server within this session, the Client will try the address displayed here before trying the other servers in the list. A session ends when you close down the Client or modify the list of Server addresses.

     

    Startup section

    Check updates on startup

    If selected, this option causes the Digitise Apps Client to automatically check for updates and new apps on the App Server when the Client loads. By default, this option is not selected and the user will have to manually request that the Client checks for updates and new apps.

    Since changes to the App Server configuration, including access permissions and the device purge options, are usually updated on the device only when the device checks for updates and new apps or attempts to download data within an app, you may want to select this option in order to force changes to the server configuration to be automatically updated on the device whenever the Client is loaded.

     

    Auto Run

    Allows you to specify a Digitise app to be run automatically when the Digitise Apps Client is loaded so that you don’t have to choose the app from the Applications screen.

    To specify an app to run, choose it from the drop-down list. By default, this option is set to Disabled, which means that when the Client is loaded, the user will be taken to the Applications screen from where they can manually load any of their available apps.

    Note that if you do specify an app to be automatically run, you can still access the Applications screen once that app has loaded. To do this keep pressing the Back key on the device to move back through the current app’s screens until the Client’s Applications screen appears.

     

    Advanced section

    Applications as grid

    Selecting this option displays the list of available Digitise apps available to you within the Digitise Apps Client in a grid format. Deselect the option to display a list instead.

    By default, the option is Selected.

     

    Display thumbnails

    This option affects how apps are displayed in the Applications menu within the Client. Selecting this option will display a thumbnail showing the current screen display for any app currently running. Non-running apps have a static icon instead. By default, the option is Not Selected which displays the static icon for all apps whether running or not.

     

    Debug Scripts

    This option allows you to start and stop the script debugging facility which allows you to step through your Digitise apps at runtime in order to help identify and diagnose problems.

    This option will only have an effect if debugging has been enabled within the app, which is done within App Studio.

    Setting this option to ON will start debugging for any apps which have debugging enabled. Setting it to OFF will stop debugging.

     

    Emulate BlackBerry

    This option is no longer supported and can be ignored.

     

    Use OAuth Authentication

    If selected the Client/Standalone App will use OAuth authentication when logging in.

    If not selected, the Client/Standalone App will use the standard Digitise Apps authentication method or Windows authentication to log in users.

     

    OAuth Client ID

    This option may only be displayed if you have selected the Use OAuth Authentication option above.

    If using OAuth authentication, this option allows you to specify the OAuth Client ID which is used together with the OAuth Client Secret, below, to identify Digitise Apps to Google.

    The Client ID is generated by Google when you set up OAuth authentication for Digitise Apps in the Google API Console.

     

    OAuth Client Secret

    This option may only be displayed if you have selected the Use OAuth Authentication option above.

    If using OAuth authentication, this option allows you to specify the OAuth Client Secret which is used together with the OAuth Client ID, above, to identify Digitise Apps to Google.

    The Client Secret is generated by Google when you set up OAuth authentication for Digitise Apps in the Google API Console.

     

    Save Password

    Determines whether the Digitise Apps Client will save the user’s password, so they don’t have to enter it in the login screen each time they login. The Client won’t login automatically but will pre-populate the password field within the login dialog.

    If selected, the password will be saved.

    If not selected, only the Username and Domain fields will be remembered.

    Remembered values are stored in an encrypted database on the device.

    Note that this Setting is equivalent to the Save Password option which appears on the login screen. Changing the option here will automatically change the setting on the login screen and vice versa.

     

    If you are using Google OAuth to login, this option works slightly differently – for details see Log In Using Google OAuth Authentication.

     

11. You can edit any of the options on this page, if required.

    • Note: If you are installing a version of the Client which has been pre-configured, the developer can lock some individual settings when the Client build is requested. Settings which have been locked can be viewed but not edited.

    If tapping an option takes you to another screen, when you have finished, keep tapping the device’s Back button until you return to the Settings screen.

12. When you have finished with the Settings screen press the device’s Back key to return to the Applications page.

13. If you have not yet created any Digitise apps, press the Back key to close the Client. On the other hand, if you do have apps available, you can list the apps available, download and run them - see Run Clients and Standalone Apps on Android Devices for more information.