Skip to main content

Troubleshooting the Mobile Apps Generation

OutSystems

Troubleshooting the Mobile Apps Generation

This article contains information that is intended to help in the troubleshooting of issues when generating mobile apps to native platforms.

Note:

Common Issues

This section contains some issues that are frequent and may be of help in troubleshooting mobile generation problems, namely:

Using an Invalid iOS Certificate

Sometimes there are issues with the iOS certificates that can block the mobile app generation. Check the log files and one of the following situations may be happening:

  • The certificate entered in Service Studio is not compatible with the provisioning profile also introduced in Service Studio.
    We recommend following the steps in this article.

  • The certificate is not valid for code signing.
    Check if the certificate was revoked or has expired.

Targeting the Wrong Version of a Native SDK

Each MABS version that is used for generating a mobile app targets a given native SDK version, in both iOS and Android. At the same time, plugins can depend on different versions of these native SDKs.

In the following example (in the Extensibility Configurations of the module), we are using some Cordova preferences to change the native SDK in an app to target Android SDK 22.

In this case we were using MABS 5.0 and its specifications in MABS versions tells us that the version 28 of the Android SDK is required. So, we must change the value to version 28 to be able to submit the app to the Play Store.

Although there are Cordova preferences to force the version of the native SDKs, the best option is to adapt the plugin to the target SDK version of the MABS specifications.

Not Using a Tagged Version of a Plugin

It’s recommended that we use a tagged version of a plugin. If not, we’ll be always using the latest version of the master branch directly. It means that we’ll be consuming a version of the code that is not stable, because developers might be constantly pushing changes to the main branch.

For instance, with GitHub repositories we should use <GitHubLink>#<TagVersion> as the following example shows in the Extensibility Configurations of the module:

Not Using Tagged Versions of Plugin Dependencies

If the plugin dependencies do not target a specific version of a library, the latest version of that library will be fetched, making the outcome of the native generation inconsistent.

For example, a Google Analytics plugin is using play-services-analytics, but allows any version to be used, as can be seen in the following section of its plugin.xml file:

The “+” sign allows the latest version available to be used when generating the app, but if major changes are done to play-services-analytics, it might become incompatible with the MABS requirements or other plugins.

Keeping these entries with a working version will ensure that results are predictable.

This is just one example, but you may find more entries also used with the same purpose (of obtaining a plugin dependency) using the "+" in their specification. This includes other dependency entries in the same plugin.xml file and dependency blocks in Gradle files.

Defining the Same Meta-data Tag More than Once

Sometimes a meta-data tag can be defined more than once with different values. A typical situation happens with plugins when they create or modify the AndroidManifest.xml file and, in there, redefine and override the value of a meta-data tag with the same key.

As an example, this log file shows a conflict caused by a plugin overriding the value of the SOME_APP_KEY meta-data tag, which was already defined by its own library as a string resource:

* What went wrong:
> Manifest merger failed : Attribute meta-data#SOME_APP_KEY@value value=(1234567890) from AndroidManifest.xml:18:54-130
    is also present at [com.some.some:library:1.2.3] AndroidManifest.xml:22:13-47 value=(@string/some_app_key).
    Suggestion: add 'tools:replace="android:value"' to <meta-data> element at AndroidManifest.xml:18:9-133 to override.

In this case, a solution would be reviewing the plugin implementation and fixing the override of the value of the meta-data tag.

Conflict with AndroidX Support Libraries

When building an app with a plugin (or a plugin dependency) that is using an AndroidX support library, the support library may not be compatible with the MABS version.

In this type of issues, the log file can contain something like:

* What went wrong:
Execution failed for task ':app:processReleaseManifest'.
> Manifest merger failed : Attribute application@appComponentFactory value=(android.support.v4.app.CoreComponentFactory) from [com.android.support:support-compat:28.0.0] AndroidManifest.xml:22:18-91
    is also present at [androidx.core:core:1.0.0] AndroidManifest.xml:22:18-86 value=(androidx.core.app.CoreComponentFactory).
    Suggestion: add 'tools:replace="android:appComponentFactory"' to <application> element at AndroidManifest.xml:5:5-20:19 to override.

To fix this issue review the implementation of your plugins and look for Gradle dependencies that may be using Android X.

Some situations can also happen with dependencies to Google without the version being locked, like for example:

implementation "com.google.android.gms:play-services-maps:+"`

This means it will use the latest version, which can be Android X. To fix this kind of issue, find the plugin(s) originating dependencies to Android X and lock their version so that they will use a non-Android X version.

In case you are using a plugin version that needs Android X to work, consider upgrading or downgrading that plugin to a version that does not use Android X.

Incompatibility Between Android Support Libraries

Building an app that uses Android support library dependencies targeting different versions can cause mobile generation issues.

Here's an example of the log message when using multiple support libraries with different versions that define different values for the android.support.VERSION meta-data tag:

* What went wrong:
> Manifest merger failed : Attribute meta-data#android.support.VERSION@value value=(25.4.0) from [com.android.support:exifinterface:25.4.0] AndroidManifest.xml:25:13-35
    is also present at [com.android.support:support-v4:26.1.0] AndroidManifest.xml:28:13-35 value=(26.1.0).
    Suggestion: add 'tools:replace="android:value"' to <meta-data> element at AndroidManifest.xml:23:9-25:38 to override.

To resolve this issue upgrade (or downgrade) plugins that can be causing the incompatibility. Alternatively, change MABS to a version that makes it compatible with the Android support libraries used by the MABS built-in plugins.

If the issue remains, modify the plugin(s) implementation to make the problematic dependency versions compatible.

Issues with Google Services Configuration Files

An app that uses Google Services needs to be correctly configured with specific JSON (for Android) or Plist (for iOS) configuration files located in the correct directories. For the plugins that use Google Services, you need to have the configuration files added as Resources in Service Studio.

For example, when using the Google Services plugin and the google-services.json file was not found in the correct directory, the log message is:

Execution failed for task ':app:processDebugGoogleServices'.
> File google-services.json is missing. The Google Services Plugin cannot function without it.

Or, another example, this time with the google-services.json in the correct directory but, in its content, the package name in the JSON does not match the package name of the application:

Execution failed for task ':app:processDebugGoogleServices'.
> No matching client found for package name 'com.some.some'

To solve this issue:

  • Check the plugins documentation to make sure they are being correctly configured
  • Make sure the content of the JSON or Plist files has the right information

If the issue remains:

  • Try using different versions of the plugins, or
  • If MABS was upgraded to version 5.0, modify the plugins to comply with the Cordova-android directory changes described in Troubleshoot the Upgrade to MABS 5.0.

In the specific case of PushWoosh, a supported plugin in the Forge, it requires a ZIP file with the configuration JSON file for Android. Read the plugin documentation for more information.

In the case of a specific supported plugin, PushWoosh, it requires a ZIP file with the configuration JSON file for Android. Read the plugin documentation for more information.

Incompatible Versions of Google Play Services

When building an app that uses multiple dependencies of Google Play Services, their versions can conflict with each other, causing issues in the app generation.

In this example, the log file contains an error message when generating an app with plugins using at least two Google Play services library dependencies that are not compatible:

Failed to capture fingerprint of input files for task ':app:preDebugBuild' property 'compileManifests' during up-to-date check.
> In project 'app' a resolved Google Play services library dependency depends on another at an exact version (e.g. "[11.0.
  0]", but isn't being resolved to that version. Behavior exhibited by the library will be unknown.

To resolve this issue update the plugins to versions that use compatible versions of Google Play services libraries.

Or, if the issue remains, modify the plugins to force the versions of the dependencies to become compatible.

Some Troubleshooting Techniques

This section describes some techniques that can help in troubleshooting mobile generation issues:

Check the Logs

One way of troubleshooting is to look for issues in the log files.

1. Get the Log File

OutSystems logs the generation steps of a mobile app package, including the stack trace with additional details in case of error.

To get this mobile app package generation log, do the following:

  1. If you are in Service Studio, go to the details page of the mobile app and click Application Management... to open the mobile app's page in Service Center console. The page opens in a separate browser.

    Otherwise, open the Service Center console of the environment (https://<your_server>/ServiceCenter), go to Factory » Applications, and click the mobile app name to go to the app details page.

  2. Go to the Native Platforms tab. You will see the information about the latest mobile app package generation for each mobile platform.

  3. Click the Log File icon to save the file.

If you are getting this log by request of OutSystems Support, fetch the file you saved from the local download folder and attach it to your support case.

2. Look for Issues in the Log File

Open the log file and look for the lines with errors. To narrow the search, look for the lines with the timestamp closer to when the error occurred.

Find below a couple of troubleshooting examples.

Examples of Troubleshooting with the Logs

Example 1

While generating the mobile app, the “Error fetching Cordova plugin” error is raised.

By checking the logs there’s a more detailed message:

It shows that the 1.5.0 tag defined in the plugin does not exist in GitHub.

The plugin implementation should be reviewed to use the right tag.

Example 2

Like before, the “Error fetching Cordova plugin” error is raised.

By checking the logs we can see a more detailed message:

In this case the log shows that a configuration archive is missing for the Pushwoosh plugin. The instructions for the plugin state that a “google-services” archive must be included, which ties in with the name of the Cordova hook that failed.

Check the Plugins

When using plugins in mobile apps, they can sometimes be the source of issues. This section provides some guidelines on how to troubleshoot possible issues related with plugins.

Make Sure that Plugins Comply with MABS

When using plugins, make sure that their implementation complies with the MABS version requirements or, otherwise, they may be a source of problems.

For example, if the plugin.xml file contains engine entries like in the image below, make sure they are compatible with Cordova CLI or Android/iOS Engines:

Find the Plugins Causing Issues

When troubleshooting an app that has plugins, start by finding a plugin that is the root cause of the issues. By setting the focus on a single plugin, it can facilitate the analysis.

This section introduces some techniques to find out which plugin (or plugins) are causing issues.

Reproduce in a Clean OutSystems App

This is the low-code way to try to reproduce issues with plugins. It is typically used when we have a strong hint of which plugin or plugins may be causing problems.

Create a clean app and add plugins, one by one, as follows:

  1. Create a new Mobile app in Service Studio;

  2. Add a plugin to the app and generate the mobile app;

  3. If the problem is reproduced, stop and use the logs to troubleshoot the problem;

  4. Add another plugin and repeat from step 2.

Reproduce in a Clean Cordova Project

This method implies knowledge about working with Cordova projects and a bit of setup work. However, it can reveal to be better than the previous method if working with several plugins and there’s no clue of which one or ones are causing issues, mainly because it’s faster to generate the mobile app.

Create a Cordova project and add plugins, one by one, as follows:

  1. Set up the Cordova environment following the Cordova instructions for the Cordova CLI version found in the MABS version requirements.
    Note: In the case of iOS, you must use a macOS environment;

  2. Create the Cordova project

    cordova create <app_name>
    
  3. Go to the Cordova project folder to execute the command

    cd <app_name>
    
  4. Add a platform:

    cordova platform add <platform>@<engine version>
    

    Where:
    <platform>: is either 'android' or 'ios'
    <engine version>: is the engine version required by the MABS version.

  5. Add a plugin and build the project

    cordova plugin add <plugin_repo_url>
    
    cordova build <platform>
    
  6. If the problem is reproduced, stop and use the logs to troubleshoot the problem

  7. If the problem is not yet reproduced, repeat from step 5.

This method allows testing your plugins against the Cordova Android/iOS Engine of a MABS version. However, mobile apps generated by OutSystems have a native shell with built-in plugins that OutSystems uses internally. This means that this method won’t allow detecting any incompatibility between your plugins and the built-in plugins because they are not installed.

Remove Plugin by Plugin and Generate

Another low-code way of finding out which plugins may be causing issues is removing one by one and generating the app at each removal. If the problem disappears, we will probably have found the plugin that is causing the issue.

Still Having Problems?

If none of the approaches in this document helped troubleshooting the issue, consider opening a support case to get help from the OutSystems Support.

  • Was this article helpful?