Using Settings in an App

Desk Phone API features described in this section are deprecated and supported only on the following models: D40, d45, d50, d60, d62, d65, d70

You can develop your app so it uses generic settings, or settings that are specific to each phone. If you have phone-specific settings, you can choose to store them in the phone's config file, or have the user enter the settings via your app. This guide discusses how to choose the best solution for your app.

If your app relies on information that may be different depending on the phone that is using the app, then you'll want to define settings for the app to use.

Settings stored in the phone's config file

The appconfig area of each phone's config file can include one or more settings for the app to retrieve and act on. This is a good way to publish settings because they are managed with the rest of the phone's configuration information, and they will 'survive' a factory reset (because the settings are stored somewhere else).

In development, those settings can be entered using the development web page or the CGI.

Settings entered via your app

If your app includes data input, then that information is stored and retrieved as indicated in your app.

Remember information gathered this way is deleted during a factory reset. So, if you are collecting a small amount of information that won't be too discouraging if a user has to re-enter it, then this method is fine. Otherwise, you should manage your app's settings along with the rest of the phone's configuration information, and publish it in each phone's config file.

The following example uses the digium.readFile and digium.writeFile methods to store local settings.

 /* Here are two simple functions for working with JSON / and a JavaScript object to store some settings information. We use the readFile and writeFile method to store a string and use the native JSON JavaScript object to parse and stringify it. */
  
//settings object passed in, let's assume it looks like {"name" : "Bob", "location" : "USA"}
function saveSettings (settings) {
      var settingsString = JSON.stringify(settings);
      //write our settings in non-volatile storage so they are preserved.
      digium.writeFile("nv", "my_app_settings.json", settingsString);
}
  
function readSettings () {
       var settings = {};
  
      // we wrap loading this file in a try catch because we are not sure if it exists yet or not.
      // if it doesn't the app engine will throw an exception halting execution.
      // this is also why we initialize the settings object above.
      // If this errors we will return the empty object
       try {
             var settingsString = digium.readFile("nv", "my_app_settings.json");
             settings = JSON.parse(settingsString);
       } catch (error) {
                util.debug("my_app_settings.json file does not exist yet");
       }
  
       //return our settings object
       return settings;
}

Phones

Using Settings in an App

Settings stored in the phone's config file

Settings entered via your app

Return to Documentation Home I Return to Sangoma Support