Skip to main content

Android - Local Development

This guide walks through the day-to-day development workflow for building Q2 Mobile SDK modules. Follow these steps when creating new features or updating existing modules.

Overview​

The local development cycle consists of:

  1. Create a feature branch - Branch from master for your work
  2. Develop your module - Write code using the DevApp
  3. Test locally - Verify functionality in DevApp
  4. Test with obfuscation - Ensure your module works with R8/ProGuard
  5. Ready for review - Submit merge request when testing is complete

1. Create Feature Branch​

Start by creating a new branch from the master branch:

git checkout master
git pull origin master
git checkout -b your-feature-branch-name

Branch naming:

  • Use any naming convention that works for your team
  • No specific format required
  • Examples: feature/biometric-auth, bugfix/payment-crash, JIRA-123-add-analytics
tip

Always branch from master, not from production or other feature branches. This ensures you're starting with the latest certified code.

2. Develop Your Module​

Set Up Your Module in DevApp​

If this is a new module, configure it in your DevApp's settings.json:

  1. Open settings.json in your DevApp project
  2. Add your module configuration in the appropriate section (UIModules, MethodModules, etc.)
  3. Include any necessary data {} configuration your module needs

For detailed settings.json configuration, see Settings JSON Guide.

Write Your Code​

Develop your module following the appropriate module type guide:

Development best practices:

  • Make incremental changes and test frequently
  • Follow Android and Kotlin best practices
  • Keep your code secure (no hardcoded credentials, use HTTPS, proper data storage)
  • Handle errors gracefully
  • Log appropriately for debugging (but remove debug logs before submitting)

3. Test Locally with DevApp​

The DevApp provides a near-production environment for testing your module during development.

Run DevApp​

  1. Open your module project in Android Studio
  2. Select your DevApp configuration
  3. Run the app on an emulator or physical device

Test Your Module​

For MethodModules and UIModules:

  • Your module is called from JavaScript/Tecton code
  • Use Chrome DevTools to debug the JavaScript bridge
  • See Module Debugging for Chrome inspect instructions

For LifecycleModules:

  • Module starts automatically when the app launches
  • Test lifecycle events (app start, foreground, background, etc.)

For PushReceiverModules:

  • Test with real push notifications
  • See Firebase Setup for notification testing

Common Testing Scenarios​

Test these scenarios thoroughly:

  • Happy path - Normal usage flows
  • Edge cases - Empty data, null values, boundary conditions
  • Error scenarios - Network failures, invalid input, permission denials
  • Different device configurations - Various Android versions, screen sizes, locales
  • State management - App backgrounding, orientation changes, low memory
important
Test Thoroughly Locally

The more testing you do locally, the fewer issues you'll encounter later in the certification build phase. It's much faster to iterate locally than to wait for certification builds.

4. Test With Obfuscation (Critical!)​

Before submitting your merge request, you must test your module with R8/ProGuard obfuscation enabled. This is a required step that simulates the production build environment and catches issues that only appear with code shrinking and obfuscation.

danger
This Step Is Mandatory

Production builds use R8 obfuscation. Without proper testing and consumer rules:

  • Your module will crash in production with ClassNotFoundException or NoSuchMethodException
  • JSON serialization will break
  • Reflection calls will fail
  • Q2's code review will reject your merge request if consumer rules are missing or inadequate

Do not skip this step. Test with obfuscation enabled before submitting your merge request.

Complete ProGuard Testing Guide​

For comprehensive instructions on:

  • Why ProGuard/R8 testing is critical
  • How to enable minify in DevApp
  • How to create consumer rules (with examples)
  • How to test your rules
  • Common issues and how to fix them
  • What rules will be rejected during code review

See: Consumer ProGuard Rules - Complete guide with step-by-step instructions

Quick Summary​

  1. Enable minifyEnabled true in your DevApp's debug build configuration
  2. Create/update consumer-rules.pro in your module with specific keep rules
  3. Build and test all functionality
  4. Fix any crashes by adding appropriate rules
  5. Never use keep-all rules (they will be rejected)

4.5. Third-Party Libraries (If Applicable)​

If your module uses private third-party libraries or libraries not available on standard Maven repositories (Google, Maven Central), you must submit them to Q2 for hosting.

note
When This Applies

You only need to follow this step if:

  • Your module uses private/proprietary libraries
  • Your module uses libraries from Maven repositories Q2 cannot access
  • The library is not available on Google Maven or Maven Central

Standard public libraries from Google/Maven Central work without any special steps.

Q2 Library Hosting Process​

For security reasons, the Q2 Mobile App does not allow arbitrary Maven repositories. If you need a private library:

  1. Prepare library artifacts - Collect the .aar and .pom files
  2. Submit to Q2 - We'll upload them to your repository's package registry
  3. Reference in your module - Use standard Maven dependency syntax

For complete instructions on:

  • How to prepare library artifacts
  • POM file format requirements
  • Submission process
  • How to reference hosted libraries

See: Third-Party Libraries - Complete submission guide

Important: Submit third-party libraries early in your development process to avoid delays during the certification phase.

5. Commit Your Changes​

Once your module is working correctly with obfuscation enabled:

Stage and Commit​

git add .
git commit -m "Add biometric authentication to payment module

- Implemented fingerprint and face recognition support
- Added biometric configuration in module data
- Updated consumer rules for new security classes
- Tested with minify enabled"

Good commit messages:

  • Use present tense ("Add feature" not "Added feature")
  • Briefly describe what and why
  • List key changes in bullet points for larger commits

Push to Remote​

git push origin your-feature-branch-name

6. Ready for Merge Request​

When you've completed development and testing:

  1. Verify everything is committed and pushed
  2. Double-check obfuscation testing - This is the most common source of issues
  3. Review your changes - Look at your diff to catch any debug code or commented sections
  4. Prepare module data configuration - Document any changes to your data {} structure

Next Steps​

Proceed to create your merge request and submit for Q2 review:

  1. Create merge request from your branch to master
  2. Submit support ticket notifying Q2
  3. Include module data configuration changes (if any)

For detailed instructions, see Development Workflow for the complete end-to-end process.

Development Tips​

Use Version Control Effectively​

  • Commit frequently with meaningful messages
  • Don't commit large binary files
  • Review your changes before committing
  • Use .gitignore to exclude build artifacts

Keep Security in Mind​

  • Never hardcode API keys, passwords, or tokens
  • Use HTTPS for all network requests
  • Store sensitive data securely (Android Keystore)
  • Validate user input
  • Handle permissions properly

Write Maintainable Code​

While Q2 doesn't review code quality, you're responsible for:

  • Clear, readable code
  • Appropriate comments for complex logic
  • Consistent code style
  • Unit tests (if applicable to your workflow)

Performance Considerations​

  • Don't block the main thread
  • Use background threads for network/database operations
  • Optimize memory usage
  • Profile your code for performance bottlenecks

Handle Dependencies Properly​

If your module uses third-party libraries:

  • Document all dependencies
  • Ensure they're compatible with the Q2 Mobile SDK
  • Include proper consumer rules for each dependency
  • See Third-Party Libraries for submission requirements

Troubleshooting​

DevApp won't build after adding my module​

Common causes:

  • Missing dependency declaration
  • Syntax error in settings.json
  • Incorrect module class path
  • Missing required module methods

Solution: Check Android Studio's build output for specific errors.

Module works in DevApp but crashes with minify enabled​

Cause: Missing or inadequate ProGuard consumer rules.

Solution: Add specific keep rules for classes/methods that are accessed dynamically or via reflection. See Consumer ProGuard Rules.

JavaScript can't call my module​

Cause: Module not properly registered or identifier mismatch.

Solution:

  • Verify settings.json configuration
  • Check module identifier matches between settings.json and Tecton code
  • Use Chrome DevTools to inspect available modules: __MOB.modules
  • See Module Debugging

Changes not appearing after rebuild​

Cause: Gradle cache issues.

Solution:

  • Try "Build → Clean Project" in Android Studio
  • Invalidate caches: "File → Invalidate Caches / Restart"
  • See Managing Gradle Caches

Additional Resources​

Need help? Contact Q2 support through q2developer.com.