Digipass S3 is now DigipassONE. This section is currently being updated to reflect our new name.

Customizing and packaging the Cordova App SDK

  • Updated on Apr 3, 2026
  • Published on Nov 26, 2025
  • 4 minute(s) read
Prev Next

Cross-Platform UI configuration

The Digipass S3 App SDK allows you to make small or large modifications to its built-in UI without programming. By editing a cross-platform JSON UI configuration file, you can:

  • Replace strings.

  • Localize your app.

  • Display a friendly name for an authentication method.

  • Give a title, description and icon to an authenticator.

  • Explain to the user why an additional authentication method is required.

  • Modify a style to affect one or many different views.

  • Use your own images.

  • Handle Dark Mode.

See App UI Customization for instructions to create the JSON UI configuration file. Read on to see how to pass that JSON UI configuration file to the App SDK.

The App SDK loads your JSON UI configuration file at runtime. Store your UI Configuration file locally, or pass your entire UI configuration to the App SDK in a JSON formatted string.

Configure the web UI

To direct the App SDK to your JSON UI configuration file, add the following code to your Cordova app.

NNLUiConfig.addUiConfig("<source of your UI configuration file>", false)

Specify the source of your UI configuration file with one of the following:

  • the URL where the configuration file resides

  • the configuration object itself

  • the entire configuration in a JSON formatted string

To localize the strings that the App SDK displays in your app, pass true into second, localize, parameter and prepare additional UI configuration files as described in Localizing Your App. A localized UI configuration file can be applied only if you pass a URL as the source parameter when you call addUiConfig().

Configure the authenticators' native UI

To apply the same JSON UI configuration to native UIs presented by authenticator plugins, make a copy of the JSON UI configuration file and store the copy in the application's native resources.

Add the following line into the config.xml file in the appropriate platform section of your application.

<resource-file src="<path of your UI configuration file>.json" custom="true" />  

To localize the authenticators' native UI just add another resource pointing to the localized file as follows.

<resource-file src="<path of your UI configuration file>_<locale>.json" custom="true" />

Any image or icon referenced in JSON UI configuration should be also added to the application resources.

Android

Adding your app to the server

Prior to releasing your completed Android app, you must add it to the Digipass S3 Server. Ensure that any legal notices included with your app contain the proper attributions to third-party source licenses.

  1. Navigate to the Cordova project directory. For example: cordova_bom_9.5.0.xx/app_tutorial

    Create an APK for the app by running the following command.

cordova build android --release -- --packageType=apk

You can find the APK file under ../app_tutorial/platforms/android/app/build/outputs/apk/release

Alternatively, you can build the release application using the AAB format.

cordova build android --release

You can find the AAB file under

../app_tutorial/platforms/android/app/build/outputs/bundle/release

  1. Use the Admin Console to Add Your App to the Server. Refer to Configuring an Android App.

About Android resources

Cordova uses the appropriate resources under the directory:

app_tutorial/platforms/android/res

This contains all the resources in subdirectories. For example, you might want to provide a different UI layout depending on the screen size.

Layout configuration

Place your customised UI layout files under this folder:

app_tutorial/platforms/android/res/layout

In the example of PIN UI customization, the appropriate nnl_asm_pin_ui.xml and nnl_asm_pin_ui_landscape.xml should be updated with the required UI. Note that when you move the layout xml file to the res/layout folder, also move all drawable dependency files to the res/drawable folder. In addition, move strings_pin_asm.xml to the res/values folder.

Excluding database files from backup

Beginning with Android 6.0 (API 23), Android provides the Auto Backup for Apps feature enabled by default. The ASM database files must be excluded from the backup because data in these files are encrypted with a key located in the keystore. The key does not survive the application uninstall/install cycle. As a result, if an old database is restored, the application cannot use it.

Database files are stored in the files subfolder of the application local folder. The following fragment shows how they can be excluded from backup.

  1. Create an XML file, like backuprules.xml, describing the backup content in the project root directory. This is the same directory where the file config.xml file is located. The following example excludes the database files for the authenticators with the 0001#0001 and 0001#0002 AAIDs. For other AAIDs, specify the correct path attribute. If there are .dat files, such as 0001#0001.dat, exclude those as well.

    In the backup_rules.xml file:

<?xml version="1.0" encoding="utf-8"?>
<full-backup-content>
    <exclude domain="file" path="0001#0001"/>
    <exclude domain="file" path="0001#0001.dat"/>
    <exclude domain="file" path="0002#0002"/>
    <exclude domain="file" path="0002#0002.dat"/>
</full-backup-content>

  1. Update the config.xml file to merge the new backup rules into the AndroidManifest.xml file:

<platform name="android">
    <resource-file 
        src="backuprules.xml"
        target="res/xml/backuprules.xml" />
    <edit-config 
        file="AndroidManifest.xml" 
        mode="merge" 
        target="/manifest/application">
        <application android:fullBackupContent="@xml/backuprules" />
    </edit-config>
</platform>

iOS

Adding your app to the server

Prior to releasing your completed iOS app, you must add it to the Digipass S3 Server. Ensure that any legal notices included with your app contain the proper attributions to third-party source licences.

  1. Navigate to the Cordova project directory. For example: cordova_bom_9.5.0.xx/app_tutorial

    Replace the com.noknok.cordovatutorialapp in config.xml with com.noknok.cordovatutorialapp.store.

Run build via the following command.

sh build_ios.sh

Create an IPA file for the app by running the following command.

cordova build ios --release --buildConfig

You can find the IPA file in:

.../Cordova/Code/cordovatutorialapp/platforms/ios/build/device/Cordovatutorialapp.ipa

  1. Use the Admin Console to Add Your App to the Server. Refer to Configuring an iOS app. Follow the instructions for configuring an iOS app.