Best practices, FAQ and tips for developing hybrid apps with Hybrid App Toolkit

This blog post contains parts that were previously covered in the post What’s new with Hybrid Application Toolkit in 2019, combined with new information.

The goal is to guide you with your app development and for you to be able to resolve some of the common challenges by yourself. We don’t need to reinvent the wheel or bump into the same issue someone else faced already. Let’s get more productive.

Before we start, I have one recommendation, which is the same as on all my other blog posts related to Hybrid Application Toolkit:

When you start developing a new mobile app, we strongly recommend that you consider developing this with either MDK (Mobile Development Kit) for cross platform applications, or our native SDKs (SAP Cloud Platform SDK for iOS or SAP Cloud Platform SDK for Android).

Develop a web app

The most productive environment to develop your (mobile) app is in the cloud, as a web application. You should avoid developing code that is only able to run on a mobile device. It is much easier to test and debug your (UI5) application in your favourite browser. Mobile devices add more challenges due to limitations in memory, processing capacity, connectivity, building/packaging, downloading, screen size, etc. The development cycles/roundtrips are much shorter for web development. The debugging tools in ‘desktop’ Chrome/Safari/Firefox are pretty advanced; please make use of it!

Some recommendations:

  • Keep your code as much as possible common across your web app and mobile app. We have seen customer support requests where some parts of the code were unnecessary different. The customer mentioned the app was running fine as a web app, but failed as a mobile app. You won’t be able to debug your app on the web, when your code only runs on mobile.
  • In case you are making use of APIs that are only available in the mobile environment, ensure those calls are ‘guarded’ with checks on whether the API is available before calling it. This ensures your web app doesn’t break while running in a desktop browser.
  • Code that is handling data queries (OData) should be the same across web app and mobile app. There is no need to have this implemented in a mobile specific way. The only tricky part might be regarding the user, but this should not affect the other parts of the code.
  • Make use of events instead of polling or checking for status.
  • Keep it as simple as possible.

Migrating your app across multiple spaces (for Dev, QA, Prod)

You are developing an app in a Development space and now you need to move this into a QA space for testing, followed by a Prod space for production. How can you make use of the same project structure and App Id.

The challenge here is that when you use our Cloud Build Service (through SAP Mobile Services), it will automatically generate a new application, with new App Id, in SAP Mobile Services (but only if there is none already). This will require you to change various things manually and results in maintenance issues. To avoid this, please follow the following process:

  1. Create a project in SAP Web IDE Full-Stack and build the mobile app in this (Dev) environment.
  2. Push the project content, including the file .che/project.json into your Git repository. Note: the .che folder might be hidden. Use the option in SAP Web IDE Full-Stack to show hidden files.
  3. Go to the SAP Mobile Services Admin cockpit and export the app that was generated in step 1.
  4. Switch to your QA environment and open the SAP Mobile Services Admin cockpit there. Import the app you’ve exported in step 3.
  5. Open SAP Web IDE Full-Stack in this QA environment and clone the Git project into your workspace.
  6. Build the mobile app using our Cloud Build Service. Since you’ve already imported the app into SAP Mobile Services in step 4, there is no need to create a new one. Hence, the same App Id will be used.
  7. Your QA team might report issues found in the QA environment. As a developer, continue your development and bug fixing in the Dev environment. Push your code changes into your Git repository.
  8. To get the latest updates into the QA environment, pull the code changes from your Git repository and rebuild the app.
  9. Repeat steps 7 and 8 until you reach a point where things are ready for production.
  10. Switch to your Prod environment and open the SAP Mobile Services Admin cockpit there. Import the app you’ve exported in step 3.
  11. Open SAP Web IDE Full-Stack in this Prod environment and clone the Git project into your workspace.
  12. Build the mobile app using our Cloud Build Service. Since you’ve already imported the app into SAP Mobile Services in step 10, there is no need to create a new one. Hence, the same App Id will be used.
  13. Publish and distribute your app (after testing, of course).

As you can see, you should manage your code in a Git repository and use Git as a means to distribute the project across spaces/landscape/systems. We don’t need to do anything special in Hybrid Application Toolkit to achieve this.

If you want to take this one step further and tie this into a Continuous Integration/Continuous Delivery (CI/CD) environment, then please take a look at this tutorial.

In this section I will provide answers to frequently asked questions, and I plan to update this once we receive more questions on a certain topic.

Is there a way to disable the certificate prompt on Android (X509)?

If you do not wish the user to see this screen, handling of client certificates can be disabled by simply adding the following line in config.xml:

<preference name="SAPKapselHandleX509Challenges" value="false" />

Why are there only a few UI5 versions available to select from, and why are some of those already out of maintenance?

We are not able to provide you any arbitrary version of UI5. We pick a version on an ad-hoc basis. It’s a snapshot. At the time we’ve picked those versions, they were relevant (in some cases, customers are even asking for it). If your app requires updates on UI5, you’ll have to rebuild your app with another version of UI5 (once available) and redistribute your app.

Why is my packaged app so big?

We package a large amount of UI5 libraries into the application. It is a curated list of libraries, but we have to ensure MOST apps work. If your app is not an offline app, I recommend you create a Fiori Client type of app instead. This kind of app will download the UI5 libraries from a frontend server and is able to cache this at runtime. The app will be much smaller and the UI5 version is controlled at the frontend server, instead of fixed in the app.

For my iOS app, I need to add settings in the Info.plist file. How can I do this for my project in SAP Web IDE?

Obviously, the Info.plist file is not available in the SAP Web IDE Full-Stack project. Using the config.xml file, you can pass settings to our Cloud Build Service, which will apply them in the Info.plist file that gets generated. You can add entries in the config.xml file by using the <config-file> element.


<platform name="ios"> <config-file target="*-Info.plist" parent="CFBundleURLTypes"> <array> <dict> <key>CFBundleURLSchemes</key> <array> <string>ABCDEF</string> <string>APP-NAME</string> </array> </dict> </array> </config-file> </platform> 

Another example, for solving problems with accessing the camera on iOS:

<platform name="ios"> <config-file parent="NSCameraUsageDescription" target="*-Info.plist"> <string>We are using a camera to scan barcodes.</string> </config-file> </platform>

When I build my app with SAP Mobile Services, the build succeeds but I don’t see the app nor the mobile destination created in the SAP Mobile Services cockpit.

You probably have multiple SAP Mobile Services subscriptions in your account. In this case the app was actually created in another SAP Mobile Services instance. Please change your mobileservices destination URL to “https://mobile-<account>.<landscape>”.

Example: your destination might point to “https://mobilepreview-<account>.<landscape>”. Similar issues can happen when using multiple landscapes for ‘sandbox’ ,’dev’ or ‘qa’.

Where did the Kapsel templates go?

In the first generation of SAP Web IDE (based on Eclipse Orion), we had introduced a number of application templates tailored towards mobile usage. These templates were basically copies of existing templates, with modifications for mobile. To avoid duplication of templates and the need for maintaining them, we have changed our approach and made sure a number of standard templates (e.g. CRUD, Master-Detail) available in SAP Web IDE can be used to create mobile apps. Therefore, the “Kapsel Templates” are no longer necessary.

I have an existing project based on the Kapsel Offline template. How do I build this project now that the HAT Local add-on is gone and I cannot enable this project for mobile ?

First of all, you can only build this kind of app using the HAT Local Add-on. The structure is not compatible with our Cloud Build Service. That’s why you cannot enable it for mobile, for building the app with our cloud build service.

You have two options:

  1. You can still build it using HAT local add-on; provided you have enabled the feature in the SAP Web IDE Full-Stack preferences AND you have installed the HAT local add-on tool. Take note that the latter is out of maintenance and therefore no longer supported and updated.
  2. You migrate the project to SAP Mobile Services on SAP Cloud Platform. If you were using on-premise SMP 3, then this will require changes in your landscape. If cloud services are not an option for you, then you have to stay with option 1.There are no tools available to help migrate your project. What you need to do, is create a new project in SAP Web IDE Full-Stack based on either the Fiori Master-Detail application template, or the Fiori CRUD application template. Then move all relevant code from your old project to the new one. Since every app is implemented differently, I cannot provide guidelines on what to do here. Your developers know what needs to move.Take note that using the Cloud Build Service, your app will be built with Kapsel 3.1 (or higher).

Is OAuth supported for authentication ?

Yes, OAuth is supported. However, by default the mobile app created/generated in SAP Mobile Services will use SAML. But you can change this in the SAP Mobile Services admin cockpit. Open the configuration of your app and navigate to Security. Here you can switch to OAuth and create a Client ID. Now, next time you trigger a Cloud Build from SAP Web IDE Full-Stack, the security settings will be retrieved from SAP Mobile Services and the project is updated accordingly.

Is it possible to create an offline app that consumes data from multiple systems ?

Yes, this is possible by creating multiple offline stores in your app and configuring the service root to consume the destinations that provide access to these systems. Please check this post, which has been updated to cover this topic.

My app starts up with a blank screen and hangs. Now what ?

This is a very common issue and requires you to investigate further before calling support. There are a few possible causes for failures during startup / initialisation of the app. It might be issues loading dependent libraries; it could be that it tries to access a service URL that doesn’t exist/respond; or various other causes.

Now what?: start debugging.

Connect to your app over USB (or wifi, for the pros) and check what errors the browser (Safari or Chrome) is reporting.

Check the logs on SAP Mobile Services Admin cockpit for connection issues.

Collect Network Traces on SAP Mobile Services Admin cockpit to identify what is going on.

Check the device logs.

Can I share the build results (url, QR code) with other users ?

Before confirming this, please take note that HAT is a tool targeting the developer flow. We do not support app distribution through this method.

The answer to the question is ‘Yes’. Users who have access to the same SAP Cloud Platform account can access the build results and download the app as well. Do take note that for iOS app distribution, Apple has implemented some restrictions. You can sign the app with an enterprise certificate and distribute within your organisation. However, it is not possible to distribute outside of your organisation.

For wider distribution on iOS, you have to publish the app in the Apple AppStore.

I am creating a B2C app and would like to know how to skip the logon screen.

Add the following line in the file <your project>/mobile/hybrid/sap-mobile-hybrid.js, before the sap.hybrid.kapsel.doLogonInit() function is called:

context.custom = { disablePasscode: true, skipRegistrationScreen: true };

For submitting our Android App into the Google Play store, we require the targetSdkVersion to be set to 28 (for Android 9). How can we change this?

In the config.xml file of your project, please find the following line and change the value to the required value:

<preference name="android-targetSdkVersion" value="26"/>

Take note that our Cloud Build Service needs to be able to handle the value set.

Does Hybrid Application Toolkit support developing apps targeting a Cloud Foundry environment?

My initial answer would be ‘No’, because this tool was built for Neo environments. However, with some manual steps (a workaround), it is possible to use SAP Mobile Services available on Cloud Foundry. This is explained here.

To be able to publish my iOS app in the App Store, I have to ensure it is not using or referencing UIWebView. How can I achieve this?

Currently, newly created apps will use WKWebView by default. I’ve also provided guidelines on what to do for existing apps. Details are available in this blog post. However, we will have to wait until a new release on the SAP Mobile SDK is available and used by our Cloud Build Service, before we can meet the requirements set by Apple.

In this section I will provide you with useful information that could help you in using SAP Web IDE and the HAT extension. I will update this section with new information, once it is available.

Avoiding download failures

If you are facing issues downloading your app or project archive while using the Chrome browser, please try using Firefox instead. Firefox is better than Chrome for resuming a broken downloading. Additional notes:

  • Before resuming the suspended download, please login to the SAP Mobile Service Admin cockpit to establish an authenticated session. The downloading link is protected by SAML2 authentication. If the logon session has timed out, resuming will not work.
  • Please do not close the browser during the suspend/resume. Resumable downloading will not work if you close the browser.
  • Before resuming the suspended download, please backup the partial files on disk. Sometimes the browser will automatically remove the partial file when a download is broken.

I will not be monitoring this blog very frequently, so in case you run into issues with our SAP Web IDE extension or Cloud Build Service triggered via SAP Web IDE, please raise a support ticket for component CA-WDE-MOB.

If you have questions, feel free to comment down below. Again, please don’t expect instant answers.


Ludo Noens – Product Owner, Hybrid Application Toolkit