Android - Native Login Module

The Native Login module is the updated, modern login experience built from the ground up using native Android with Jetpack Compose. It replaces the legacy login page with a fully native implementation that provides improved performance, better accessibility, and a more polished user experience.

Enabling Native Login

There are two steps to enable Native Login: adding the dependency to your build.gradle and configuring settings.json.

1. Add the Dependency

In your DevApp's build.gradle, add the Native Login dependency to the dependencies block alongside your other Q2 dependencies:

dependencies {
    implementation "com.q2.app.core:core:$q2Version"
    implementation "com.q2.nativelogin:nativelogin:$q2Version"
    // ... other dependencies
}

2. Configure settings.json

In your DevApp's settings.json, you need to do two things:

a) Add the Native Login module to the sdk_modules array:

{
  "sdk_modules": [
    {
      "name": "native_login",
      "classPath": "com.q2.nativelogin.NativeLoginEntryPoint",
      "include": ":modules:authentication:nativelogin",
      "identifier": "native_login",
      "data": {},
      "enabled": true
    }
  ]
}

b) Set the nativeLogin flag to true at the top level of the JSON:

{
  "applicationName": "Dev App",
  "package": "com.q2.devapp",
  "nativeLogin": true,
  "sdk_modules": [
    ...
  ]
}

tip

Make sure both the "enabled": true property inside the module config and the top-level "nativeLogin": true flag are set. Both are required for Native Login to activate.

Customizing the UI

The login screen's buttons and footer links are defined per-FI and served from the Q2Config filemap. The module reads them at runtime; nothing about them is baked into the app.

Changed in 26.10.0

loginButtons and ualButtons used to be read from a uiConfiguration array in this module's settings.json data block. They are now read from Q2Config, like footer links already were. A uiConfiguration array left in settings.json is inert. It produces no error and no buttons. Move the definitions to the FI's alternate-login-buttons.json asset.

Configuration Types and Sources

Type	Where it appears	Filemap key
loginButtons	Below the login form on the main login screen	assets/alternate-login-buttons.json
ualButtons	On the User Access List (Add Another Account) screen	assets/alternate-login-buttons.json
footerLinks	The footer area	assets/footer-links.json

Example Configuration

alternate-login-buttons.json:

{
  "uiConfiguration": [
    {
      "type": "loginButtons",
      "items": [
        {
          "displayName": "_t.mob.enrollnow",
          "link": "https://your-bank.com/enrollment",
          "linkType": "url",
          "target": "self",
          "buttonStyle": "secondary",
          "order": 1
        },
        {
          "displayName": "_t.main_page.contactUs",
          "link": "5124444444",
          "linkType": "phone",
          "buttonStyle": "text",
          "platformSpecifier": 3,
          "order": 2
        }
      ]
    },
    {
      "type": "ualButtons",
      "items": [
        {
          "displayName": "_t.mob.enrollnow",
          "link": "https://your-bank.com/enrollment",
          "linkType": "url",
          "target": "self",
          "buttonStyle": "secondary"
        }
      ]
    }
  ]
}

Configuration Properties

Each item in the items array supports the following properties:

• displayName (required): The text displayed on the button or link. Can be a translation key (e.g., _t.mob.enrollnow) or plain text.
• link (required): The destination URL, phone number, or relative path.
• linkType (required): The type of link. Valid values:
  • "url": Web link
  • "phone": Phone number
• target (optional, for URL links): How the link should open:
  • "self": Opens in the app's webview (default)
  • "browser": Opens in external browser
  • "popup": Opens in a popup/modal webview
• buttonStyle (optional, for buttons): The visual style of the button:
  • "secondary": Standard button style
  • "text": Text-only button (no background)
• platformSpecifier (optional, added in 26.10.0): Bitmask controlling which platforms render the item. Android 0b001 (1), iOS 0b010 (2), Browser 0b100 (4); combine by adding, so 3 is Android + iOS and 7 is all three. Omit the field to render everywhere. An item whose mask omits the Android bit is dropped on Android.
• order (optional, added in 26.10.0): Ascending sort key within the group. Items with no order sort after items that have one.

warning

order is not cross-platform symmetric

Android sorts an item with no order last. iOS treats a missing order as 0, which sorts it first. If the same asset serves both platforms, set order explicitly on every item.

Translation Keys

You can use translation keys (prefixed with _t.) for displayName values to ensure your buttons and links are properly localized for different languages.

Learn More

For more information about configuring modules and the settings.json file, see Configuring settings.json.