iOS - Setup DevApp

As part of setting up module, you will be already configured with Q2DevApp within your module folder.

q2-demo-ios
├── Package.swift
├── q2-demo-ios
│   ....
├── Q2DevApp
│   └── Q2DevApp.xcworkspace
├── ....
└── settings.json

In order to use specific online banking URL tied to your sandbox update settings.json located at root of the repository.

Scene Delegate Requirement (26.3.0+)

Starting with iOS Mobile SDK 26.3.0, Q2DevApp must define UIApplicationSceneManifest and include a local Q2DevAppSceneDelegate that inherits Q2CoreSceneDelegate.

For existing projects cloned from older DevApp templates, update Q2DevApp/Info.plist and add Q2DevAppSceneDelegate as shown in Scene Delegate Reference.

Overview of settings.json

The settings.json file, located at root of the repo is a key configuration file used to define the behavior of your Q2DevApp during development. It closely mirrors the configuration of the Q2MobileApp release consumed by an FI, ensuring that your module behaves consistently both in development and in the final app. Q2MobileCore powers Q2MobileApp, and Q2MobileSDK provides the interfaces and module types used by FI modules. By correctly setting up this file, you ensure that your Q2DevApp 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.

Key Sections in settings.json

• targetURLBase This is the base URL that points to your online banking environment (such as your sandbox, sales demo (a.k.a. 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. For current built-in Universal Link handling, the incoming link path must contain this value.

• universalAndAppLinkAssociatedDomain This is the host name used for current built-in Universal Link matching and for the Associated Domains entitlement. The incoming link host must match this configured domain for Q2MobileApp-managed Universal Links.

• enableDevMode This is typically set to true in order to enable developer mode to view console log in Safari Javascript console and some other developer feature.

• 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.

Example of settings.json

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

{
    "targetURLBase": "https://stack.q2developer.com/sdk/native/ardent",
    "targetPageName": "uux.aspx",
    "enableDevMode": true,
    "modules": [
       ...
    ]
}

Understanding the modules

You can read further around what should go in module by going here: Configure Settings for Module

Deep Linking Prerequisites

Use this checklist when testing deep links in Q2DevApp or Q2MobileApp.

For built-in FI app deeplink contracts, route semantics, and module-owned link guidance, see Deep Linking.

For FI and Q2 Universal Links setup, domain onboarding, and Apple App Site Association ownership, see Universal Links Setup Guide.

• urlScheme
  • Required for custom URL scheme testing.
  • The same value must be present in settings.json and the app Info.plist CFBundleURLSchemes.
• targetPageName
  • Required for current built-in Universal Link matching.
  • The incoming URL path must contain this value, which is typically uux.aspx.
• universalAndAppLinkAssociatedDomain
  • Required for current built-in Universal Link matching.
  • The incoming URL host must match this domain.
• Associated Domains entitlement
  • Required for Universal Links.
  • Must include applinks:{domain} for the target host.
• Provisioning profile capability
  • Required for Universal Links in signed builds.
  • The provisioning profile must include Associated Domains capability.
• Apple App Site Association file
  • Required for Universal Links to open the app reliably.
  • The AASA file must include the exact app ID and supported paths for the build being tested.

important

Current built-in iOS Universal Link handling in Q2MobileApp is fragment-based. For Q2MobileApp-managed FI app deeplinks, the accepted shape is effectively:

https://{associated-domain}/.../{targetPageName}#/route

If #/ is missing, Q2MobileApp will not treat the link as a built-in FI app deeplink.

Scene Delegate Reference

The required scene delegate wiring for Mobile SDK iOS 26.3.0+ is shown below for reference.

Info.plist

Make sure your Q2DevApp target Info.plist includes UIApplicationSceneManifest:

Q2DevApp Info.plist

<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).Q2DevAppSceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

Q2DevAppSceneDelegate

Add a local scene delegate class to the Q2DevApp app target:

Q2DevAppSceneDelegate.swift

import UIKit
import Q2MobileCore

class Q2DevAppSceneDelegate: Q2CoreSceneDelegate {}

Why This Is Required

• Q2DevApp now relies on scene-based lifecycle callbacks
• deeplink and lifecycle testing should run through the same app lifecycle model used by the current SDK
• without this setup, Q2DevApp may not initialize or route lifecycle events correctly

Key Considerations

• nativeLogin and push flags can generally remain set to false 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 Q2DevApp setup is correctly aligned with the Q2MobileApp environment. This configuration allows you to maintain a consistent development experience and ensures that your modules are properly integrated into the app.

Once you have updated your settings.json to reflect your environment, you are ready to configure settings for module.