Skip to content

Migration

There are changes to Mobile Development Kit as well as migration requirements to consider when you move from one version of Mobile Development Kit to the next.

Note

If you are upgrading minor or major version, make sure you follow the upgrade notes for each version higher than your current version. e.g. If you are upgrading from 3.2 to 4.2. Please follow the upgrade notes for 4.0, 4.1 and 4.2 (if any)

General Migration Tips

  • If you have previously make a clone of any files from the /MDKClient_SDK/App_SDK/template/app folder such as:

    • /App_Resources/Android/app.gradle
    • /App_Resources/iOS/build.xcconfig
    • Or others

    You must make sure to synchronize them with their newer versions from your new target Mobile Development Kit version.

Upgrading to 24.7

Migrate Button Table's and Its ButtonItem Rule Context

In Mobile Development Kit 24.7, the context for all the properties and events of the ButtonTable and its ButtonItem has been switched from SectionedTableProxy to ButtonTableButtonProxy.

SectionedTableProxy functions are dynamically added to ButtonTableButtonProxy at runtime to maintain backward compatibility. A warning log will be generated when a SectionedTableProxy function is used. These functions will soon be deprecated.

ButtonTableButtonProxy includes a redraw function. Invoking the context redraw() function will trigger the redraw function of the SectionedTableProxy to maintain backward compatibility.

Migrate SectionHeader, SectionFooter, and SectionHeaderItem Rule Context

The context for all the properties and events of the SectionHeader, SectionFooter, and SectionHeaderItem has been switched from SectionProxy inherited class to SectionHeaderProxy, SectionFooterProxy, and SectionHeaderItemProxy, respectively. These new proxy classes share the same base class ControlProxy.

SectionProxy functions are dynamically added to ControlProxy at runtime to maintain backward compatibility. A warning log will be generated when a SectionProxy function is used. These functions will soon be deprecated.

Following functions are present in both SectionProxy and ControlProxy:

  • getName
  • getType
  • getPageProxy
  • getParent
  • getVisible
  • setVisible

Invoking the above-mentioned functions will trigger the ControlProxy functions. Both SectionProxy and ControlProxy include a redraw function. Invoking the context redraw() function will trigger the redraw function of the SectionProxy.

Color Scheme for Banner Message Action

The default color scheme for the Banner Message Action has been updated to red (negative) and gray (normal). To continue displaying your banner in red, set the Semantic property to Negative.

Upgrading to 6.2

Migrate EncryptDatabase to SecureDatabaseEncryptionKey

In Mobile Development Kit 6.2, EncryptDatabase flag in BrandedSettings.json is no longer supported due to security consideration as setting EncryptDatabase to false is considered unsafe because it's generating unencrypted database. It has been replaced with SecureDatabaseEncryptionKey in BrandedSettings.json.

Setting SecureDatabaseEncryptionKey to true has the exact same result as setting EncryptDatabase to true. It will be securely encrypted.

Setting SecureDatabaseEncryptionKey to false will still encrypt the offline database but with a simple key MDK, so that you can use that key to debug the content of the database if needed or use them as demo database. You should not set this flag to false in production environment. It's meant to be used for development, debugging or demo purposes only.

Forward Compatibility

  • Encrypted offline databases generated with older Mobile Development Kit version will still work in Mobile Development Kit 6.2. This means any existing apps using encrypted offline database can be upgraded to Mobile Development Kit 6.2 without issue as long as SecureDatabaseEncryptionKey is also set to true in the new version of the app.
  • Unencrypted offline databases generated with older Mobile Development Kit version will no longer work in Mobile Development Kit 6.2, this includes demo database. They will need to be re-generated.

Demo Mode

If you have enabled demo mode for your existing app and has included demo offline database files in the demo folder, then you must regenerate your demo offline database files with SecureDatabaseEncryptionKey set to false and update them in the demo folder, unencrypted demo database files will no longer work in Mobile Development Kit 6.2.

Upgrading to 6.0

Custom Onboarding Logo on Android

To give you better control of customizing the onboarding logo, you can now specify layout height and width of your logo. To do that, you must specify those value if you have previously customize the logo.

For example, if this is your customlogo.xml from:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:android="http://schemas.android.com/apk/res/android">
  <style name="OnboardingLogo">
          <item name="android:src">@drawable/custom_icon</item>
  </style>
</resources>

You need to add the android:layout_width and android:layout_height to it as well:

<?xml version="1.0" encoding="utf-8"?>
<resources xmlns:android="http://schemas.android.com/apk/res/android">
  <style name="OnboardingLogo">
          <item name="android:src">@drawable/custom_icon</item>
          <item name="android:layout_width">wrap_content</item>
          <item name="android:layout_height">24dp</item>
  </style>
</resources>

Migrating Metadata

NativeScript 8 (used by Mobile Development Kit Client 6.0) introduces some prominent changes. To use it, you might need to update your metadata project.

For more information, see Metadata Migration.

Upgrading to 5.2

Onboarding Flow Upgrade on Android

We have improved our onboarding flow on Android. As part of this, when the client is upgraded to 5.2 version the user will be automatically redirected to onboarding login screen where they have to re-authenticate and re-generate the passcode. All the data remains intact and there will be no changes in the application behavior.

Upgrading to 5.0 or Newer

Deprecating OData Initialization Actions

  • Offline OData Initialize (Action.Type.OfflineOData.Initialize)
  • OData Service Create (Action.Type.ODataService.Create)
  • OData Service Open (Action.Type.ODataService.Open)

These are now unified into a single action: OData Service Initialize (Action.Type.ODataService.Initialize).

This new action can be used to initialize both offline or online OData service.

Deprecating font-color Styling Property

  • font-color is now deprecated and is replaced with color

Upgrading to 4.3 or Newer

ClientAPI.sendMobileServiceRequest function is deprecated and should not be used anymore.

It has been replaced by ClientAPI.sendRequest which has the same functionality.

Upgrading to 4.2 or Newer

Migrating Mobile Development Kit Modules Import

If you have imported Mobile Development Kit client's classes via relative path such as:

import { IControl } from './controls/IControl';

// or
import { IControl } from '../../controls/IControl';

// or
import { IView } from './controls/IView';

// and so on

These should be migrated to use mdk-core module:

import { IControl } from 'mdk-core/controls/IControl';
import { IView } from 'mdk-core/controls/IView';

Upgrading to 4.0 or Newer

Upgrading NativeScript Full Path Import

With NativeScript 6.0 or newer, you must use fully qualified module path for tns-core-modules imports.

For example:

Before version 4.0, you can write import with short path:

import * as fs from 'file-system';

In version 4.0 or newer, you must write import with fully qualified path:

import * as fs from 'tns-core-modules/file-system';

Using Built-in NativeScript Framework Modules

If you are importing the following NativeScript modules in your rules:

  • tns-core-modules/application-settings
  • tns-core-modules/connectivity
  • tns-core-modules/file-system
  • tns-core-modules/platform
  • tns-core-modules/ui/dialogs
  • tns-core-modules/utils/utils

These 6 modules are now part of the ClientAPI and you can access them via ClientAPI.nativescript.

You should now migrate and use them via ClientAPI.nativescript.<modulename>

e.g. ClientAPI.nativescript.appSettingsModule

For more details please see NativeScript Framework Modules


Last update: July 15, 2024