iOS - Module Whitelisting

When releasing or updating your iOS module for Q2MobileApp, understanding the whitelisting process is essential for ensuring compatibility and controlled deployment across Financial Institution (FI) app builds.

Policy Change for 26.5.0 and Up

Starting with Q2MobileApp iOS 26.5.0, any brand-new module must begin at version 1.0.0. For these new modules, no explicit whitelisting is required from 1.0.0 until the next major version. In practice, that means 1.x releases do not need explicit whitelisting, and the next explicit whitelisting point is 2.0.0.

📋 Quick Reference

Version Update	Q2MobileApp < 26.5.0	Q2MobileApp 26.5.0+
Initial (1.0.0)	Project-specific	❌ No, for brand-new modules
Patch (1.0.0 → 1.0.1)	❌ No	❌ No
Minor (1.0.0 → 1.1.0)	✅ Yes	❌ No, until next major
Major (1.0.0 → 2.0.0)	✅ Yes	✅ Yes

Key Point: For Q2MobileApp iOS 26.5.0+, a new module must start at 1.0.0, and all 1.x releases are available without explicit whitelisting. Explicit whitelisting is required again at the next major version.

Why whitelisting is required

1. Controlled Release Management

Whitelisting allows Q2MobileApp to control which module versions are available in each app release. This prevents unintended updates and ensures only tested and approved versions are distributed to FIs.

2. Compatibility Assurance

Before Q2MobileApp iOS 26.5.0, major and minor version updates often required explicit whitelisting to control adoption. For 26.5.0+, new modules that begin at 1.0.0 can move through 1.x without explicit whitelisting, while the next major version still requires review to validate compatibility and reduce integration risks.

3. Version Handling for 26.5.0+

For new modules introduced in Q2MobileApp iOS 26.5.0+, version 1.0.0 is the required starting point. From 1.0.0 through all 1.x updates, the app can pick up releases without explicit whitelisting. The first version that requires explicit whitelisting again is the next major release, such as 2.0.0.

4. FI Build Consistency

When an FI rebuilds their app targeting a specific Q2MobileApp version, only the module versions allowed for that app release will be included. For Q2MobileApp iOS 26.5.0+, that includes 1.x versions for brand-new modules without explicit whitelisting, while major version changes still require explicit approval. This ensures consistency and prevents unexpected module upgrades in production environments.

Version Flow Diagram

Whitelisting Matrix

Update Type	Whitelisting Required	Auto-Picked by App	Notes
Initial 1.0.0 on 26.5.0+	No	Yes	Required starting version for any brand-new module
Patch within 1.x	No	Yes	Auto-picked
Minor within 1.x	No	Yes	No explicit whitelisting until next major
Next major (2.0.0)	Yes	No	Must be explicitly whitelisted

Decision Guide

Use this flowchart to determine if your module update requires whitelisting:

Version Timeline Example

Here's how different version updates flow through the whitelisting process:

Real-World Scenarios

1. New Module Starting Version Scenario:

   • ✅ A brand-new module for Q2MobileApp iOS 26.5.0+ starts at 1.0.0
   • ✅ No explicit whitelisting is required for that initial 1.0.0 release
   • ✅ FI builds can consume the module without waiting for a whitelist entry

2. Minor Update Scenario:

   • ✅ You release 1.1.0 (new features within the same major line)
   • ✅ For Q2MobileApp iOS 26.5.0+, explicit whitelisting is still not required
   • ✅ FI builds can continue to consume the latest 1.x version automatically

3. Major Update Scenario:

   • ❌ You release 2.0.0 (breaking changes)
   • ❌ Requires explicit whitelisting and extensive testing
   • ✅ Available only in future Q2MobileApp releases after approval

---

Key Takeaways

Quick Summary

• New modules on 26.5.0+: Start at 1.0.0
• All 1.x updates on 26.5.0+: ✅ No explicit whitelisting needed
• Next major update (2.0.0): ❌ Requires explicit whitelisting
• FI consistency: Builds always use the same module versions for a given Q2MobileApp release

Next Steps

1. Planning an update? Use the Decision Guide above
2. Need whitelisting? Contact the Q2 team when introducing the next major version
3. Questions? Review the Version Timeline Example for scenarios

Benefits of this process:

• 🔒 Controlled deployments across all Financial Institution apps
• 🔄 Automatic patch updates for critical bug fixes
• 🧪 Thorough testing for feature and breaking changes
• 📈 Predictable release cycles aligned with Q2MobileApp schedule