Android - Setting Up Your settings.json

The settings.json file, located under devapp/assets/conf/settings.json, is a key configuration file used to define the behavior of your DevApp during development. It closely mirrors the configuration of the Q2 Mobile App, ensuring that your module behaves consistently both in development and in the final app. By correctly setting up this file, you ensure that your DevApp environment is properly configured to run the modules you are working on.

This guide explains the structure of the settings.json file, what each section does, and how to modify it to suit your development needs.

Overview of settings.json

The settings.json file can seem complex at first glance, but it's quite straightforward once you understand its structure. Here’s a breakdown of its sections and how you can configure them:

Key Sections in settings.json

• applicationName
  This is the name of the application. For most cases, you can ignore this setting.

• package
  This defines the application’s package. Unless otherwise informed, leave this set to com.q2.devapp.

• targetURLBase
  This is the base URL that points to your development environment (such as your sandbox, SDX, or any other environment you are working against). In most cases, this should point to your sandbox environment.

• targetPageName
  This is typically set to "uux.aspx", and generally, you should leave it as is unless otherwise informed. It represents the base page for your application, but it can be extended with additional parameters if needed.

• sdk_modules
  This is an array of objects, and it’s one of the most important parts of the configuration. It defines the modules that will be loaded into the DevApp. When you develop a new module, you will add it to this section. We will discuss how to configure this section in detail below.

• mob_modules
  This is another array of objects, similar to sdk_modules. However, this section is reserved for core application modules and should not be modified for custom modules. Leave this section as it is unless otherwise told.

• nativeLogin
  This is a boolean flag indicating whether native login is enabled. You can leave this set to true.

• push
  This boolean flag enables or disables push functionality for your application. Set this to true if push notifications are required for your project. Note that you will also need to enable the sdk_modules PushEnrollment and the mob_modules Q2PushService modules for push notifications to function correctly.

Example of settings.json

Below is an example of a typical settings.json file for DevApp:

{
  "applicationName": "Dev App",
  "package": "com.q2.devapp",
  "targetURLBase": "https://stack.q2developer.com/sdk/native/ardent",
  "targetPageName": "uux.aspx",
  "sdk_modules": [
    {
      "name": "com.q2.package_name_my_module",
      "identifier": "com.q2.package_name.my_module",
      "classPath": "com.q2.package_name.my_module",
      "enabled": true,
      "data": {
        "my_data_key": "my_data_value"
      }
    },
    {
      "name": "PushEnrollment",
      "identifier": "pushEnrollment",
      "classPath": "com.q2.push.enrollmentprompt.EntryPoint",
      "include": ":modules:push",
      "data": {},
      "enabled": false
    }
  ],
  "mob_modules": [
    {
      "id": 1,
      "name": "Q2PushService",
      "moduleType": "push",
      "classPath": "com.app.q2.modules.push.q2_push_service.Q2PushService",
      "include": ":modules:q2_push_service",
      "googleServicesRequired": "true",
      "data": {},
      "enabled": false
    }
  ],
  "nativeLogin": true,
  "push": false
}

Understanding the sdk_modules

The sdk_modules section contains an array of objects that define each module to be loaded into the DevApp. Let’s break down the structure of each module:

Key Fields for Each Module in sdk_modules

• name
  This is the name of the module. It should typically be the same as your identifier and classPath, but it can be something else. It must be unique and only contain letters, periods, and underscores. Ideally, avoid uppercase as this is case-sensitive.

• identifier
  This field is used by Tecton and other external sources to locate and call the module. It uniquely identifies your module. It is best to match it with the classPath, but for iOS parity, it can be different. Ideally, avoid uppercase as this is case-sensitive.
  Example: "com.q2.package_name.my_module"

• classPath
  The path to the main class of your module. This must match the full package path, including the class name.
  Example: "com.q2.package_name.MyModule"

• enabled
  This boolean flag determines whether the module is active in the application. If set to true, the module is included in the build. If set to false, it will be excluded.

• data
  This is an object where you can pass additional configuration data for the module. This is useful if your module requires custom build-time data.
  Example: If your module will be installed in several FI applications and you need to pass a key for each one, this is how you can do that.

Example Module Configuration

{
  "name": "com.q2.package_name_my_module",
  "identifier": "com.q2.package_name.my_module",
  "classPath": "com.q2.package_name.my_module",
  "enabled": true,
  "data": {
    "rtu_deeplink_key": "my_deeplink_uri"
  }
}

When Creating a Module

When you create a new module class, it must be added to the sdk_modules section for it to be loaded and used by DevApp. You’ll also need to ensure that all necessary fields (name, identifier, classPath, etc.) are correctly populated.

DevApp comes with several example modules, which you can reference to understand the structure. However, once you understand how to add and configure your module, make sure to delete the example entries to avoid confusion.

Key Considerations

• mob_modules should not be modified for custom modules.
  This section is reserved for core functionality like push notifications and other built-in features. If you are working on a custom module, you should only focus on sdk_modules.

• nativeLogin and push flags can generally remain set to true
  unless you are specifically told to disable them.

• targetURLBase should ideally point to your sandbox environment
  to match your development setup. However, it can also point to other environments if needed.

Conclusion

By understanding and configuring the settings.json file, you ensure that your DevApp setup is correctly aligned with the Q2 Mobile App environment. This configuration allows you to maintain a consistent development experience and ensures that your modules are properly integrated into the app.